API を使用する

アクセス トークンを入手し、デバイスリストの最初の呼び出しを行ったら、 SDM API を使用してデバイスにアクセスし、操作する準備が整いました。

ストラクチャとデバイスを一覧表示する

curl を使用して、structures エンドポイントへの簡単な GET 呼び出しを行います。

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/structures' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

呼び出しに成功すると、アカウントにリンクされているアカウントのストラクチャのリストが返されます。 Device Access プロジェクト:

{
  "structures": [
    {
      "name": "enterprises/project-id/structures/structure-id",
      "traits": {
        "sdm.structures.traits.Info": {
          "customName": "structure-name"
        }
      }
    }
  ]
}

まだ行っていない場合は、devices エンドポイントに対して GET 呼び出しを行って、 デバイスのリストを取得します。

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

呼び出しが成功すると、 Device Accessプロジェクトにリンクされているデバイスのリストが返されます。各デバイスには、それぞれ固有の利用可能なトレイトリストがあります。

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

各デバイスの device-id をコピーします（他の API 呼び出しで必要になります）。

デバイスの情報を取得する

特定のデバイスの情報を取得するには、device-id に GET 呼び出しを行います。 endpoint:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

レスポンスは前回と同様ですが、特定のデバイスに関するものです。

{
  "name": "enterprises/project-id/devices/device-id",
  "type": "sdm.devices.types.device-type",
  "traits": { ... },
  "parentRelations": [
    {
      "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
      "displayName": "device-room-name"
    }
  ]
}

コマンドの実行

GET 呼び出しが成功してアクセスを検証したら、 コマンドを実行する方法は、承認したデバイスの種類によって異なります。

サーモスタット

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.ThermostatMode.SetMode",
    "params" : {
      "mode" : "HEAT"
    }
  }'

カメラ

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.CameraLiveStream.GenerateRtspStream",
    "params" : {}
  }'

呼び出しが成功すると、次のようになります。

サーモスタット

空のレスポンスが返され、物理的なサーモスタットが温度を コマンド パラメータで指定したモードに変更します。

{}

カメラ

ライブ配信の URL と関連トークンが届きます。

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

トラブルシューティング

未認証

SDM API のアクセス トークンは 1 時間のみ有効です。条件 UNAUTHENTICATED レスポンスが返された場合、トークンの有効期限が切れている可能性があります。 更新トークンを取得して、新しいトークンを できます。

その他のエラー

Device Access エラーコードの一覧については、エラーコード リファレンスをご覧ください。