Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/content/influxdb3/cloud-serverless/write-data/api/v1-http.md

14 KiB
Raw Permalink Blame History

title seotitle list_title description weight menu influxdb3/cloud-serverless/tags metadata related list_code_example
Use the InfluxDB v1 HTTP write API Use the v1 write API Use the v1 write API Use the InfluxDB v1 HTTP write API to write data stored in InfluxDB Cloud Serverless. 301
influxdb3_cloud_serverless
parent name
Write data Use the v1 HTTP write API
query
influxql
python
InfluxQL
/influxdb3/cloud-serverless/guides/api-compatibility/v1/
/influxdb3/cloud-serverless/reference/client-libraries/v1/
```sh curl "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \ --header "Authorization: Token API_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1463683075' ```

Use the InfluxDB v1 HTTP API /write endpoint and InfluxQL to write data stored in {{< product-name >}}. The /write endpoint provides compatibility for InfluxDB 1.x workloads that you bring to InfluxDB 3.

The v1 write and query APIs require mapping databases and retention policies to buckets.

Map databases and retention policies to buckets

The v1 write and query APIs require mapping databases and retention policies to buckets.

InfluxDB can autogenerate a bucket and DBRP mapping for a write request or you can create a bucket and DBRP before writing.

Autogenerate a bucket and DBRP mapping

To let InfluxDB autogenerate a bucket and an associated DBRP mapping, pass the following parameters when writing data to the v1 /write endpoint:

If no bucket exists with the name DATABASE_NAME/RETENTION_POLICY_NAME, InfluxDB creates a bucket and a DBRP before writing the data to the bucket.

To learn more about DBRP mapping, see the v1 API compatibility guide.

Create a bucket and DBRP mapping

To create a DBRP for a bucket:

  1. If it doesn't already exist, create the bucket that you want to write to.
  2. Find the bucket ID for the bucket that you want to write to.
  3. Create a DBRP, which maps a database name and retention policy name to the bucket ID from the preceding step.

If the db=DATABASE_NAME and rp=RETENTION_POLICY parameters in your /write request map to an existing DBRP, InfluxDB writes to the mapped bucket.

Write to the v1 HTTP /write endpoint

{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" %}}

Parameters

For {{% product-name %}} v1 API /write requests, set parameters as listed in the following table:

Parameter Allowed in Ignored Value
consistency Query string Ignored N/A
db {{% req " *" %}} Query string Honored Database (see how to map databases and retention policies to buckets)
precision Query string Honored Timestamp precision
rp Query string Honored Retention policy (see how to map databases and retention policies to buckets)
Authorization header or u and p Token

{{% caption %}}{{% req " *" %}} = {{% req "Required" %}}{{% /caption %}}

Timestamp precision

Use one of the following precision values in v1 API /write requests:

  • ns: nanoseconds
  • us: microseconds
  • ms: milliseconds
  • s: seconds
  • m: minutes
  • h: hours

Data

In the request body, include the line protocol data that you want to write to the bucket.

Authorization

To authorize writes to an existing bucket, include a token that has write permission to the bucket. Use Token authentication or v1-compatible username and password authentication to include a token in the request.

For InfluxDB to autogenerate the bucket and DBRP, you must use a token, such as an All-access token, that has write permissions to buckets and DBRPs.

Tools for writing to the v1 API

When using the v1 API and associated tooling, pass the DBRP mapping's database name and retention policy name in the request parameters.

The following tools work with the {{% product-name %}} /write endpoint:

Telegraf

If you have existing v1 workloads that use Telegraf, you can use the InfluxDB v1.x influxdb Telegraf output plugin to write data.

{{% note %}} See how to use Telegraf and the v2 API for new workloads that don't already use the v1 API. {{% /note %}}

The following table shows outputs.influxdb plugin parameters and values for writing to the {{% product-name %}} v1 API:

Parameter Ignored Value
database Honored Bucket name
retention_policy Honored Duration
username Ignored String or empty
password Honored API token with permission to write to the bucket
content_encoding Honored gzip (compressed data) or identity (uncompressed)
skip_database_creation Ignored N/A (see how to create a bucket)

To configure the v1.x output plugin for writing to {{% product-name %}}, add the following outputs.influxdb configuration in your telegraf.conf file:

{{% code-placeholders "API_TOKEN|RETENTION_POLICY" %}}

[[outputs.influxdb]]
  urls = ["https://{{< influxdb/host >}}"]
  database = "DATABASE_NAME"
  skip_database_creation = true
  retention_policy = "RETENTION_POLICY"
  username = "ignored"
  password = "API_TOKEN"
  content_encoding = "gzip”

{{% /code-placeholders %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the database
  • {{% code-placeholder-key %}}RETENTION_POLICY{{% /code-placeholder-key %}}: the retention policy
  • {{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token with sufficient permissions to the mapped bucket
Other Telegraf configuration options

influx_uint_support: supported in InfluxDB 3.

For more plugin options, see influxdb on GitHub.

Interactive clients

To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman.

{{% note %}} For production use cases, use tools such as client libraries that construct line protocol for you and provide batch writing options. {{% /note %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} Token Auth Basic Auth Query String Auth {{% /code-tabs %}} {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}

curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
    --header "Authorization: Token API_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1463683075'

{{% /code-placeholders %}} {{% /code-tab-content %}} {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}

curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
    -user "ignored":"API_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1463683075'

{{% /code-placeholders %}} {{% /code-tab-content %}} {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}

curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-urlencode "u=ignored" \
    --data-urlencode "p=DATABASE_TOKEN" \
    --data-binary 'home,room=kitchen temp=72 1463683075'

{{% /code-placeholders %}} {{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the database
  • {{% code-placeholder-key %}}RETENTION_POLICY{{% /code-placeholder-key %}}: the retention policy
  • {{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token with sufficient permissions to the mapped bucket

v1 influx CLI (not supported)

Don't use the v1 influx CLI with {{% product-name %}}. While it may coincidentally work, it isn't officially supported.

Client libraries

Use language-specific v1 client libraries and your custom code to write data to InfluxDB. v1 client libraries send data in line protocol syntax to the v1 API /write endpoint.

The following samples show how to configure v1 client libraries for writing to {{% product-name %}}:

{{< tabs-wrapper >}} {{% tabs %}} Node.js Python {{% /tabs %}} {{% tab-content %}}

Create a v1 API client using the node-influx JavaScript client library:

{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}

const Influx = require('influx')

// Instantiate a client for writing to {{% product-name %}} v1 API
const client = new Influx.InfluxDB({
  host: '{{< influxdb/host >}}',
  port: 443,
  protocol: 'https'
  database: 'BUCKET_NAME',
  username: 'ignored',
  password: 'API_TOKEN'
})

// When calling write or query functions, specify the retention policy name in options.

{{% /code-placeholders %}}

{{% /tab-content %}} {{% tab-content %}}

Create a v1 API client using the influxdb-python Python client library:

{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}

from influxdb import InfluxDBClient

# Instantiate a client for writing to {{% product-name %}} v1 API
client = InfluxDBClient(
  host='{{< influxdb/host >}}',
  ssl=True,
  database='DATABASE_NAME',
  username='',
  password='API_TOKEN'
  headers={'Content-Type': 'text/plain; charset=utf-8'}
  )

# When calling write or query functions, specify the retention policy name in options.

{{% /code-placeholders %}}

{{% /tab-content %}} {{< /tabs-wrapper >}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the database
  • {{% code-placeholder-key %}}RETENTION_POLICY{{% /code-placeholder-key %}}: the retention policy
  • {{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token with sufficient permissions to the specified bucket