デバイスグループ管理API
デバイスグループは、そのグループのメンバーであるAlexa搭載デバイスに話しかけることでユーザーがまとめて制御できるデバイスのグループを表します。ターゲット設定には、暗黙の設定と明示的な設定があります。明示的なターゲット設定は、「アレクサ、リビングの照明をつけて」のように、ユーザーがデバイスグループ名を指定した場合になされます。 暗黙のターゲット設定は、ユーザーがグループ名を指定しなかった場合になされます。たとえば、デバイスグループに含まれているデバイスにユーザーが「アレクサ、照明をつけて」と話しかけた場合、Alexaはそのグループに属するすべての照明をつけます。デバイスグループに属するデバイスは概して同じ物理空間内に存在します。ただし、これは必須ではありません。
Alexa Smart Propertiesでは、デバイスグループ管理APIを使用して、ユニットにデバイスのグループを作成できます。
APIエンドポイント
リクエストヘッダーでは、組織が所在する地域に応じて、Host
を以下のいずれかに設定してください。
国 | エンドポイント |
---|---|
カナダ、米国 |
|
ドイツ、スペイン、フランス、イタリア、英国 |
|
日本 |
|
認証
すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。
操作
デバイスグループAPIには、以下の操作が用意されています。
操作 | HTTPメソッドとURI |
---|---|
| |
| |
| |
| |
| |
|
デバイスグループを作成する
POST /v1/deviceGroups
を呼び出すと、デバイスグループを作成できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
POST /v1/deviceGroups HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
なし。
リクエスト本文の形式
{
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "{groupFriendlyName}"
}
},
"memberDevices": [
{
"id": "amzn1.alexa.endpoint.{endpointId}"
}
],
"associatedUnits": [
{
"id": "amzn1.alexa.unit.did.{UnitId}"
}
]
}
リクエスト本文の例
{
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "kitchen"
}
},
"memberDevices": [
{
"id": "amzn1.alexa.endpoint.es2fiL0v9nOJlfYf5Raw7Ff90bv7tAJkie3p3Zzf4C7svpIEL4GcGh8lQdBbYWIjqfA2ydFEvzy_kG3QBOg2MRUBDR0StBHCwNombp4-2N7SY8H1JCQxKO0mKO1Ez5VX3QPItZ26rEvnqpjjday41DZ0lz4lNZAHpoc0GuvX6M4uRKO9wFuTklf7XZf1EOiRLyKQg0rPBE1V7epjFqVRKtAZluxMmZkCgQJ30Mwt4MxQFmha-Ypfm0s2vzpXqe6"
}
],
"associatedUnits": [
{
"id": "amzn1.alexa.unit.did.7R9ITXF3SHFHJDGQYSAXJ9C7E78CA2DD3C1NM2RN70BSELVVZ1EDZZC4KVQ6GLZ72W0QXDIQ49RT5CMPU91DW6ZTSKA6HPQI3LAPZYMY"
}
]
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
friendlyName |
デバイスグループのフレンドリー名。NameValue オブジェクトとして指定します。ユニットのどのデバイスグループにも一意の名前が必要です。 |
NameValueオブジェクト | ◯ |
memberDevices |
デバイスグループに追加するデバイス。 • リストに含まれるすべてのエンドポイントが存在しており、呼び出し元にそのエンドポイントへのアクセス権限がある必要があります。 • リストに含まれるすべてのデバイスが、作成しているグループと同じユニットと関連付けられている必要があります。 • リストは空でも構いません。 |
Endpoint オブジェクトのリスト |
✕ |
associatedUnits |
デバイスグループと関連付けるユニットのID。 • ユニットは1つのみ指定してください。 • 指定されるユニットが存在しており、呼び出し元にそのユニットへのアクセス権限がある必要があります。 • デバイスグループの作成後に、関連付けられたユニットを変更することはできません。 • デバイスグループの作成後に、ユニットをそのデバイスグループに関連付けることはできません。 |
Unit オブジェクトのリスト |
◯ |
NameValueオブジェクト
フィールド | 説明 | 型 |
---|---|---|
type |
名前の値のタイプ。現時点でサポートされる値は、"PLAIN" のみです。 |
文字列 |
value |
名前の値。Value オブジェクトとして指定します。 |
オブジェクト |
Valueオブジェクト
フィールド | 説明 | 型 |
---|---|---|
text |
文字列値。 | 文字列 |
Endpointオブジェクト
フィールド | 説明 | 型 |
---|---|---|
id |
エンドポイントID。"amzn1.alexa.endpoint.{endpointId}" というAmazon Common Identifier(ACI)形式で指定します。 |
文字列 |
DeviceGroupオブジェクト
フィールド | 説明 | 型 |
---|---|---|
id |
デバイスグループID。"amzn1.alexa.endpointGroup.{deviceGroupId}" というAmazon Common Identifier(ACI)形式で指定します。 |
文字列 |
friendlyName |
デバイスグループのフレンドリー名。 | NameValue オブジェクト |
memberDevices |
デバイスグループのメンバーであるデバイス。 | Endpoint オブジェクトのリスト |
associatedUnits |
デバイスグループと関連付けられているユニットのID。現在、指定できるユニットIDは1つのみです。 | Unit オブジェクトのリスト |
Unitオブジェクト
フィールド | 説明 | 型 |
---|---|---|
id |
ユニットID。"amzn1.alexa.unit.did.{UnitId}" 形式で指定します。 |
文字列 |
成功応答のヘッダー
Host
値は、リクエストのHost
値と同じになります。HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
応答本文の例
{
"id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g"
}
応答本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
新しいデバイスグループのデバイスグループID。"amzn1.alexa.endpointGroup.{deviceGroupId}" 形式で指定します。 |
文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラーのエラータイプ。 | 文字列 | ◯ |
message |
エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 | 文字列 | ◯ |
HTTP応答コード
ステータスコード | 型 | メッセージ | 説明 |
---|---|---|---|
201 | CREATED | Created | リクエストが成功しました。 |
400 | BAD_REQUEST | Bad Request | リクエストの形式が、次のいずれかの理由で正しくありません。 • 指定されたフレンドリー名のデバイスグループが、指定された関連付けられているユニットに既に存在しています。 • 指定された関連付けられているユニットが存在しないか、呼び出し元にそのユニットへのアクセス権限がありません。 • 指定されたメンバーデバイスが存在しないか、呼び出し元にそのメンバーデバイスへのアクセス権限がありません。 • 指定されたメンバーデバイスに、デバイスグループと同じユニットが関連付けられていません。 • 指定されたAlexa搭載メンバーデバイスは、既に別のデバイスグループのメンバーデバイスです。 |
401 | UNAUTHORIZED | Unauthorized | 認可が失敗しました。 |
403 | FORBIDDEN | Forbidden | リクエストを完了できませんでした。 |
429 | TOO_MANY_REQUESTS | Too Many Requests | リクエストが制限されました。 |
500 | INTERNAL_SERVER_ERROR | Internal Server Error | サーバー側のエラーが発生しました。 |
503 | SERVICE_UNAVAILABLE | Service Unavailable | サービスが一時的に使用できません。 |
デバイスグループにデバイスを追加する
POST /v1/deviceGroups/{id}/memberDevices
を呼び出すと、デバイスをデバイスグループに追加できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
POST /v1/deviceGroups/{id}/memberDevices HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
デバイスグループID。有効なデバイスグループを表している必要があります。 | 文字列 | ◯ |
リクエスト本文の形式
{
"memberDevice": {
"id": "{endpointId}"
}
}
リクエスト本文の例
{
"memberDevice": {
"id": "amzn1.alexa.endpoint.W28D0yZ5FzcjByRRnEQwmUHC1tZAncTyo8ekrOky8oVUtkayVpomPYpy7gjIVGDa5VoiRpNT8AKJGtmD92xmV2hlzIyBQSzYrELdsIBSXxSrahd375XACr2iuyo2POKCBbgYBaCSzIvXoklLdAEugOMk5WG8gi1sh4l7IBVoQ9RwzkPp731ZbTtnjHyC5WCceM4s5a9RFtrYDD3ejoER5RBX3o0W7FYtGlM3faDbgTPeL1Nr4cWoyIAguRK4J2P"
}
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
memberDevice |
デバイスグループにメンバーとして追加するデバイス。 • 有効なEndpointオブジェクトを表している必要があります。 • エンドポイントが存在しており、呼び出し元にそのエンドポイントへのアクセス権限がある必要があります。 • エンドポイントが追加先のデバイスグループと同じユニットに関連付けられている必要があります。 |
Endpointオブジェクト | ◯ |
成功応答のヘッダー
Host
値は、リクエストのHost
値と同じになります。HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラーのエラータイプ。 | 文字列 | ◯ |
message |
エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 | 文字列 | ◯ |
HTTP応答コード
ステータスコード | 型 | メッセージ | 説明 |
---|---|---|---|
204 | NO_CONTENT | No Content | リクエストが成功しました。 |
400 | BAD_REQUEST | Bad Request | リクエストの形式が、次のいずれかの理由で正しくありません。 • 指定されたメンバーデバイスが存在しないか、呼び出し元にそのメンバーデバイスを使用する権限がありません。 • 指定されたメンバーデバイスに、デバイスグループと同じユニットが関連付けられていません。 • 指定されたAlexa搭載メンバーデバイスは、既に別のデバイスグループのメンバーデバイスです。 |
401 | UNAUTHORIZED | Unauthorized | 認可が失敗しました。 |
403 | FORBIDDEN | Forbidden | リクエストを完了できませんでした。 |
404 | NOT_FOUND | Not Found | 指定されたデバイスグループが存在しないか、呼び出し元にそのデバイスグループへのアクセス権限がありません。 |
429 | TOO_MANY_REQUESTS | Too Many Requests | リクエストが制限されました。 |
500 | INTERNAL_SERVER_ERROR | Internal Server Error | サーバー側のエラーが発生しました。 |
503 | SERVICE_UNAVAILABLE | Service Unavailable | サービスが一時的に使用できません。 |
デバイスグループからデバイスを削除する
DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId}
を呼び出すと、デバイスをデバイスグループから削除できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
デバイスグループID。有効なデバイスグループを表している必要があります。 | 文字列 | ◯ |
endpointId |
デバイスグループから削除するデバイスのエンドポイントID。デバイスグループに属するメンバーデバイスの有効なEndpointオブジェクトを表している必要があります。 | 文字列 | ◯ |
成功応答のヘッダー
Host
値は、リクエストのHost
値と同じになります。HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラーのエラータイプ。 | 文字列 | ◯ |
message |
エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 | 文字列 | ◯ |
HTTP応答コード
ステータスコード | 型 | メッセージ | 説明 |
---|---|---|---|
204 | NO_CONTENT | No Content | リクエストが成功しました。 |
400 | BAD_REQUEST | Bad Request | リクエストの形式が正しくありませんでした。 |
401 | UNAUTHORIZED | Unauthorized | 認可が失敗しました。 |
404 | NOT_FOUND | Not Found | リクエストが次のいずれかの理由で失敗しました。 • 指定されたデバイスグループが存在しないか、呼び出し元にそのデバイスグループへのアクセス権限がありません。 • 指定されたメンバーデバイスがデバイスグループに存在しないか、呼び出し元にそのメンバーデバイスへのアクセス権限がありません。 |
429 | TOO_MANY_REQUESTS | Too Many Requests | リクエストが制限されました。 |
500 | INTERNAL_SERVER_ERROR | Internal Server Error | サーバー側のエラーが発生しました。 |
503 | SERVICE_UNAVAILABLE | Service Unavailable | サービスが一時的に使用できません。 |
デバイスグループのフレンドリー名を変更する
POST /v1/deviceGroups/{id}/friendlyName
を呼び出すと、デバイスグループのフレンドリー名を変更できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
POST /v1/deviceGroups/{id}/friendlyName HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
デバイスグループID。有効なデバイスグループを表している必要があります。 | 文字列 | ◯ |
リクエスト本文の形式
{
"type": "PLAIN",
"value": {
"text": "{groupFriendlyName}"
}
}
リクエスト本文の例
{
"type": "PLAIN",
"value": {
"text": "kitchen"
}
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | |
---|---|---|---|
friendlyName |
デバイスグループの新しいフレンドリー名。NameValueオブジェクトとして指定します。 | NameValueオブジェクト | ◯ |
成功応答のヘッダー
Host
値は、リクエストのHost
値と同じになります。HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラーのエラータイプ。 | 文字列 | ◯ |
message |
エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 | 文字列 | ◯ |
HTTP応答コード
ステータスコード | 型 | メッセージ | 説明 |
---|---|---|---|
204 | NO_CONTENT | No Content | リクエストが成功しました。 |
400 | BAD_REQUEST | Bad Request | リクエストの形式が、次のいずれかの理由で正しくありません。 • 指定されたフレンドリー名のデバイスグループが、指定された関連付けられているユニットに既に存在しています。 |
401 | UNAUTHORIZED | Unauthorized | 認可が失敗しました。 |
403 | FORBIDDEN | Forbidden | リクエストを完了できませんでした。 |
404 | NOT_FOUND | Not Found | 指定されたデバイスグループが存在しないか、呼び出し元にそのデバイスグループへのアクセス権限がありません。 |
429 | TOO_MANY_REQUESTS | Too Many Requests | リクエストが制限されました。 |
500 | INTERNAL_SERVER_ERROR | Internal Server Error | サーバー側のエラーが発生しました。 |
503 | SERVICE_UNAVAILABLE | Service Unavailable | サービスが一時的に使用できません。 |
デバイスグループを削除する
DELETE /v1/deviceGroups/{id}
を呼び出すと、デバイスグループを削除できます。削除を実行すると、デバイスグループからすべてのメンバーデバイスと関連付けられているユニットが削除されますが、引き続き存在はしています。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
DELETE /v1/deviceGroups/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
デバイスグループID。有効なデバイスグループを表している必要があります。 | 文字列 | ◯ |
成功応答のヘッダー
Host
値は、リクエストのHost
値と同じになります。HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラーのエラータイプ。 | 文字列 | ◯ |
message |
エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 | 文字列 | ◯ |
HTTP応答コード
ステータスコード | 型 | メッセージ | 説明 |
---|---|---|---|
204 | NO_CONTENT | No Content | リクエストが成功しました。 |
400 | BAD_REQUEST | Bad Request | リクエストの形式が正しくありませんでした。 |
401 | UNAUTHORIZED | Unauthorized | 認可が失敗しました。 |
404 | NOT_FOUND | Not Found | 指定されたデバイスグループが存在しないか、呼び出し元にそのデバイスグループへのアクセス権限がありません。 |
429 | TOO_MANY_REQUESTS | Too Many Requests | リクエストが制限されました。 |
500 | INTERNAL_SERVER_ERROR | Internal Server Error | サーバー側のエラーが発生しました。 |
503 | SERVICE_UNAVAILABLE | Service Unavailable | サービスが一時的に使用できません。 |
デバイスグループのリストを取得する
GET /v1/deviceGroups
を呼び出すと、デバイスグループのリストを取得できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
GET /v1/deviceGroups?associatedUnits.id={UnitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
なし。
リクエストと応答の例
以下の例では、この呼び出しの使い方を示します。
デフォルト情報のみを含める
この例では、各デバイスグループのデフォルト情報のみを含める方法を示します。
リクエストは以下のとおりです。
GET /v1/deviceGroups?associatedUnits.id=amzn1.alexa.unit.did.KOHSO00IAQYD6S0W5GWBKF1U2JQFDK1GHAJFNPAK4MTCHO0VJNMTJQOQVOVHMOUW4CW5XM0TC4LDRKBA1NLOS6EKPAXDD5AVEY3E5QVN HTTP/1.1
応答は以下のとおりです。
HTTP/1.1 200 OK
{
"paginationContext": {
"nextToken": null
},
"results": [
{
"deviceGroup": {
"id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g"
}
}
]
}
各デバイスグループの詳細を含める
この例では、expand=all
パラメーターを使用して各デバイスグループの詳細を含める方法を示します。
リクエストは以下のとおりです。
GET /v1/deviceGroups?associatedUnits.id=amzn1.alexa.unit.did.GMCCVDN5EIN4PBFQMNRHT7U6H4RDMXNEYAIHYX4C1IVX3RARAEAZJU1KMAC74VFK00TPD0PWWITP991M4E6UE14KW2Q4BGM0X0PEMEHD&expand=all HTTP/1.1
応答は以下のとおりです。
HTTP/1.1 200 OK
{
"paginationContext": {
"nextToken": null
},
"results": [
{
"deviceGroup": {
"id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g",
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "kitchen"
}
},
"memberDevices": [
{
"id": "amzn1.alexa.endpoint.BmX5E58b3nEKsmwSwKs6NofAP9eNe3jFs9C5aa3Ui49CAnpmkwKiZ58OhdPrsMVzxjZkgn5TWrFioHkACNhAmNKximBGWTpfBzh1IpJIR14b0gfT83evGBCvMBf0HpAz9HEzBqnToo1NnSjBGUqpiFUr8FfrCa26bNYdqhsIZ8aNlOdmb8UK4dT2tQnYn52MFP9x4lkfGsXN93YIaI3ur42GxuvO5CFOBgJ8ALPf7UDCMadoZ3WM3db2cZ2EW92"
}
],
"associatedUnits": [
{
"id": "amzn1.alexa.unit.did.7RBKKY0AGCGS9WWGNGG6QLFJQ2U6XADPWRQCS15O7DWNO62U0AAHYF5B79I018JMGLFWQTRUHTGSI7BA7A9CEOD929TBP253R82V03R3"
}
]
}
}
]
}
リクエストのクエリパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
associatedUnits.id |
ユニットID。ここに指定されたユニットに関連付けられているデバイスグループに結果を絞り込みます。 | 文字列 | ◯ |
maxResults |
1回の呼び出しで取得する結果の最大数。値は1~10の間で指定します。デフォルト値は10です。 | 整数 | ✕ |
nextToken |
nextToken の値を次回のリクエストで継続トークン(nextToken クエリパラメーター)に指定すると、結果の次のページを取得できます。最初のリクエストと同じフィルターパラメーターを指定する必要があります。パラメーターが変更されていると、400 Bad Requestが返されます。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
文字列 | ✕ |
expand |
応答で返すプロパティのセット。現時点でサポートされる値は、"all" のみです。このパラメーター指定がない場合、"id" プロパティのみが返されます。 |
文字列 | ✕ |
成功応答のヘッダー
Host
値は、リクエストのHost
値と同じになります。HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
応答本文のパラメーター
フィールド | 説明 | 型 | 詳細な結果のみ |
---|---|---|---|
paginationContext |
ページ分割情報を含むオブジェクト。これがある場合、応答に含まれている結果は不完全です。ない場合は、すべての結果が既に返されています。詳細については、クエリ結果のページ分割を処理するを参照してください。 | オブジェクト | ✕ |
paginationContext.nextToken |
nextToken の値は、次回のオブジェクトセットのリストを表示する継続トークンとして次回のリクエストで使用します。 |
文字列 | ✕ |
results |
クエリへの応答で返されたデバイスグループのリスト。 | DeviceGroup オブジェクトのリスト |
✕ |
results.deviceGroup |
デバイスグループオブジェクト。 | DeviceGroup オブジェクト |
✕ |
results.deviceGroup.id |
デバイスグループID。"amzn1.alexa.endpointGroup.{deviceGroupId}" というAmazon Common Identifier(ACI)形式で指定します。 |
文字列 | ✕ |
results.deviceGroup.friendlyName |
デバイスグループのフレンドリー名。 | NameValue オブジェクト |
◯ |
results.deviceGroup.memberDevices |
デバイスグループのメンバーであるデバイス。 | Endpoint オブジェクトのリスト |
◯ |
results.deviceGroup.associatedUnits |
デバイスグループと関連付けられているユニットのID。現在、指定できるユニットIDは1つのみです。 | Unit オブジェクトのリスト |
◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラーのエラータイプ。 | 文字列 | ◯ |
message |
エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 | 文字列 | ◯ |
HTTP応答コード
ステータスコード | 型 | メッセージ | 説明 |
---|---|---|---|
200 | OK | OK | リクエストが成功しました。 |
400 | BAD_REQUEST | Bad Request | リクエストの形式が、次のいずれかの理由で正しくありません。 • 無効か有効期限の切れた nextToken 値が指定されていました。• 有効な nextToken 値が指定されていたが、フィルターパラメーターが前回のリクエストのパラメーターと一致しませんでした。• 無効な maxResults 値が指定されていました。 |
401 | UNAUTHORIZED | Unauthorized | 認可が失敗しました。 |
403 | FORBIDDEN | Forbidden | リクエストを完了できませんでした。 |
429 | TOO_MANY_REQUESTS | Too Many Requests | リクエストが制限されました。 |
500 | INTERNAL_SERVER_ERROR | Internal Server Error | サーバー側のエラーが発生しました。 |
503 | SERVICE_UNAVAILABLE | Service Unavailable | サービスが一時的に使用できません。 |
関連トピック
最終更新日: 2024 年 03 月 21 日