Using the HTTP Bridge

This section explains how devices can use the HTTP bridge to communicate with Cloud IoT Core. For general information about HTTP and MQTT, see Protocols.

Be sure to refer to the API documentation for full details about each method described in this section.

Complete these steps before using the HTTP bridge:

  • Set up one or more device registries, including a Cloud Pub/Sub topic for telemetry events
  • Create devices

Device authentication

Each request to the HTTP bridge must include a JSON Web Token (JWT) in the header.


The JWT in this example is for illustration purposes only.

curl -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDU2ODk1MDgsImV4cCI6MTUwNTY5MzEwOCwiYXVkIjoibXktZ2NwLXByb2plY3QifQ' -H 'cache-control: no-cache' '{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}/config?local_version=1'

Each request must include the JWT, even if you send several requests in quick succession. Cloud IoT Core does not "remember" authentication over the HTTP bridge.

For more information about authentication and JWTs, see the sections on device security and device credentials.

Publishing telemetry events

Use the publishEvent method to publish telemetry events to Cloud IoT Core. Binary payload data must be base64-encoded.


curl -X POST -H 'authorization: Bearer YOUR_JWT' -H 'content-type: application/json' --data '{"binary_data": "YOUR_DATA"}' -H 'cache-control: no-cache' '{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}:publishEvent'

Telemetry events are forwarded to a Cloud Pub/Sub topic, as specified in GCP Console or with the eventNotificationConfigs[i].pubsubTopicName field in the device registry resource. The publishEvent method provides an optional subFolder field for classifying telemetry events. To learn how to publish data from subfolders to separate Pub/Sub topics, see the section below.

NOTE: If you try to publish a device telemetry event without specifying a Cloud Pub/Sub topic for the device's registry, the method fails and returns an error. This applies only to telemetry events, not state data.

Publishing telemetry events to separate Pub/Sub topics

Devices can publish data to separate Pub/Sub topics by specifying a subfolder in the subFolder field in the publishEvent method. This subfolder must be configured in the device registry resource's eventNotificationConfigs.subfolderMatches field with a matching Pub/Sub topic in the eventNotificationConfigs.pubsubTopicName field. When data is sent to a subfolder, it is published to the subfolder's matching Pub/Sub topic.

As detailed in Creating a device registry, all device registries should have one default Pub/Sub topic with no matching subfolder. If a default Pub/Sub topic exists, devices automatically publish to it in the following cases:

  • No subfolder is specified in the subFolder field
  • A subfolder is specified in the subFolder field, but it doesn't have a matching Pub/Sub topic in the device registry

In each of these cases, if no default Pub/Sub topic exists, data sent from the device will be lost.


curl -X POST -H 'authorization: Bearer YOUR_JWT' -H 'content-type: application/json' --data '{"binary_data": "YOUR_DATA", "sub_folder": "YOUR_SUBFOLDER"}' -H 'cache-control: no-cache' '{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}:publishEvent'

Excessive load and exponential backoff

Cloud IoT Core limits projects that generate excessive load. When devices retry failed operations without waiting, they can trigger limits that affect all devices in the same Google Cloud Platform project.

For retries, you are strongly encouraged to implement a truncated exponential backoff algorithm with introduced jitter.

Configuring devices

You can use Cloud IoT Core to configure devices. A device configuration consists of binary data that can be used to update firmware, reboot a device, turn on a feature, or change other properties.

To configure a device using the HTTP bridge, first define the configuration in Cloud IoT Core, then request the configuration via the device.

Compressing HTTP requests

A device can send gzip-compressed data to Cloud IoT Core over the HTTP bridge. To send compressed data to Cloud IoT Core, each HTTP request must include the content-encoding: gzip HTTP header.

Compressing data lets you reduce bandwidth in the device-to-cloud direction. However, you cannot reduce the total cost of your Cloud IoT Core usage by compressing data. For details, see Pricing.

Updating device configuration

When using the HTTP bridge, the device must explicitly request device configurations with the API. Cloud IoT Core does not push configurations to devices over the HTTP bridge; instead, devices must poll for new configurations.

To get the device configuration that's currently available from Cloud IoT Core, use a getConfig request. You can use the localVersion query parameter to specify the configuration version that's currently on the device. The following table shows how this parameter affects the response:

Device version API response
localVersion is 0 (default value) Most recent version from Cloud IoT Core
localVersion is nonzero and equal to the version currently available from Cloud IoT Core OK (with empty configuration in the binary_data field)
localVersion is nonzero and older (lower than) the version currently available from Cloud IoT Core Current (newer) version from Cloud IoT Core
localVersion is nonzero and newer (higher than) the version currently available from Cloud IoT Core OUT_OF_RANGE error


curl -H 'authorization: Bearer YOUR_JWT' -H 'cache-control: no-cache' '{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}/config?local_version=0'

Setting device state

Use a setState request to report device state to Cloud IoT Core. State data must be base64-encoded.


curl -X POST -H 'authorization: Bearer YOUR_JWT' -H 'content-type: application/json' --data '{"state": {"binary_data": "YOUR_DATA"}}' -H 'cache-control: no-cache' '{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}:setState'

To retrieve device state data, view the device details in Cloud Console or use the API. For more details, see the section on device state.

Was this page helpful? Let us know how we did:

Send feedback about...

Google Cloud Internet of Things Core