HTTP write task
Learn how to send commands to HTTP endpoints with Synnax.
This task follows the standard task lifecycle.
Task configuration reference
Endpoint configuration reference
Each endpoint maps a single Synnax command channel to an HTTP request. When the channel receives a value, the Driver builds the JSON body and sends the request.
Field types reference
The request body is constructed from three types of fields, each placed at a JSON Pointer location in the body.
Channel field (required)
The channel field is the primary field on each endpoint. Its value comes from a Synnax command channel — when a value is written to the channel, the Driver places it in the request body at the specified pointer.
http.ChannelField(
pointer="/value",
json_type="number",
channel=setpoint_cmd.key,
) Enum values
When the HTTP request body should contain string values that represent discrete states,
use enum_values to map them to numbers. The Driver converts matching strings to their
numeric equivalents before writing to the channel.
http.ChannelField(
pointer="/source",
json_type="string",
channel=source_cmd.key,
enum_values=[{"label": "OFF", "value": 0}, {"label": "ON", "value": 1}],
) Static fields
Static fields place a fixed value in every request.
http.StaticWriteField(
pointer="/unit",
json_type="string",
value="psi",
) Generated fields
Generated fields produce a new value for each request. Two generator types are supported:
# UUID generator - produces a unique ID per request
http.GeneratedWriteField(
pointer="/request_id",
generator="uuid",
)
# Timestamp generator - produces current time per request
http.GeneratedWriteField(
pointer="/timestamp",
generator="timestamp",
time_format="iso8601",
)How-to
Console
Python
Configure and run task
import synnax as sy
from synnax import http
client = sy.Synnax()
# Retrieve the HTTP device
dev = client.devices.retrieve(name="My HTTP Server")
# Create a command time index
http_cmd_time = client.channels.create(
name="http_cmd_time",
is_index=True,
data_type=sy.DataType.TIMESTAMP,
retrieve_if_name_exists=True,
)
# Create a command channel
setpoint_cmd = client.channels.create(
name="http_setpoint_cmd",
index=http_cmd_time.key,
data_type=sy.DataType.FLOAT64,
retrieve_if_name_exists=True,
)
# Create the write task
task = http.WriteTask(
name="HTTP Write Task",
device=dev.key,
endpoints=[
http.WriteEndpoint(
method="PUT",
path="/api/v1/setpoint",
channel=http.ChannelField(
pointer="/value",
json_type="number",
channel=setpoint_cmd.key,
),
),
],
)
# Configure the task with Synnax
client.tasks.configure(task)
# Start task and send commands
with task.run():
with client.open_writer(
start=sy.TimeStamp.now(),
channels=[http_cmd_time.key, setpoint_cmd.key],
enable_auto_commit=True,
) as writer:
writer.write({
http_cmd_time.key: sy.TimeStamp.now(),
setpoint_cmd.key: 42.0,
})
writer.commit() Use static and generated fields
import synnax as sy
from synnax import http
client = sy.Synnax()
dev = client.devices.retrieve(name="My HTTP Server")
http_cmd_time = client.channels.create(
name="http_cmd_time",
is_index=True,
data_type=sy.DataType.TIMESTAMP,
retrieve_if_name_exists=True,
)
setpoint_cmd = client.channels.create(
name="http_setpoint_cmd",
index=http_cmd_time.key,
data_type=sy.DataType.FLOAT64,
retrieve_if_name_exists=True,
)
# Each request body will contain:
# {
# "value": <channel value>,
# "source": "synnax",
# "request_id": "<generated uuid>"
# }
task = http.WriteTask(
name="HTTP Write Task",
device=dev.key,
endpoints=[
http.WriteEndpoint(
method="POST",
path="/api/v1/control",
channel=http.ChannelField(
pointer="/value",
json_type="number",
channel=setpoint_cmd.key,
),
fields=[
http.StaticWriteField(
pointer="/source",
json_type="string",
value="synnax",
),
http.GeneratedWriteField(
pointer="/request_id",
generator="uuid",
),
],
),
],
)
client.tasks.configure(task)