Google Cloud IoT Core Connector Guide

The Google Cloud IoT Core connector lets Tealfabric workflows call Cloud IoT Core REST endpoints with service account credentials for device and registry operations. This guide explains practical setup and request patterns for environments where IoT Core endpoints are still available.

Important lifecycle note

Google Cloud IoT Core has been discontinued by Google Cloud for general use. Use this connector only for supported legacy environments or platform-specific compatibility layers where the endpoint behavior remains available. Validate support status before building new production dependencies.

When to use this connector

Use this connector when your workflow must query device registry metadata or dispatch commands to devices through legacy IoT Core-style APIs. It is useful for migration bridges and controlled compatibility workloads where existing device logic still depends on these endpoints. Explicit endpoint paths and clear retry rules are essential for reliability.

Configuration reference

Connector settings are stored in integration configuration and applied to all operations. Keep service account credentials secure and rotate them with your GCP key policy.

• project_id (required): Google Cloud project ID.
• region (required): Registry region, such as us-central1.
• registry_id (required): Target device registry ID.
• service_account_key (required): Service account JSON key with required permissions.
• timeout_seconds (optional): Request timeout for connector calls.

List devices from a registry

The receive operation can query device metadata for monitoring, reconciliation, or migration workflows. Limit the fields you request to keep responses efficient.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type DeviceRecord = {
  id?: string;
  name?: string;
  lastHeartbeatTime?: string;
};

async function listIoTDevices(integrationId: string): Promise<DeviceRecord[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "receive",
        endpoint:
          "projects/<ENTITY_ID>/locations/us-central1/registries/<ENTITY_ID>/devices",
        query: {
          fieldMask: "id,name,lastHeartbeatTime",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { data?: DeviceRecord[] };
  if (!payload.data) throw new Error("Missing IoT device payload");
  return payload.data;
}

Send commands to a device

Use send to issue device commands through the registry path. Include retry and timeout handling for disconnected or intermittently connected devices.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "endpoint": "projects/<ENTITY_ID>/locations/us-central1/registries/<ENTITY_ID>/devices/<ENTITY_ID>:sendCommandToDevice",
    "method": "POST",
    "data": {
      "binaryData": "eyJtb2RlIjoicmVzZXQifQ==",
      "subfolder": "commands"
    }
  }'

{
  "success": true,
  "data": {
    "status": "queued",
    "device_id": "<ENTITY_ID>"
  }
}

Validate and troubleshoot

Run test before production cutover and after any service account or IAM policy changes. Common failures include missing roles, invalid endpoint paths, and device connectivity state at command time. Log execution IDs and endpoint payloads to speed up troubleshooting.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "status": "ok",
    "project_id": "<ENTITY_ID>",
    "registry_id": "<ENTITY_ID>"
  }
}