TL;DR InfluxDB Tech Tips: API Invokable Scripts in InfluxDB Cloud

By Anais Dotis-Georgiou / Product, Use Cases, Developer
Nov 10, 2021

If you’re familiar with InfluxDB Cloud, then you’re probably familiar with Flux already. Flux enables you to transform your data in any way you need and write custom tasks, checks, and notification rules. But what you might not know is that InfluxDB Cloud now supports API Invokable Scripts in Flux. API Invokable Scripts are parameterized queries that are hosted and invoked by the InfluxDB Cloud server so that application developers can add custom functionality to their time series applications without having to introduce query resources into their client-side services and code. By supporting runtime parameters, it is possible to generalize these functions so that custom results may be returned for each user. API Invokable Scripts can only be used with InfluxDB Cloud via the v2 API right now, but will be landing in the CLI, then the InfluxDB User Interface, and finally in InfluxDB OSS v2.x some time later.

Creating your first Flux API Invokable Scripts in InfluxDB Cloud

You can create an API Invokable Script and an associated function resource with the InfluxDB v2 API. An associated function resource contains the following: name, id, description, orgID, script, language, url, createdAt, and updatedAt. These features help the developer identify their API Invokable Script and its associated metadata. The function id is used to manually invoke the function upon request.

To create a function with an associated function resource, use the api/v2/functions endpoint. In this example, our parameterized query returns the last two data points from the bucket of our choice.

curl -X 'POST' \
  'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/functions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "myFirstAPIInvokableScripts",
  "description": "a API Invokable Script that gathers the last point from a bucket",
  "orgID": "<myOrgID>",
  "script": "from(bucket:params.mybucket) \
|> range(start: -7d) \
|> limit(n:2)",
  "language": "flux"
}'

The function id is returned in the body of the response when you create an API Invokable Script. Alternatively, you can also retrieve the function id and all the other associated function resources by listing the function. Then you can use list the function with:

curl -X 'GET' \
  'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/functions?orgID=<myOrgID>' \
  -H 'accept: application/json'

Invoking a script with parameterized queries in InfluxDB Cloud

Once you have the function id, you can manually invoke the API Invokable Script and supply the parameters. In this case, we’ll supply the bucket name to the mybucket parameter. Our request looks like this:

curl -X 'POST' \
  'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/functions/<functionID>/invoke' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {"mybucket":"telegraf"}
}'

Invoking a script with parameterized queries in VS Code

You can also use the Flux extension for VS Code to easily create and execute an invokable script with parameterized queries. Once you’ve installed the Flux extension for VS code and configured it, you can create a new invokable script and run it. For example, I can run the following invokable script with parameters:

params = { "mybucket": "airsensor" }
from(bucket:params.mybucket) 
|> range(start: -1y) 
|> limit(n:2)

First create a new script by right-clicking on the menu on the left. Name your invokable script and add a description.

Next, write your invokable script. Right-click on your script to run the query. The output of the script will pop up in a new tab to the right by default.

Now you can run the invokable script remotely and integrate the script into an application built on top of InfluxDB, for example. However, once you’ve verified that your script gives you the expected output, you’ll want to remove the following line: params = { "mybucket": "airsensor" }.

Now you can inject the parameters when you invoke the script via the API, like in the example above but with the correct parameter in the body of the request:

-d '{
  "params": {"mybucket":"airsensor"}
}'

Further reading

While this post aims to provide a comprehensive overview of invokable scripts with parameterized queries, the following resources might also interest you:

1. Using the Flux VS Code Extension for IoT Application Development: This post describes how to use the Flux VS Code Extension to manage your InfluxDB instance by creating buckets and tasks to facilitate application development on top of InfluxDB.
2. Use the Flux VS Code extension: The InfluxData docs on the Flux VS Code extension.
3. InfluxDB Tech Tips: Parameterized Flux Queries with InfluxDB: This post describes how to write parameterized queries with InfluxDB.
4. Invokable Scripts and Tasks: Discover how you can use the same scripts with internal and external sources to provide consistency in alerting behavior across your application.

Final thoughts on Invokable Scripts with InfluxDB

I hope this InfluxDB Tech Tips post inspires you to take advantage of API Invokable Scripts with InfluxDB Cloud. If you are using Flux and need help, please ask for some in our community site or Slack channel. If you’re developing a cool IoT application on top of InfluxDB, we’d love to hear about it, so make sure to share your story! Additionally, please share your thoughts, concerns, or questions in the comments section. We’d love to get your feedback and help you with any problems you run into!