Python client library starter

This page documents an earlier version of InfluxDB. InfluxDB v2.7 is the latest stable version. View this page in the v2.7 documentation.

Follow this step-by-step tutorial to build an Internet-of-Things (IoT) application with InfluxData client libraries and your favorite framework or language.

In this tutorial, you’ll use the InfluxDB API and client libraries to build a modern application as you learn the following:

  • InfluxDB core concepts.

  • How the application interacts with devices and InfluxDB.

  • How to authenticate apps and devices to the API.

  • How to install a client library.

  • How to write and query data in InfluxDB.

  • How to use the InfluxData UI libraries to format data and create visualizations.

Contents

Set up InfluxDB

If you haven’t already, create an InfluxDB Cloud account or install InfluxDB OSS.

Authenticate with an InfluxDB API token

For convenience in development, create an All-Access token for your application. This grants your application full read and write permissions on all resources within your InfluxDB organization.

For a production application, create and use a read-write token with minimal permissions and only use it with your application.

Introducing IoT Starter

The application architecture has four layers:

  • InfluxDB API: InfluxDB v2 API.
  • IoT device: Virtual or physical devices write IoT data to the InfluxDB API.
  • UI: Sends requests to the server and renders views in the browser.
  • API: Receives requests from the UI, sends requests to InfluxDB, and processes responses from InfluxDB.

For the complete code referenced in this tutorial, see the influxdata/iot-api-python repository.

Create the application

Create a directory that will contain your iot-api projects. The following example code creates an iot-api directory in your home directory and changes to the new directory:

  1. mkdir ~/iot-api-apps
  2. cd ~/iot-api-apps

Use Flask, a lightweight Python web framework, to create your application.

  1. In your ~/iot-api-apps directory, open a terminal and enter the following commands to create and navigate into a new project directory:

    1. mkdir iot-api-python && cd $_

  2. Enter the following commands in your terminal to create and activate a Python virtual environment for the project:

    1. # Create a new virtual environment named "virtualenv"
    2. # Python 3.8+
    3. python -m venv virtualenv
    5. # Activate the virtualenv (OS X & Linux)
    6. source virtualenv/bin/activate

  3. After activation completes, enter the following commands in your terminal to install Flask with the pip package installer (included with Python):

    1. pip install Flask

  4. In your project, create a app.py file that:

    1. Imports the Flask package.
    2. Instantiates a Flask application.
    3. Provides a route to execute the application.
    1. from flask import Flask
    2. app = Flask(__name__)
    4. @app.route("/")
    5. def hello():
    6.   return "Hello World!"

    influxdata/iot-api-python app.py

    Start your application. The following example code starts the application on http://localhost:3001 with debugging and hot-reloading enabled:

    1. export FLASK_ENV=development
    2. flask run -h localhost -p 3001

    In your browser, visit http://localhost:3001 to view the “Hello World!” response.

Install InfluxDB client library

The InfluxDB client library provides the following InfluxDB API interactions:

  • Query data with the Flux language.
  • Write data to InfluxDB.
  • Batch data in the background.
  • Retry requests automatically on failure.

Enter the following command into your terminal to install the client library:

  1. pip install influxdb-client

For more information about the client library, see the influxdata/influxdb-client-python repo.

Configure the client library

InfluxDB client libraries require configuration properties from your InfluxDB environment. Typically, you’ll provide the following properties as environment variables for your application:

  • INFLUX_URL
  • INFLUX_TOKEN
  • INFLUX_ORG
  • INFLUX_BUCKET
  • INFLUX_BUCKET_AUTH

To set up the client configuration, create a config.ini in your project’s top level directory and paste the following to provide the necessary InfluxDB credentials:

  1. [APP]
  2. INFLUX_URL = <INFLUX_URL>
  3. INFLUX_TOKEN = <INFLUX_TOKEN>
  4. INFLUX_ORG = <INFLUX_ORG_ID>
  5. INFLUX_BUCKET = iot_center
  6. INFLUX_BUCKET_AUTH = iot_center_devices

/iot-api-python/config.ini

Replace the following:

  • <INFLUX_URL>: your InfluxDB instance URL.
  • <INFLUX_TOKEN>: your InfluxDB API token with permission to query (read) buckets and create (write) authorizations for devices.
  • <INFLUX_ORG_ID>: your InfluxDB organization ID.

Build the API

Your application API provides server-side HTTP endpoints that process requests from the UI. Each API endpoint is responsible for the following:

  1. Listen for HTTP requests (from the UI).
  2. Translate requests into InfluxDB API requests.
  3. Process InfluxDB API responses and handle errors.
  4. Respond with status and data (for the UI).

Create the API to register devices

In this application, a registered device is a point that contains your device ID, authorization ID, and API token. The API token and authorization permissions allow the device to query and write to INFLUX_BUCKET. In this section, you add the API endpoint that handles requests from the UI, creates an authorization in InfluxDB, and writes the registered device to the INFLUX_BUCKET_AUTH bucket. To learn more about API tokens and authorizations, see Manage API tokens

The application API uses the following /api/v2 InfluxDB API endpoints:

  • POST /api/v2/query: to query INFLUX_BUCKET_AUTH for a registered device.
  • GET /api/v2/buckets: to get the bucket ID for INFLUX_BUCKET.
  • POST /api/v2/authorizations: to create an authorization for the device.
  • POST /api/v2/write: to write the device authorization to INFLUX_BUCKET_AUTH.

Create an authorization for the device

In this section, you create an authorization with read-write permission to INFLUX_BUCKET and receive an API token for the device. The example below uses the following steps to create the authorization:

  1. Instantiate the AuthorizationsAPI client and BucketsAPI client with the configuration.
  2. Retrieve the bucket ID.
  3. Use the client library to send a POST request to the /api/v2/authorizations InfluxDB API endpoint.

Create a ./api/devices.py file that contains the following:

  1. # Import the dependencies.
  2. import configparser
  3. from datetime import datetime
  4. from uuid import uuid4
  6. # Import client library classes.
  7. from influxdb_client import Authorization, InfluxDBClient, Permission, PermissionResource, Point, WriteOptions
  8. from influxdb_client.client.authorizations_api import AuthorizationsApi
  9. from influxdb_client.client.bucket_api import BucketsApi
  10. from influxdb_client.client.query_api import QueryApi
  11. from influxdb_client.client.write_api import SYNCHRONOUS
  13. from api.sensor import Sensor
  15. # Get the configuration key-value pairs.
  17. config = configparser.ConfigParser()
  18. config.read('config.ini')
  20. def create_authorization(device_id) -> Authorization:
  21.     influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'),
  22.                                      token=os.environ.get('INFLUX_TOKEN'),
  23.                                      org=os.environ.get('INFLUX_ORG'))
  25.     authorization_api = AuthorizationsApi(influxdb_client)
  26.     # get bucket_id from bucket
  27.     buckets_api = BucketsApi(influxdb_client)
  28.     buckets = buckets_api.find_bucket_by_name(config.get('APP', 'INFLUX_BUCKET'))  # function returns only 1 bucket
  29.     bucket_id = buckets.id
  30.     org_id = buckets.org_id
  31.     desc_prefix = f'IoTCenterDevice: {device_id}'
  32.     org_resource = PermissionResource(org_id=org_id, id=bucket_id, type="buckets")
  33.     read = Permission(action="read", resource=org_resource)
  34.     write = Permission(action="write", resource=org_resource)
  35.     permissions = [read, write]
  36.     authorization = Authorization(org_id=org_id, permissions=permissions, description=desc_prefix)
  37.     request = authorization_api.create_authorization(authorization)
  38.     return request

iot-api-python/api/devices.py

To create an authorization that has read-write permission to INFLUX_BUCKET, you need the bucket ID. To retrieve the bucket ID, create_authorization(deviceId) calls the BucketsAPI find_bucket_by_name function that sends a GET request to the /api/v2/buckets InfluxDB API endpoint. create_authorization(deviceId) then passes a new authorization in the request body with the following:

  • Bucket ID.
  • Organization ID.
  • Description: IoTCenterDevice: DEVICE_ID.
  • List of permissions to the bucket.

To learn more about API tokens and authorizations, see Manage API tokens.

Next, write the device authorization to a bucket.

Write the device authorization to a bucket

With a device authorization in InfluxDB, write a point for the device and authorization details to INFLUX_BUCKET_AUTH. Storing the device authorization in a bucket allows you to do the following:

  • Report device authorization history.
  • Manage devices with and without tokens.
  • Assign the same token to multiple devices.
  • Refresh tokens.

To write a point to InfluxDB, use the InfluxDB client library to send a POST request to the /api/v2/write InfluxDB API endpoint. In ./api/devices.py, add the following create_device(device_id) function:

  1. def create_device(device_id=None):
  2.     influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'),
  3.                                      token=config.get('APP', 'INFLUX_TOKEN'),
  4.                                      org=config.get('APP', 'INFLUX_ORG'))
  5.     if device_id is None:
  6.         device_id = str(uuid4())
  7.     write_api = influxdb_client.write_api(write_options=SYNCHRONOUS)
  8.     point = Point('deviceauth') \
  9.         .tag("deviceId", device_id) \
  10.         .field('key', f'fake_auth_id_{device_id}') \
  11.         .field('token', f'fake_auth_token_{device_id}')
  12.     client_response = write_api.write(bucket=config.get('APP', 'INFLUX_BUCKET_AUTH'), record=point)
  13.     # write() returns None on success
  14.     if client_response is None:
  15.         return device_id
  16.     # Return None on failure
  17.     return None

iot-api-python/api/devices.py

create_device(device_id) takes a device_id and writes data to INFLUX_BUCKET_AUTH in the following steps:

  1. Initialize InfluxDBClient() with url, token, and org values from the configuration.
  2. Initialize a WriteAPI client for writing data to an InfluxDB bucket.
  3. Create a Point.
  4. Use write_api.write() to write the Point to the bucket.
  5. Check for failures–if the write was successful, write_api returns None.
  6. Return device_id if successful; None otherwise.

The function writes a point with the following elements:

ElementNameValue
measurementdeviceauth
tagdeviceIddevice ID
fieldkeyauthorization ID
fieldtokenauthorization (API) token

Next, create the API to list devices.

Create the API to list devices

Add the /api/devices API endpoint that retrieves, processes, and lists registered devices.

  1. Create a Flux query that gets the last row of each series that contains a deviceauth measurement. The example query below returns rows that contain the key field (authorization ID) and excludes rows that contain a token field (to avoid exposing tokens to the UI).

    1. // Flux query finds devices
    2.  from(bucket:`${INFLUX_BUCKET_AUTH}`)
    3.       |> range(start: 0)
    4.       |> filter(fn: (r) => r._measurement == "deviceauth" and r._field != "token")
    5.       |> last()

  2. Use the QueryApi client to send the Flux query to the POST /api/v2/query InfluxDB API endpoint.

    In ./api/devices.py, add the following:

    Python

    1. def get_device(device_id=None) -> {}:
    2.     influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'),
    3.                                      token=os.environ.get('INFLUX_TOKEN'),
    4.                                      org=os.environ.get('INFLUX_ORG'))
    5.     # Queries must be formatted with single and double quotes correctly
    6.     query_api = QueryApi(influxdb_client)
    7.     device_filter = ''
    8.     if device_id:
    9.         device_id = str(device_id)
    10.         device_filter = f'r.deviceId == "{device_id}" and r._field != "token"'
    11.     else:
    12.         device_filter = f'r._field != "token"'
    14.     flux_query = f'from(bucket: "{config.get("APP", "INFLUX_BUCKET_AUTH")}") ' \
    15.                  f'|> range(start: 0) ' \
    16.                  f'|> filter(fn: (r) => r._measurement == "deviceauth" and {device_filter}) ' \
    17.                  f'|> last()'
    19.     response = query_api.query(flux_query)
    20.     result = []
    21.     for table in response:
    22.         for record in table.records:
    23.             try:
    24.                 'updatedAt' in record
    25.             except KeyError:
    26.                 record['updatedAt'] = record.get_time()
    27.                 record[record.get_field()] = record.get_value()
    28.             result.append(record.values)
    29.     return result

    iot-api-python/api/devices.py get_device()

The get_device(device_id) function does the following:

  1. Instantiates a QueryApi client and sends the Flux query to InfluxDB.
  2. Iterates over the FluxTable in the response and returns a list of tuples.

Create IoT virtual device

Create a ./api/sensor.py file that generates simulated weather telemetry data. Follow the example code to create the IoT virtual device.

Next, generate data for virtual devices and write the data to InfluxDB.

Write telemetry data

In this section, you write telemetry data to an InfluxDB bucket. To write data, use the InfluxDB client library to send a POST request to the /api/v2/write InfluxDB API endpoint.

The example below uses the following steps to generate data and then write it to InfluxDB:

  1. Initialize a WriteAPI instance.
  2. Create a Point with the environment measurement and data fields for temperature, humidity, pressure, latitude, and longitude.
  3. Use the WriteAPI write method to send the point to InfluxDB.

In ./api/devices.py, add the following write_measurements(device_id) function:

Python

  1. def write_measurements(device_id):
  2.     influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'),
  3.                                      token=config.get('APP', 'INFLUX_TOKEN'),
  4.                                      org=config.get('APP', 'INFLUX_ORG'))
  5.     write_api = influxdb_client.write_api(write_options=SYNCHRONOUS)
  6.     virtual_device = Sensor()
  7.     coord = virtual_device.geo()
  8.     point = Point("environment") \
  9.         .tag("device", device_id) \
  10.         .tag("TemperatureSensor", "virtual_bme280") \
  11.         .tag("HumiditySensor", "virtual_bme280") \
  12.         .tag("PressureSensor", "virtual_bme280") \
  13.         .field("Temperature", virtual_device.generate_measurement()) \
  14.         .field("Humidity", virtual_device.generate_measurement()) \
  15.         .field("Pressure", virtual_device.generate_measurement()) \
  16.         .field("Lat", coord['latitude']) \
  17.         .field("Lon", coord['latitude']) \
  18.         .time(datetime.utcnow())
  19.     print(f"Writing: {point.to_line_protocol()}")
  20.     client_response = write_api.write(bucket=config.get('APP', 'INFLUX_BUCKET'), record=point)
  21.     # write() returns None on success
  22.     if client_response is None:
  23.         # TODO Maybe also return the data that was written
  24.         return device_id
  25.     # Return None on failure
  26.     return None

iot-api-python/api/devices.py write_measurement()

Query telemetry data

In this section, you retrieve telemetry data from an InfluxDB bucket. To retrieve data, use the InfluxDB client library to send a POST request to the /api/v2/query InfluxDB API endpoint. The example below uses the following steps to retrieve and process telemetry data:

  1. Query environment measurements in INFLUX_BUCKET.
  2. Filter results by device_id.
  3. Return CSV data that the influxdata/giraffe UI library can process.

In ./api/devices.py, add the following get_measurements(device_id) function:

Python

  1. def get_measurements(query):
  2.     influxdb_client = InfluxDBClient(url=config.get('APP', 'INFLUX_URL'),
  3.                                      token=os.environ.get('INFLUX_TOKEN'), org=os.environ.get('INFLUX_ORG'))
  4.     query_api = QueryApi(influxdb_client)
  5.     result = query_api.query_csv(query,
  6.                                  dialect=Dialect(
  7.                                        header=True,
  8.                                        delimiter=",",
  9.                                        comment_prefix="#",
  10.                                        annotations=['group', 'datatype', 'default'],
  11.                                        date_time_format="RFC3339"))
  12.     response = ''
  13.     for row in result:
  14.         response += (',').join(row) + ('\n')
  15.     return response

iot-api-python/api/devices.py get_measurements()

Define API responses

In app.py, add API endpoints that match incoming requests and respond with the results of your modules. In the following /api/devices/<device_id> route example, app.py retrieves device_id from GET and POST requests, passes it to the get_device(device_id) method and returns the result as JSON data with CORS allow- headers.

Python

  1. @app.route('/api/devices/<string:device_id>', methods=['GET', 'POST'])
  2. def api_get_device(device_id):
  3.     if request.method == "OPTIONS": # CORS preflight
  4.         return _build_cors_preflight_response()
  5.     return _corsify_actual_response(jsonify(devices.get_device(device_id)))

iot-api-python/app.py

Enter the following commands into your terminal to restart the application:

  1. CONTROL+C to stop the application.
  2. flask run -h localhost -p 3001 to start the application.

To retrieve devices data from your API, visit http://localhost:3001/api/devices in your browser.

Install and run the UI

influxdata/iot-api-ui is a standalone Next.js React UI that uses your application API to write and query data in InfluxDB. iot-api-ui uses Next.js rewrites to route all requests in the /api/ path to your API.

To install and run the UI, do the following:

  1. In your ~/iot-api-apps directory, clone the influxdata/iot-api-ui repo and go into the iot-api-ui directory–for example:

    1. cd ~/iot-api-apps
    2. git clone git@github.com:influxdata/iot-api-ui.git
    3. cd ./iot-app-ui

  2. The ./.env.development file contains default configuration settings that you can edit or override (with a ./.env.local file).

  3. To start the UI, enter the following command into your terminal:

    1. yarn dev

    To view the list and register devices, visit http://localhost:3000/devices in your browser.

To learn more about the UI components, see influxdata/iot-api-ui.

api python