Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix/2759 1.x query api (#2841) 

* fix: 1.x compat api. Clarify authentication schemes, parameters, and use cases for OSS and Cloud (#2759)

* fix: curl examples

* update: add node.js examples

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/2855/head
Jason Stirnaman 2021-07-14 16:59:39 -05:00 committed by GitHub
parent ad06069f2c
commit 9bb3340b02
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 790 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
assets/js/influxdb-url.js
View File

@ -110,14 +110,46 @@ function getPrevUrls() {
// Iterate through code blocks and update InfluxDB urls
// Requires objects with cloud and oss keys and url values
function updateUrls(prevUrls, newUrls) {
var preference = getPreference()
var prevUrlsParsed = {
cloud: {},
oss: {}
}
var newUrlsParsed = {
cloud: {},
oss: {}
}
Object.keys(prevUrls).forEach(function(k) {
try {
prevUrlsParsed[k] = new URL(prevUrls[k])
} catch {
prevUrlsParsed[k] = { host: prevUrls[k] }
}
})
Object.keys(newUrls).forEach(function(k) {
try {
newUrlsParsed[k] = new URL(newUrls[k])
} catch {
newUrlsParsed[k] = { host: newUrls[k] }
}
})
/**
* Match and replace <prev> host with <new> host
* then replace <prev> URL with <new> URL.
**/
var cloudReplacements = [
{ replace: prevUrls.cloud, with: newUrls.cloud},
{ replace: prevUrls.oss, with: newUrls.cloud }
{ replace: prevUrlsParsed.cloud.host, with: newUrlsParsed.cloud.host },
{ replace: prevUrlsParsed.oss.host, with: newUrlsParsed.cloud.host },
{ replace: prevUrls.cloud, with: newUrls.cloud },
{ replace: prevUrls.oss, with: newUrls.cloud },
]
var ossReplacements = [
{ replace: prevUrlsParsed.cloud.host, with: newUrlsParsed.cloud.host },
{ replace: prevUrlsParsed.oss.host, with: newUrlsParsed.oss.host },
{ replace: prevUrls.cloud, with: newUrls.cloud},
{ replace: prevUrls.oss, with: newUrls.oss }
]
@ -164,7 +196,7 @@ function appendUrlSelector() {
///////////////////////////// Function executions //////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Add the preserve tag to code blocks that shouldn't be udpated
// Add the preserve tag to code blocks that shouldn't be updated
addPreserve()
// Append URL selector buttons to code blocks
@ -358,4 +390,4 @@ if (cloudUrls.includes(referrerHost)) {
setRadioButtons()
setPreference("cloud")
showPreference()
}
}

36
assets/text/api/v1-compat/auth/cloud/basic-auth.js Normal file
View File

@ -0,0 +1,36 @@
/**
* Use an InfluxDB Cloud username and token
* with Basic Authentication
* to query the InfluxDB 1.x compatibility API
*/
const https = require('https');
const querystring = require('querystring');
function queryWithUsername() {
const queryparams = {
db: 'mydb',
q: 'SELECT * FROM cpu_usage',
};
const options = {
host: 'localhost:8086',
path: '/query?' + querystring.stringify(queryparams),
auth: 'exampleuser@influxdata.com:YourAuthToken',
headers: {
'Content-type': 'application/json'
},
};
const request = https.get(options, (response) => {
let rawData = '';
response.on('data', () => {
response.on('data', (chunk) => { rawData += chunk; });
})
response.on('end', () => {
console.log(rawData);
})
});
request.end();
}

16
assets/text/api/v1-compat/auth/cloud/basic-auth.sh Normal file
View File

@ -0,0 +1,16 @@
#######################################
# Use an InfluxDB 1.x compatible username
# and password with Basic Authentication
# to query the InfluxDB 1.x compatibility API
#######################################
# Use default retention policy
#######################################
# Use the --user option with `--user <username>:<password>` syntax
# or the `--user <username>` interactive syntax to ensure your credentials are
# encoded in the header.
#######################################
curl --get "http://localhost:8086/query" \
--user "OneDotXUsername":"YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT * FROM cpu_usage"

37
assets/text/api/v1-compat/auth/oss/basic-auth.js Normal file
View File

@ -0,0 +1,37 @@
/**
* Use an InfluxDB 1.x compatible username and password
* to query the InfluxDB 1.x compatibility API
*
* Use Basic authentication
*/
const https = require('https');
const querystring = require('querystring');
function queryWithUsername() {
const queryparams = {
db: 'mydb',
q: 'SELECT * FROM cpu_usage',
};
const options = {
host: 'localhost:8086',
path: '/query?' + querystring.stringify(queryparams),
auth: 'OneDotXUsername:yourPasswordOrToken',
headers: {
'Content-type': 'application/json'
},
};
const request = https.get(options, (response) => {
let rawData = '';
response.on('data', () => {
response.on('data', (chunk) => { rawData += chunk; });
})
response.on('end', () => {
console.log(rawData);
})
});
request.end();
}

16
assets/text/api/v1-compat/auth/oss/basic-auth.sh Normal file
View File

@ -0,0 +1,16 @@
#######################################
# Use an InfluxDB 1.x compatible username
# and password with Basic Authentication
# to query the InfluxDB 1.x compatibility API
#######################################
# Use default retention policy
#######################################
# Use the --user option with `--user <username>:<password>` syntax
# or the `--user <username>` interactive syntax to ensure your credentials are
# encoded in the header.
#######################################
curl --get "http://localhost:8086/query" \
--user "OneDotXUsername":"yourPasswordOrToken" \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT * FROM cpu_usage"

38
assets/text/api/v1-compat/auth/oss/querystring-auth.js Normal file
View File

@ -0,0 +1,38 @@
/**
* Use an InfluxDB 1.x compatible username and password
* to query the InfluxDB 1.x compatibility API
*
* Use authentication query parameters:
* ?u=<username>&p=<password>
*
* Use default retention policy.
*/
const https = require('https');
const querystring = require('querystring');
function queryWithToken() {
const queryparams = {
db: 'mydb',
q: 'SELECT * FROM cpu_usage',
u: 'OneDotXUsername',
p: 'yourPasswordOrToken'
};
const options = {
host: 'localhost:8086',
path: "/query?" + querystring.stringify(queryparams)
};
const request = https.get(options, (response) => {
let rawData = '';
response.on('data', () => {
response.on('data', (chunk) => { rawData += chunk; });
})
response.on('end', () => {
console.log(rawData);
})
});
request.end();
}

14
assets/text/api/v1-compat/auth/oss/querystring-auth.sh Normal file
View File

@ -0,0 +1,14 @@
#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB 1.x compatibility API
#######################################
# Use authentication query parameters:
# ?u=<username>&p=<password>
# Use default retention policy.
#######################################
curl --get "http://localhost:8086/query" \
--data-urlencode "u=OneDotXUsername" \
--data-urlencode "p=yourPasswordOrToken" \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT * FROM cpu_usage"

35
assets/text/api/v1-compat/auth/oss/token-auth.js Normal file
View File

@ -0,0 +1,35 @@
/**
* Use a token in the Authorization header
* to query the InfluxDB 1.x compatibility API
*/
const https = require('https');
const querystring = require('querystring');
function queryWithToken() {
const queryparams = {
db: 'mydb',
q: 'SELECT * FROM cpu_usage',
};
const options = {
host: 'localhost:8086',
path: "/query?" + querystring.stringify(queryparams),
headers: {
'Authorization': 'Token YourAuthToken',
'Content-type': 'application/json'
},
};
const request = https.get(options, (response) => {
let rawData = '';
response.on('data', () => {
response.on('data', (chunk) => { rawData += chunk; });
})
response.on('end', () => {
console.log(rawData);
})
});
request.end();
}

10
assets/text/api/v1-compat/auth/oss/token-auth.sh Normal file
View File

@ -0,0 +1,10 @@
#######################################
# Use a token in the Authorization header
# to query the InfluxDB 1.x compatibility API
#######################################
curl --get "http://localhost:8086" \
--header "Authorization: Token YourAuthToken" \
--header 'Content-type: application/json' \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT * FROM cpu_usage"

12
content/influxdb/cloud/query-data/influxql.md
View File

@ -18,7 +18,7 @@ related:
In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database)
and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
In InfluxDB Cloud, data is stored in [buckets](/influxdb/cloud/reference/glossary/#bucket).
Because InfluxQL uses the 1.x data model, before querying in InfluxQL, a bucket must be mapped to a database and retention policy (DBRP).
Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL.
{{% note %}}
#### InfluxQL reference documentation
@ -26,7 +26,7 @@ For complete InfluxQL reference documentation, see
[Influx Query Language in the latest InfluxDB 1.x documentation](/{{< latest "influxdb" "v1" >}}/query_language/).
{{% /note %}}
**Complete the following steps:**
**To use InfluxQL to query bucket data, complete the following steps:**
1. [Verify buckets have a mapping](#verify-buckets-have-a-mapping).
2. [Map unmapped buckets](#map-unmapped-buckets).
@ -126,11 +126,9 @@ Include the following in your request:
- **Query parameters:**
- **db**: 1.x database to query
- **rp**: 1.x retention policy to query _(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)_
- **q**: InfluxQL query
- **q**: URL-encoded InfluxQL query
{{% note %}}
**URL-encode** the InfluxQL query to ensure it's formatted correctly when submitted to InfluxDB.
{{% /note %}}
{{% api/url-encode-note %}}
```sh
curl --get https://cloud2.influxdata.com/query?db=example-db \
@ -178,4 +176,4 @@ To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest
- `REVOKE`
{{% /warn %}}
{{< /flex-content >}}
{{< /flex >}}
{{< /flex >}}

2
content/influxdb/cloud/reference/api/_index.md
View File

@ -12,7 +12,7 @@ The InfluxDB v2 API provides a programmatic interface for interactions with Infl
Access the InfluxDB API using the `/api/v2/` endpoint.
## Authentication
InfluxDB uses [authentication tokens](/influxdb/cloud/security/tokens/) to authorize API requests.
{{% cloud-token-auth %}}
Include your authentication token as an `Authorization` header in each request.
```sh

116
content/influxdb/cloud/reference/api/influxdb-1x/_index.md
View File

@ -21,41 +21,127 @@ like [Grafana](https://grafana.com) and others.
<a class="btn" href="/influxdb/cloud/api/v1-compatibility/">View full v1 compatibility API documentation</a>
## Authentication
InfluxDB Cloud all query and write requests to be authenticated using
{{% cloud %}}
InfluxDB Cloud requires all query and write requests to be authenticated using
[InfluxDB authentication tokens](/influxdb/cloud/security/tokens/).
Use the following authenication methods:
{{% /cloud %}}
- [Token authentication](#token-authentication)
- [Basic authentication](#basic-authentication)
Use InfluxDB authentication tokens with the following authentication schemes:
### Token authentication
* [Authenticate with the Token scheme](#authenticate-with-the-token-scheme)
* [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
### Authenticate with the Token scheme
Token authentication requires the following credential:
- **token**: InfluxDB [authentication token](/influxdb/cloud/security/tokens/)
Use the `Authorization` header with the `Token` scheme to provide your
authentication token to InfluxDB.
token to InfluxDB.
##### Token authentication with authorization header
##### Syntax
```sh
# Header syntax
Authorization: Token <token>
# Header example
Authorization: Token mYSuP3rs3cREtT0k3N
```
### Basic authentication
Basic authentication requires the following credentials:
##### Example
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{% get-assets-text "api/v1-compat/auth/oss/token-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/oss/token-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
### Authenticate with a username and password scheme
Use the following schemes with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
- [Basic authentication](#basic-authentication)
- [Query string authentication](#query-string-authentication)
##### Manage credentials
Username and password schemes require the following credentials:
- **username**: InfluxDB Cloud username
- **password**: InfluxDB Cloud [authentication token](/influxdb/cloud/security/tokens/)
#### Basic authentication
Use the `Authorization` header with the `Basic` scheme to provide username and password credentials to InfluxDB.
{{% api/v1-compat/basic-auth-syntax %}}
##### Syntax
```sh
# --user syntax
<username>:<password>
Authorization: Basic <username>:<password>
```
##### Example
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{% get-assets-text "api/v1-compat/auth/oss/basic-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/cloud/basic-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
#### Query string authentication
Use InfluxDB 1.x API parameters to provide username and password credentials through the query string.
{{% note %}}
##### Consider when using query string parameters
- URL-encode query parameters that may contain whitespace or other special characters.
- Be aware of the [risks](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) when exposing sensitive data through URLs.
{{% /note %}}
##### Syntax
```sh
/query/?u=<username>&p=<password>
/write/?u=<username>&p=<password>
```
##### Example
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{% get-assets-text "api/v1-compat/auth/oss/querystring-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/oss/querystring-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
## InfluxQL support
The compatibility API supports InfluxQL, with the following caveats:

119
content/influxdb/cloud/reference/api/influxdb-1x/query.md
View File

@ -18,4 +18,121 @@ related:
- /influxdb/cloud/query-data/influxql
---
{{< duplicate-oss >}}
The `/query` 1.x compatibility endpoint queries InfluxDB Cloud and InfluxDB OSS 2.0 using **InfluxQL**.
Use the `GET` request method to query data from the `/query` endpoint.
{{< api-endpoint method="get" endpoint="http://localhost:8086/query" >}}
The `/query` compatibility endpoint uses the **database** and **retention policy**
specified in the query request to map the request to an InfluxDB bucket.
For more information, see [Database and retention policy mapping](/{{% latest "influxdb" %}}/reference/api/influxdb-1x/dbrp).
{{% note %}}
If you have an existing bucket that doesn't follow the **database/retention-policy** naming convention,
you **must** [manually create a database and retention policy mapping](/influxdb/v2.0/query-data/influxql/#map-unmapped-buckets)
to query that bucket with the `/query` compatibility API.
{{% /note %}}
## Authentication
{{% api/v1-compat/cloud/authentication %}}
## Query string parameters
{{% api/url-encode-note %}}
### u
(Optional) The InfluxDB Cloud **username** to authenticate the request.
_See [query string authentication](/influxdb/cloud/reference/api/influxdb-1x/#query-string-authentication)._
### p
(Optional) The InfluxDB Cloud **authentication token** to authenticate the request.
_See [query string authentication](/influxdb/cloud/reference/api/influxdb-1x/#query-string-authentication)._
### db
({{< req >}}) The **database** to query data from.
This is mapped to an InfluxDB [bucket](/influxdb/v2.0/reference/glossary/#bucket).
_See [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/)._
### rp
The **retention policy** to query data from.
This is mapped to an InfluxDB [bucket](/influxdb/v2.0/reference/glossary/#bucket).
_See [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/)._
### q
({{< req >}}) The **InfluxQL** query to execute.
To execute multiple queries, delimit queries with a semicolon (`;`).
### epoch
Return results with [Unix timestamps](/influxdb/v2.0/reference/glossary/#unix-timestamp)
(also known as epoch timestamps) in the specified precision instead of
[RFC3339 timestamps](/influxdb/v2.0/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
The following precisions are available:
- `ns` - nanoseconds
- `u` or `µ` - microseconds
- `ms` - milliseconds
- `s` - seconds
- `m` - minutes
- `h` - hours
## Query examples
- [Query using basic authentication](#query-using-basic-authentication)
- [Query a non-default retention policy](#query-a-non-default-retention-policy)
- [Execute multiple queries](#execute-multiple-queries)
- [Return query results with millisecond Unix timestamps](#return-query-results-with-millisecond-unix-timestamps)
- [Execute InfluxQL queries from a file](#execute-influxql-queries-from-a-file)
##### Query using basic authentication
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{% get-assets-text "api/v1-compat/auth/cloud/basic-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/cloud/basic-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
##### Query a non-default retention policy
```sh
curl --get http://localhost:8086/query \
--header "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "rp=customrp" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
```
##### Execute multiple queries
```sh
curl --get http://localhost:8086/query \
--header "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT * FROM mem WHERE host=host1;SELECT mean(used_percent) FROM mem WHERE host=host1 GROUP BY time(10m)"
```
##### Return query results with millisecond Unix timestamps
```sh
curl --get http://localhost:8086/query \
--header "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "rp=myrp" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" \
--data-urlencode "epoch=ms"
```
##### Execute InfluxQL queries from a file
```sh
curl --get http://localhost:8086/query \
--header "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
--form "q=@path/to/influxql.txt" \
--form "async=true"
```

107
content/influxdb/cloud/reference/api/influxdb-1x/write.md
View File

@ -19,4 +19,109 @@ related:
- /influxdb/cloud/reference/syntax/line-protocol
---
{{< duplicate-oss >}}
The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and InfluxDB OSS 2.0
using patterns from the InfluxDB 1.x `/write` API endpoint.
Use the `POST` request method to write [line protocol](/influxdb/cloud/reference/syntax/line-protocol/)
to the `/write` endpoint.
{{< api-endpoint method="post" endpoint="https://cloud2.influxdata.com/write" >}}
{{% note %}}
If you have an existing bucket that doesn't follow the **database/retention-policy** naming convention,
you **must** [manually create a database and retention policy mapping](/influxdb/cloud/query-data/influxql/#map-unmapped-buckets)
to write data to that bucket with the `/write` compatibility API.
{{% /note %}}
## Authentication
{{% api/v1-compat/cloud/authentication %}}
## Request body
Include your line protocol in the request body.
**Binary encode** the line protocol to prevent unintended formatting.
The examples [below](#write-examples) use the curl `--data-binary` flag to binary
encode the line protocol.
## Query string parameters
### u
(Optional) The InfluxDB Cloud **username** to authenticate the request.
_See [query string authentication](/influxdb/cloud/reference/api/influxdb-1x/#query-string-authentication)._
### p
(Optional) The InfluxDB Cloud **authentication token** to authenticate the request.
_See [query string authentication](/influxdb/cloud/reference/api/influxdb-1x/#query-string-authentication)._
### db
({{< req >}}) The **database** to write data to.
This is mapped to an InfluxDB [bucket](/influxdb/cloud/reference/glossary/#bucket).
_See [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/)._
### rp
The **retention policy** to write data to.
This is mapped to an InfluxDB [bucket](/influxdb/cloud/reference/glossary/#bucket).
_See [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/)._
### precision
The precision of [Unix timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) in the line protocol.
Default is nanosconds (`ns`).
The following precisions are available:
- `ns` - nanoseconds
- `u` or `µ` - microseconds
- `ms` - milliseconds
- `s` - seconds
- `m` - minutes
- `h` - hours
## Write examples
- [Write data using basic authentication](#write-data-using-basic-authentication)
- [Write data to a non-default retention policy](#write-data-to-a-non-default-retention-policy)
- [Write multiple lines of line protocol](#write-multiple-lines-of-line-protocol)
- [Write data with millisecond Unix timestamps](#write-data-with-millisecond-unix-timestamps)
- [Use curl to write data from a file](#use-curl-to-write-data-from-a-file)
##### Write data using basic authentication
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
--user "myusername:YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write data using token authentication
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
--header "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write data to a non-default retention policy
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb&rp=customrp \
--user "myusername:YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write multiple lines of line protocol
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
--header "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000
measurement,host=host2 field1=14i,field2=12.7 1577836800000000000
measurement,host=host3 field1=5i,field2=6.8 1577836800000000000"
```
##### Write data with millisecond Unix timestamps
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb&precision=ms \
--header "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000"
```
##### Use curl to write data from a file
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
--header "Authorization: Token YourAuthToken" \
--data-binary @path/to/line-protocol.txt
```

2
content/influxdb/cloud/upgrade/v1-to-cloud/_index.md
View File

@ -31,7 +31,7 @@ Do one of the following to create an InfluxDB Cloud account:
- [Subscribe through your cloud provider](/influxdb/cloud/get-started/#subscribe-through-a-cloud-provider).
## Create an All-Access authentication token
InfluxDB Cloud requires all requests to be authenticated with **token authentication**.
{{% cloud-token-auth %}}
Create an **All-Access** token in your InfluxDB Cloud user interface (UI) to use
for the upgrade process.

2
content/influxdb/v1.8/administration/authentication_and_authorization.md
View File

@ -143,7 +143,7 @@ Connected to http://localhost:8086 version 1.4.x
InfluxDB shell 1.4.x
```
##### Authenticate with credentials in the influx sheel
##### Authenticate with credentials in the influx shell
Start the `influx` shell and run the `auth` command.
Enter your username and password when prompted.

16
content/influxdb/v2.0/install.md
View File

@ -134,6 +134,22 @@ To manually authorize the InfluxDB binaries:
We are in the process of updating our build process to ensure released binaries are signed by InfluxData.
{{% /warn %}}
{{% warn %}}
#### "too many open files" errors
After running `influxd`, you might see an error in the log output like the
following:
```sh
too many open files
```
To resolve this error, follow the
[recommended steps](https://unix.stackexchange.com/a/221988/471569) to increase
file and process limits for your operating system version then restart `influxd`.
{{% /warn %}}
_See the [`influxd` documentation](/influxdb/v2.0/reference/cli/influxd) for information about
available flags and options._

14
content/influxdb/v2.0/query-data/influxql.md
View File

@ -18,7 +18,7 @@ related:
In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database)
and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
In InfluxDB OSS 2.0, data is stored in [buckets](/influxdb/v2.0/reference/glossary/#bucket).
Because InfluxQL uses the 1.x data model, before querying in InfluxQL, a bucket must be mapped to a database and retention policy (DBRP).
Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL.
{{% note %}}
#### InfluxQL reference documentation
@ -26,7 +26,7 @@ For complete InfluxQL reference documentation, see
[Influx Query Language in the latest InfluxDB 1.x documentation](/{{< latest "influxdb" "v1" >}}/query_language/).
{{% /note %}}
**Complete the following steps:**
**To use InfluxQL to query bucket data, complete the following steps:**
1. [Verify buckets have a mapping](#verify-buckets-have-a-mapping).
2. [Map unmapped buckets](#map-unmapped-buckets).
@ -36,7 +36,7 @@ For complete InfluxQL reference documentation, see
{{% note %}}
When [upgrading from InfluxDB 1.x to 2.0](/influxdb/v2.0/upgrade/v1-to-v2/),
Database and retention policy combinations are mapped to InfluxDB 2.0 buckets.
database and retention policy combinations are mapped to InfluxDB 2.0 buckets.
For more information, see [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/).
If you're not sure how data was written into a bucket, verify the bucket has a mapping.
{{% /note %}}
@ -197,11 +197,9 @@ Include the following in your request:
- **Query parameters:**
- **db**: 1.x database to query
- **rp**: 1.x retention policy to query _(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)_
- **q**: InfluxQL query
- **q**: URL-encoded InfluxQL query
{{% note %}}
**URL-encode** the InfluxQL query to ensure it's formatted correctly when submitted to InfluxDB.
{{% /note %}}
{{% api/url-encode-note %}}
```sh
curl --get http://localhost:8086/query?db=example-db \
@ -249,4 +247,4 @@ To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest
- `REVOKE`
{{% /warn %}}
{{< /flex-content >}}
{{< /flex >}}
{{< /flex >}}

148
content/influxdb/v2.0/reference/api/influxdb-1x/_index.md
View File

@ -20,47 +20,135 @@ InfluxDB 1.x client libraries and third-party integrations like [Grafana](https:
<a class="btn" href="/influxdb/v2.0/api/v1-compatibility/">View full v1 compatibility API documentation</a>
## Authentication
InfluxDB 2.0 requires all query and write requests to be authenticated.
Use **1.x-compatible authorizations** or **token authentication** to authenticate
requests to InfluxDB 1.x compatibility endpoints.
InfluxDB 2.0 requires all query and write requests to be authenticated with an
[authentication token](/influxdb/v2.0/security/tokens/) or 1.x compatible
credentials.
### 1.x-compatible authorizations
Include the following credentials in your 1.x-compatible authorizations:
* [Authenticate with the Token scheme](#authenticate-with-the-token-scheme)
* [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
- **username**: InfluxDB 1.x username
- **password**: InfluxDB 1.x password
For information about creating and managing 1.x-compatible authorizations, see:
- [influx v1 auth](/influxdb/v2.0/reference/cli/influx/v1/auth/)
- [Manually upgrade – 1.x-compatible authorizations](/influxdb/v2.0/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations)
There are multiple ways to provide 1.x-compatible authorization credentials to InfluxDB 2.0.
When providing the 1.x-compatible username and password, use the following syntax for basic authentication (or include the `-u` and `-p` parameters in your request).
##### Basic authentication
```sh
# --user syntax
<username>:<password>
```
### Token Authentication
### Authenticate with the Token scheme
Token authentication requires the following credential:
- **token**: InfluxDB [authentication token](/influxdb/v2.0/security/tokens/)
Use the `Authorization` header with the `Token` scheme to provide your
authentication token to InfluxDB.
Use the `Authorization` header with the `Token` scheme to provide your token to InfluxDB.
#### Syntax
##### Token authentication with authorization header
```sh
# Header syntax
Authorization: Token <token>
# Header example
Authorization: Token mYSuP3rs3cREtT0k3N
```
#### Example
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{% get-assets-text "api/v1-compat/auth/oss/token-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/oss/token-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
### Authenticate with a username and password scheme
Use the following authentication schemes with clients that support the InfluxDB 1.x convention of `username` and `password` (that don't support the `Authorization: Token` scheme):
- [Basic authentication](#basic-authentication)
- [Query string authentication](#query-string-authentication)
##### Manage credentials
Username and password schemes require the following credentials:
- **username**: 1.x username (this is separate from the UI login username)
- **password**: 1.x password or InfluxDB authentication token.
{{% note %}}
#### Password or Token
{{% api/v1-compat/oss/password-or-token %}}
{{% /note %}}
For information about creating and managing 1.x-compatible authorizations, see:
- [`influx v1 auth` command](/influxdb/v2.0/reference/cli/influx/v1/auth/)
- [Manually upgrade – 1.x-compatible authorizations](/influxdb/v2.0/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations)
#### Basic authentication
Use the `Authorization` header with the `Basic` scheme to provide username and
password credentials to InfluxDB.
{{% api/v1-compat/basic-auth-syntax %}}
##### Syntax
```sh
Authorization: Basic <username>:<password>
```
##### Example
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{% get-assets-text "api/v1-compat/auth/oss/basic-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/oss/basic-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
#### Query string authentication
Use InfluxDB 1.x API parameters to provide credentials through the query string.
{{% note %}}
##### Consider when using query string parameters
- URL-encode query parameters that may contain whitespace or other special characters.
- Be aware of the [risks](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) when exposing sensitive data through URLs.
{{% /note %}}
##### Syntax
```sh
/query/?u=<username>&p=<password>
/write/?u=<username>&p=<password>
```
##### Example
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
{{< get-assets-text "api/v1-compat/auth/oss/querystring-auth.sh" >}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{< get-assets-text "api/v1-compat/auth/oss/querystring-auth.js" >}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
##### InfluxQL support
The compatibility API supports InfluxQL, with the following caveats:

41
content/influxdb/v2.0/reference/api/influxdb-1x/query.md
View File

@ -24,7 +24,7 @@ Use the `GET` request method to query data from the `/query` endpoint.
<span class="api get">GET</span> http://localhost:8086/query
</pre>
The `/query` compatibility endpoint use the **database** and **retention policy**
The `/query` compatibility endpoint uses the **database** and **retention policy**
specified in the query request to map the request to an InfluxDB bucket.
For more information, see [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp).
@ -36,25 +36,22 @@ to query that bucket with the `/query` compatibility API.
## Authentication
Use **basic authentication** or **token authentication**.
{{% note %}}
**Note:** If using basic authentication, include the `--user` (or `-u` and `-p`) option in your request (not `--header`) to ensure the `username:password` is base64 encoded.
{{% /note %}}
Use one of the following authentication methods:
* **token authentication**
* **basic authentication with username and password**
* **query string authentication with username and password**
_For more information, see [Authentication](/influxdb/v2.0/reference/api/influxdb-1x/#authentication)._
## Query string parameters
{{% note %}}
**URL-encode** all query string parameters.
{{% /note %}}
### u
(Optional) The 1.x **username** to authenticate the request.
_See [query string authentication](/influxdb/v2.0/reference/api/influxdb-1x/#query-string-authentication)._
### p
(Optional) The 1.x **password** to authenticate the request.
_See [query string authentication](/influxdb/v2.0/reference/api/influxdb-1x/#query-string-authentication)._
### db
({{< req >}}) The **database** to query data from.
@ -89,20 +86,30 @@ The following precisions are available:
- [Query a non-default retention policy](#query-a-non-default-retention-policy)
- [Execute multiple queries](#execute-multiple-queries)
- [Return query results with millisecond Unix timestamps](#return-query-results-with-millisecond-unix-timestamps)
- [Use `curl` to execute InfluxQL queries from a file](#use-curl-to-execute-influxql-queries-from-a-file)
- [Execute InfluxQL queries from a file](#execute-influxql-queries-from-a-file)
##### Query using basic authentication
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[curl](#curl)
[Node.js](#nodejs)
{{% /code-tabs %}}
{{% code-tab-content %}}
```sh
curl --get http://localhost:8086/query \
--user "username:YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
{{% get-assets-text "api/v1-compat/auth/oss/basic-auth.sh" %}}
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```js
{{% get-assets-text "api/v1-compat/auth/oss/basic-auth.js" %}}
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
##### Query a non-default retention policy
```sh
curl --get http://localhost:8086/query \
--user "username:YourAuthToken" \
--user "OneDotXUsername":"myPasswordOrAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "rp=customrp" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
@ -126,7 +133,7 @@ curl --get http://localhost:8086/query \
--data-urlencode "epoch=ms"
```
##### Use curl to execute InfluxQL queries from a file
##### Execute InfluxQL queries from a file
```sh
curl --get http://localhost:8086/query \
--header "Authorization: Token YourAuthToken" \

39
content/influxdb/v2.0/reference/api/influxdb-1x/write.md
View File

@ -27,13 +27,18 @@ to the `/write` endpoint.
<span class="api post">POST</span> http://localhost:8086/write
</pre>
{{% note %}}
If you have an existing bucket that doesn't follow the **database/retention-policy** naming convention,
you **must** [manually create a database and retention policy mapping](/influxdb/v2.0/query-data/influxql/#map-unmapped-buckets)
to write data to that bucket with the `/write` compatibility API.
{{% /note %}}
## Authentication
Use **basic authentication** or **token authentication**.
{{% note %}}
If using basic authentication, include the `--user` (or `-u` and `-p`) option in your request (not `--header`) to ensure the `username:password` is base64 encoded.
{{% /note %}}
Use one of the following authentication methods:
* **token authentication**
* **basic authentication with username and password**
* **query string authentication with username and password**
_For more information, see [Authentication](/influxdb/v2.0/reference/api/influxdb-1x/#authentication)._
@ -47,9 +52,11 @@ encode the line protocol.
### u
(Optional) The 1.x **username** to authenticate the request.
_See [query string authentication](/influxdb/v2.0/reference/api/influxdb-1x/#query-string-authentication)._
### p
(Optional) The 1.x **password** to authenticate the request.
_See [query string authentication](/influxdb/v2.0/reference/api/influxdb-1x/#query-string-authentication)._
### db
({{< req >}}) The **database** to write data to.
@ -83,22 +90,28 @@ The following precisions are available:
##### Write data using basic authentication
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
--header "Authorization: Basic username:YourAuthToken" \
curl --request POST http://localhost:8086/write?db=mydb \
--user "myusername:PasswordOrAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write data using token authentication
```sh
curl --request POST http://localhost:8086/write?db=mydb \
--header "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write data to a non-default retention policy
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb&rp=customrp \
--header "Authorization: Basic" \
--header "username:YourAuthToken" \
curl --request POST http://localhost:8086/write?db=mydb&rp=customrp \
--user "myusername:PasswordOrAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write multiple lines of line protocol
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
curl --request POST http://localhost:8086/write?db=mydb \
--header "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000
measurement,host=host2 field1=14i,field2=12.7 1577836800000000000
@ -107,14 +120,14 @@ measurement,host=host3 field1=5i,field2=6.8 1577836800000000000"
##### Write data with millisecond Unix timestamps
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb&precision=ms \
curl --request POST http://localhost:8086/write?db=mydb&precision=ms \
--header "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000"
```
##### Use curl to write data from a file
```sh
curl --request POST https://cloud2.influxdata.com/write?db=mydb \
curl --request POST http://localhost:8086/write?db=mydb \
--header "Authorization: Token YourAuthToken" \
--data-binary @path/to/line-protocol.txt
```

7
content/influxdb/v2.0/reference/cli/influx/v1/auth/_index.md
View File

@ -13,12 +13,11 @@ influxdb/v2.0/tags: [authorization]
The `influx v1 auth` subcommands provide authorization management for the
[InfluxDB 1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/).
InfluxDB 2.0 requires authorization with token-based authorization as the standard method.
The [1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/) lets clients
authenticate with InfluxDB 2.0 using the InfluxDB 1.x convention of username and password.
InfluxDB 2.0 uses [authentication tokens](/influxdb/v2.0/security/tokens/) to authorize API requests.
The [1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/) lets clients authenticate with InfluxDB 2.0 using the InfluxDB 1.x convention of username and password.
{{% note %}}
1.x-compatibile authorizations are separate from the credentials used to log
1.x-compatible authorizations are separate from the credentials used to log
into the InfluxDB user interface.
{{% /note %}}

2
content/influxdb/v2.0/tools/api/_index.md
View File

@ -15,7 +15,7 @@ The following pages offer general guides to the most commonly used API methods.
For detailed documentation on the entire API, see [InfluxDBv2 API Documentation](/influxdb/v2.0/reference/api/#influxdb-v2-api-documentation).
{{% note %}}
If you are interacting with InfluxDB 1.x, see the [1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/).
If you need to use InfluxDB 2.0 with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/).
{{% /note %}}
Use the following API endpoints to write and query data:

5
content/influxdb/v2.0/users/create-user.md
View File

@ -10,10 +10,7 @@ weight: 101
products: [oss]
---
Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI)
to create a user.
## Create a user in the InfluxDB UI
Use the `influx` command line interface (CLI) to create a user.
{{% note %}}
Additional users cannot be created in the InfluxDB UI.

6
layouts/shortcodes/api/url-encode-note Normal file
View File

@ -0,0 +1,6 @@
{{ $_hugo_config := `{ "version": 1 }` }}
<div class="note block">
<p>
URL-encode query parameters that may contain whitespace or other special characters.
</p>
</div>

0
layouts/shortcodes/api/v1-compat/basic-auth-clients.html Normal file
View File

8
layouts/shortcodes/api/v1-compat/basic-auth-syntax.html Normal file
View File

@ -0,0 +1,8 @@
{{ $_hugo_config := `{ "version": 1 }` }}
<div class="note block">
<p>
Most HTTP clients provide a <b>Basic authentication</b> option that
accepts the <code>&lt;username&gt;:&lt;password&gt;</code> syntax
and encodes the credentials before sending the request.
</p>
</div>

6
layouts/shortcodes/api/v1-compat/cloud/authentication.html Normal file
View File

@ -0,0 +1,6 @@
Use one of the following authentication schemes:
* **token authentication**
* **basic authentication with username and password**
* **query string authentication with username and password**
_For more information, see [Authentication](/influxdb/cloud/reference/api/influxdb-1x/#authentication)._

2
layouts/shortcodes/api/v1-compat/oss/password-or-token.html Normal file
View File

@ -0,0 +1,2 @@
If you have [set a password](/influxdb/v2.0/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) for the 1.x-compatible username, provide the 1.x-compatible password.
If you haven't set a password for the 1.x-compatible username, provide the InfluxDB [authentication token](/influxdb/v2.0/security/tokens/) as the password.

1
layouts/shortcodes/cloud-token-auth.html Normal file
View File

@ -0,0 +1 @@
InfluxDB Cloud uses [authentication tokens](/influxdb/cloud/security/tokens/) to authorize API requests.