将自定义脚本作为API端点调用

使用可调用的API脚本创建自定义的InfluxDB API端点，以查询、处理和整理数据。可调用的API脚本让您能够将脚本分配给API端点，然后以标准REST操作的形式在InfluxDB Cloud中执行它们。了解如何管理可调用的API脚本并使用运行时参数调用它们。

使用 /api/v2/scripts InfluxDB API接口来：

创建一个脚本
调用一个脚本
列出脚本
更新脚本
删除一个脚本

创建可调用的脚本

要为您的组织创建一个可调用的 API 脚本，请使用 POST 方法向 /api/v2/scripts InfluxDB API 端点发送请求。

POST https://cloud2.influxdata.com/api/v2/scripts

在您的API请求中提供以下内容：

请求头

内容类型: application/json
授权: 令牌 INFLUX_API_TOKEN

请求体

具有以下字段的JSON对象：

脚本 : Flux 脚本作为一个字符串。
语言 : 你的脚本的语言（“flux”）
name : 脚本名称，在您的组织中是唯一的
描述 : 脚本描述
orgID: 你的 InfluxDB 组织 ID

在脚本中使用参数

要创建一个可调用的脚本，该脚本接受参数（变量），请将参数作为params对象的属性引用，例如params.firstparam。params是一个InfluxDB对象，用于定义运行时变量。您在调用脚本时提供params的值。如果未为引用的参数提供值，InfluxDB将返回以下错误：

{
  "code":"invalid",
  "message":"invalid parameters provided"
}

示例

创建一个可调用的 Flux 脚本

以下示例创建一个新的 Flux 脚本，该脚本引用了 params.mybucket 参数并返回 bucket 中的最后一个点。

curl -X 'POST' \
  "https://cloud2.influxdata.com/api/v2/scripts" \
  --header "Authorization: Token ${INFLUX_TOKEN}" \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary @- << EOF | jq .
  {
    "name": "getLastPoint",
    "description": "getLastPoint finds the last point in a bucket",
    "orgID": "${INFLUX_ORG_ID}",
    "script": "from(bucket: params.mybucket) \
     |> range(start: -7d) \
     |> limit(n:1)",
     "language": "flux"
  }
EOF

替换以下内容：

INFLUX_API_TOKEN: 你的 InfluxDB API token
INFLUX_ORG_ID: 您的 InfluxDB 组织 ID

InfluxDB 返回新创建的脚本。接下来，查看如何调用脚本。

{
  "id": "084d693d93048000",
  "orgID": "INFLUX_ORG_ID",
  "name": "getLastPoint",
  "script": "from(bucket: params.mybucket)      |> range(start: -7d)      |> limit(n:1)",
  "description": "getLastPoint finds the last point in a bucket",
  "language": "flux",
  "createdAt": "2021-10-15T20:32:04.172938Z",
  "updatedAt": "2021-10-15T20:32:04.172938Z"
}

调用脚本

要调用脚本，请使用 POST 方法向 /api/v2/scripts/SCRIPT_ID/invoke InfluxDB API 端点发送请求。

POST https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID

将 SCRIPT_ID 替换为您想要执行的脚本的 ID。要找到脚本 ID，请参见如何列出脚本。

在您的请求中提供以下内容：

请求头

内容类型: application/json
接受: application/csv
授权: 令牌 INFLUX_API_TOKEN

请求体

包含 params 对象的 JSON 对象。在 params 中，为您脚本中引用的参数提供键值对。create 示例引用了参数 params.mybucket。

  "from(bucket: params.mybucket) \
   |> range(start: -7d) \
   |> limit(n:1)"

以下示例调用所创建的脚本，并将“air_sensor”作为params.mybucket的值传递。

SCRIPT_ID=085138a111448000

curl -X 'POST' \
  "${INFLUX_URL}/api/v2/scripts/${SCRIPT_ID}/invoke" \
  --header "Authorization: Token ${INFLUX_TOKEN}" \
  --header 'Accept: application/csv' \
  --header 'Content-Type: application/json' \
  --data-binary '{ "params": { "mybucket": "air_sensor" } }'

InfluxDB 将查询结果以注释的 CSV 形式从 air_sensor 存储桶中返回。

将多个参数值传递给脚本

如果脚本引用多个参数，请为所有参数提供值。要为多个参数提供值，请发送一个包含params对象的对象。在params中，将参数名称作为键，并为每个键定义一个值。

以下可调用脚本对象引用了四个参数：

    {
      "name": "filter-and-group",
      "description": "Filters and groups points in a bucket. Expects parameters bucket, filterField, filterField2, and groupColumn.",
      "orgID": "${INFLUX_ORG_ID}",
      "script": "from(bucket: params.bucket) \
                 |> range(start: -30d) \
                 |> filter(fn: (r) => r._field == params.filterField or r._field == params.filterField2) \
                 |> group(columns: [params.groupColumn])",
       "language": "flux"
    }

Flux脚本引用了以下参数：

params.bucket
params.filterField
params.filterField2
params.groupColumn

要为参数提供值，请发送一个 POST 请求到 /api/v2/scripts/SCRIPT_ID/invoke，并提供一个包含 params 对象的 JSON 对象。在 params 对象内部，为脚本中引用的每个参数定义一个键值对。该对象必须是有效的JSON。

考虑一个 air_sensor 桶，里面包含 airSensors 测量。每个点都有一个 temperature、humidity 或 co 字段。

,result,table,_start,_stop,_time,_value,_field,_measurement,sensor_id
,_result,0,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,75.30007505999716,temperature,airSensors,TLM0202
,_result,1,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,73,temperature,airSensors,TLM0201
,_result,2,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,35,humidity,airSensors,TLM0201
,_result,3,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,0.5141876544505826,co,airSensors,TLM0202
,_result,4,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,0.48445310567793615,co,airSensors,TLM0201
,_result,5,2021-09-25T22:20:11.493547551Z,2021-10-25T22:20:11.493547551Z,2021-09-28T16:13:05Z,35.651929918691714,humidity,airSensors,TLM0202

以下 params 对象为脚本中引用的每个参数提供了一个键值对。

{ "params":
  {
    "bucket": "air_sensor",
    "filterField": "temperature",
    "filterField2": "humidity",
    "groupColumn": "_time"
  }
}

以下示例使用 /api/v2/scripts InfluxDB API 端点来创建脚本并通过 params 调用新的脚本 ID。

new_script_id=$(
  curl -v -X 'POST' \
    "${INFLUX_URL}/api/v2/scripts" \
    --header "Authorization: Token ${INFLUX_TOKEN}" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-binary @- << EOF | jq -r '.id' 
    {
      "name": "filter-and-group",
      "description": "Filters and groups points in a bucket. Expects parameters bucket, filterField, filterField2, and groupColumn.",
      "orgID": "${INFLUX_ORG_ID}",
      "script": "from(bucket: params.bucket) \
                 |> range(start: -30d) \
                 |> filter(fn: (r) => r._field == params.filterField or r._field == params.filterField2) \
                 |> group(columns: [params.groupColumn])",
       "language": "flux"
    }
EOF
)

curl -vv -X 'POST' \
  "${INFLUX_URL}/api/v2/scripts/${new_script_id}/invoke" \
  --header "Authorization: Token ${INFLUX_TOKEN}" \
  --header 'Accept: application/csv' \
  --header 'Content-Type: application/json' \
  --data-binary @- << EOF
    { "params":
      {
        "bucket": "air_sensor",
        "filterField": "temperature",
        "filterField2": "humidity",
        "groupColumn": "_time"
      }
    }
EOF

InfluxDB 返回来自 air_sensor 的点，这些点包含 temperature 或 humidity 字段。点按 _time 列分组。每个唯一的 table 值表示一个组。

,result,table,_start,_stop,_time,_value,_field,_measurement,sensor_id
,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,73,temperature,airSensors,TLM0201
,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,75.30007505999716,temperature,airSensors,TLM0202
,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,35,humidity,airSensors,TLM0201
,_result,0,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:13:05Z,35.651929918691714,humidity,airSensors,TLM0202
,_result,1,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:57:57Z,75.30007505999716,temperature,airSensors,TLM0202
,_result,1,2021-09-25T21:10:01.810564864Z,2021-10-25T21:10:01.810564864Z,2021-09-28T16:57:57Z,35.651929918691714,humidity,airSensors,TLM0202

可调用脚本列表

要列出一个组织的脚本，请使用 GET 方法向 /api/v2/scripts InfluxDB API 端点发送请求。

在您的请求中提供以下内容：

请求头

内容类型: application/json
授权: 令牌 INFLUX_API_TOKEN

请求查询参数

org: 您的组织名称（与orgID互斥）
orgID: 你的组织 ID (与 org 互斥)
limit: （可选）返回的脚本数量
offset: （可选）用于偏移分页的数字

curl -X 'GET' \
  "${INFLUX_URL}/api/v2/scripts" \
  --header "Authorization: Token ${INFLUX_TOKEN}" \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-urlencode "org=${INFLUX_ORG}" \
  --data-urlencode "limit=10"

要为一个组织找到特定的脚本，请使用 GET 方法向 /api/v2/scripts/SCRIPT_ID InfluxDB API 端点发送请求。

GET https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID

用您想要查找的脚本的 ID 替换 SCRIPT_ID。

在您的请求中提供以下内容：

请求头

授权: 令牌 INFLUX_API_TOKEN
接受: application/json

curl -X 'GET' \
  "${INFLUX_URL}/api/v2/scripts/${SCRIPT_ID}" \
  --header "Authorization: Token ${INFLUX_TOKEN}" \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json'

更新可调用脚本

使用API替换可调用脚本的以下属性：

名称
描述
脚本

要更新组织的现有脚本，请使用PATCH方法向/api/v2/scripts/SCRIPT_ID InfluxDB API端点发送请求。将SCRIPT_ID替换为您想要更新的脚本的ID。

PATCH https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID

在您的请求中提供以下内容：

请求头

授权: 令牌 INFLUX_API_TOKEN
内容类型: application/json
接受: application/json'

请求体

作为JSON对象的修改过的 可调用脚本。

以下示例查找包含数字日期范围的可调用脚本，替换日期为新参数，并更新可调用脚本。

find_and_update() {
  script=$(curl -X 'GET' \
    "https://cloud2.influxdata.com/api/v2/scripts" \
    --header "Authorization: Token ${INFLUX_TOKEN}" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-urlencode "org=${INFLUX_ORG}&limit=10" \
    | jq '[.scripts[] | select(.script | test("start: -?\\d\\w"))]' \
    | jq '.[0]')
  new_script=$(jq '.script |= sub("start: .*d"; "start: params.myrangestart")' <<< "${script}")
  script_id=$(jq -r '.id' <<< "${new_script}")

  curl -X 'PATCH' \
    "${INFLUX_URL}/api/v2/scripts/${script_id}" \
    --header "Authorization: Token ${INFLUX_TOKEN}" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data "${new_script}" | jq .
}

find_and_update

使用 GET /api/v2/scripts 来检索一个包含脚本列表的对象。
使用脚本数组，利用 jq 找到第一个具有包含硬编码数字日期范围的 script 属性的 可调用脚本 对象。
将script属性中的硬编码日期范围替换为新的params.myrangestart动态参数，并将该对象分配给new_script变量。
将脚本ID分配给script_id变量。
通过向 PATCH /api/v2/scripts/ 发送请求来更新脚本，URL路径中包含 $script_id，并将 $new_script 作为数据（在请求体中）。

InfluxDB 返回更新后的可调用脚本。

删除可调用的脚本

要删除一个脚本，使用 DELETE 方法向 /api/v2/scripts/SCRIPT_ID InfluxDB API 端点发送请求。将 SCRIPT_ID 替换为您想要更新的脚本的 ID。

DELETE https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID

在您的请求中提供以下内容：

请求头

授权: 令牌 INFLUX_API_TOKEN
接受: application/json'

api guides

将自定义脚本作为API端点调用

创建可调用的脚本

请求头

请求体

在脚本中使用参数

示例

创建一个可调用的 Flux 脚本

调用脚本

请求头

请求体

将多个参数值传递给脚本

可调用脚本列表

请求头

请求查询参数

请求头

更新可调用脚本

请求头

请求体

删除可调用的脚本

请求头

Flux的未来

InfluxDB 3 开源版本现已公开Alpha测试

将自定义脚本作为API端点调用

创建可调用的脚本

请求头

请求体

在脚本中使用参数

示例

创建一个可调用的 Flux 脚本

调用脚本

请求头

请求体

将多个参数值传递给脚本

可调用脚本列表

请求头

请求查询参数

请求头

更新可调用脚本

请求头

请求体

删除可调用的脚本

请求头

选择您的 InfluxDB Cloud 区域

AWS

谷歌云平台

微软 Azure

感谢您的反馈!

Flux的未来

InfluxDB 3 开源版本现已公开Alpha测试

由TSM驱动的InfluxDB Cloud