The Cloud SDK is part of the Formant Python package. It allows you to interact with the data and capabilities of the Formant cloud, which contains your organization's data and issues commands. Using the Cloud SDK, you can interact with the Formant platform programmatically, without having to use the web application or UI.

📘
When should I use the Cloud SDK?
You should use the Cloud SDK...

To query datapoints from your Formant organization.

To ingest datapoints to your Formant organization without using the Formant agent.

Installation

Prerequisite: Authenticate your session

You'll need to authenticate your session with the Cloud SDK. You can do this using your Formant credentials, or by creating a service account.

You can create a service account in the Formant web application, or using fctl, Formant's command-line tool.

Once you've generated your credentials, set the following environment variables:

export FORMANT_EMAIL="<your-email>"
export FORMANT_PASSWORD="<your-password>"

The Formant Python package can be installed via pip:

pip install formant

Usage

This section gives a broad overview of the capabilities of the Cloud SDK.

📘
The full set of methods, syntax, and return values can be found in the Cloud SDK reference.

Instantiate the cloud client

To use the methods of the Cloud SDK, you'll first instantiate the client:

from formant.sdk.cloud.v1 import Client
fclient = Client()

Ingest data

The ingest method allows you to ingest data to your Formant cloud without using the agent:

from formant.sdk.cloud.v1 import Client
fclient = Client()

params = {
	deviceId: "ced176ab-f223-4466-b958-ff8d35261529",
	name: "engine_temp",
	type: "numeric",
	tags: {"location":"sf"},
	points: [...],
}

response = fclient.ingest(params)

For a set of syntax examples to ingest various data types, see GitHub: ingest.py.

Query datapoints

The query method allows you to query datapoints from your Formant cloud:

from formant.sdk.cloud.v1 import Client
fclient = Client()

params = {
  start: "2021-01-01T01:00:00.000Z",
  end: "2021-01-01T02:00:00.000Z",
  deviceIds: ["99e8ee37-0a27-4a11-bba2-521facabefa3"],
  names: ["engine_temp"],
  types: ["numeric"],
  tags: {"location":["sf","la"]},
  notNames: ["speed"],
}

response = fclient.query(params)

For a set of syntax examples to query various data types, see GitHub: query.py.

📘
The notNames and notTags parameters are used to exclude names or tag sets from the query.

Query current stream value

The query_stream_current_value method returns only the latest value of a stream. See GitHub: query_stream_latest.py.

Query device online status

You can determine if a device is online by using the query method on the $.agent.health stream. See GitHub: online.py.

Commands

The create_command method allows you to add new commands to your Formant organization. The query_commands method returns undelivered commands by device ID. See GitHub: commands.py.

Intervention requests

The create_intervention_request and create_intervention_response methods allow you to create new intervention requests and responses.

See also