デバイスグループ管理REST APIリファレンス

デバイスグループ管理REST APIリファレンス

デバイスグループ管理REST APIを使用すると、ユニットにデバイスのグループを作成できます。

デバイスグループは、そのグループのメンバーであるAlexa搭載デバイスに話しかけることでユーザーがまとめて制御できるスマートホームデバイスのグループを表します。ターゲット設定には、暗黙の設定と明示的な設定があります。明示的なターゲット設定は、「アレクサ、リビングの照明をつけて」のように、ユーザーがデバイスグループ名を指定した場合になされます。 暗黙のターゲット設定は、ユーザーがグループ名を指定しなかった場合になされます。たとえば、デバイスグループに含まれているAlexa搭載デバイスにユーザーが「アレクサ、照明をつけて」と話しかけた場合、Alexaはそのグループに属するすべての照明をつけます。デバイスグループに属するデバイスは概して同じ物理空間内に存在します。ただし、これは必須ではありません。

APIエンドポイント

組織が所在する国に応じて、リクエストヘッダーのHostパラメーターを、以下のいずれかのAPIエンドポイントに設定してください。

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

ドイツ、スペイン、フランス、イタリア、英国

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。

操作

デバイスグループAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

デバイスグループにデバイスを追加する

POST /v1/deviceGroups/{id}/memberDevices

グループのフレンドリー名を変更する

POST /v1/deviceGroups/{id}/friendlyName

デバイスグループを作成する

POST /v1/deviceGroups

デバイスグループを削除する

DELETE /v1/deviceGroups/{id}

デバイスグループのリストを取得する

GET /v1/deviceGroups?associatedUnits.id={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1

グループからデバイスを削除する

DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId}

デバイスグループにデバイスを追加する

既存のデバイスグループにデバイスを追加します。一度に追加できるデバイスは1つだけです。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

デバイスを追加するには、/v1/deviceGroupsリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v1/deviceGroups/{id}/memberDevices HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

id

パス

既存のデバイスグループを識別します。
amzn1.alexa.endpointGroup.{id}という形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
    "memberDevice": {
        "id": "amzn1.alexa.endpoint.2"
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

memberDevices

デバイスグループに追加するエンドポイント。

  • エンドポイントが存在しており、呼び出し元にそのエンドポイントへのアクセス権限がある必要があります。
  • エンドポイントがデバイスグループと同じユニットに関連付けられている必要があります。
  • Alexa搭載エンドポイントは1つのデバイスグループにのみ追加できます。
  • スマートホームエンドポイントは複数のデバイスグループに追加できます。Amazonでは、スマートホームエンドポイントはAmazon Echo以外のデバイスと考えられます。

オブジェクト

◯

memberDevices.id

エンドポイントの一意のID。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

エンドポイントがデバイスグループに正常に追加されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

グループのフレンドリー名を変更する

デバイスグループのフレンドリー名を変更します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

フレンドリー名を変更するには、/v1/deviceGroups/{id}/friendlyNameリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v1/deviceGroups/{id}/friendlyName HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

id

パス

既存のデバイスグループを識別します。
amzn1.alexa.endpointGroup.{id}という形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
  "type": "PLAIN",
  "value": {
    "text": "entryway"
  }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

type

値フィールドの形式。現時点でサポートされる形式は、プレーンテキストのみです。
有効な値は PLAINです。

文字列

◯

value

名前を表します。

オブジェクト

◯

value.text

プレーンテキストで指定されたフレンドリー名。名前には、1文字以上の数字または文字が含まれている必要があります。
有効な値は 1～128文字のUnicode（UTF-8）文字です。
使用できる文字は、数字、文字、空白、アポストロフィです。漢字や非ラテン文字は使用できますが、その他の特殊文字や句読点は使用できません。

文字列

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

フレンドリー名が正常に変更されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

デバイスグループを作成する

新しいデバイスグループを作成します。グループへのデバイスの追加は、この操作で行うことも、デバイスグループにデバイスを追加する操作を使用して後から行うこともできます。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

デバイスグループを作成するには、/v1/deviceGroupsリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v1/deviceGroups HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
    "friendlyName": {
        "type": "PLAIN",
        "value": {
            "text": "kitchen"
        }
    },
    "memberDevices": [{
        "id": "amzn1.alexa.endpoint.1"
    }],
    "associatedUnits": [{
        "id": "amzn1.alexa.unit.did.101"
    }]
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

friendlyName

デバイスグループの名前。
同じユニット内ではどのデバイスグループにも一意の名前が必要です。

NameValueオブジェクト

◯

memberDevices

グループ内のエンドポイントのリスト。

  • リストに含まれるすべてのエンドポイントが存在しており、呼び出し元にそのエンドポイントへのアクセス権限がある必要があります。
  • リストに含まれるすべてのエンドポイントが、新しいデバイスグループと同じユニットに関連付けられている必要があります。
  • Alexa搭載エンドポイントは1つのデバイスグループにのみ追加できます。
  • スマートホームエンドポイントは複数のデバイスグループに追加できます。Amazonでは、スマートホームエンドポイントはAmazon Echo以外のデバイスと考えられます。
  • リストは空でも構いません。

オブジェクトの配列

✕

memberDevices[].id

エンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

associatedUnits

デバイスグループに関連付けられているユニットのリスト。

  • 現時点では、グループを関連付けることができるユニットは1つです。
  • ユニットが存在しており、呼び出し元にそのユニットへのアクセス権限がある必要があります。
  • デバイスグループを作成した後は、グループにユニットを追加することはできません。

オブジェクトの配列

◯

associatedUnits[].id

ユニットの一意のID。
unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

応答

正常に完了すると、HTTP 201 Createdと共に、デバイスグループのIDが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、応答の例です。

{
    "id": "amzn1.alexa.endpointGroup.1"
}

応答本文のプロパティ

プロパティ 説明 型

id

新しいデバイスグループを識別します。
amzn1.alexa.endpointGroup.{id}という形式で表します。

文字列

HTTPステータスコード

ステータス 説明

201 Created

デバイスグループが正常に作成されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

デバイスグループを削除する

指定されたデバイスグループを削除します。この操作で削除を実行すると、デバイスグループからすべてのメンバーデバイスと関連付けられているユニットが削除されますが、グループとユニットは引き続き存在します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

デバイスグループを削除するには、/v1/deviceGroups/{id}リソースに対してDELETEリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

DELETE /v1/deviceGroups/{id}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

id

パス

既存のデバイスグループを識別します。
amzn1.alexa.endpointGroup.{id}という形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

デバイスグループが正常に削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

デバイスグループのリストを取得する

指定されたユニットのデバイスグループのリストを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

デバイスグループのリストを取得するには、/v1/deviceGroupsリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v1/deviceGroups?associatedUnits.id={unitId}&expand=all&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

unitId

クエリ

ユニットの一意のID。
unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

expand

クエリ

デバイスグループの詳細（フレンドリー名、グループメンバーなど）を返します。
有効な値はallです。

文字列

✕

maxResults

クエリ

応答で返される結果の最大数。
有効な値は 1～50です。デフォルト値は 10です。

Integer

✕

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。

文字列

✕

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、指定されたユニットに定義されているグループのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答本文のプロパティ

プロパティ 説明 型

results

指定されたユニットに関連付けられているデバイスグループのリスト。
グループが定義されていない場合、このリストは空になります。

オブジェクトの配列

results[].deviceGroup

ユニットに関連付けられているデバイスグループを識別します。

オブジェクト

results[].deviceGroup.id

デバイスグループを識別します。
amzn1.alexa.endpointGroup.{id}という形式で表します。

文字列

results[].deviceGroup.friendlyName

（任意）デバイスグループの名前。
同じユニット内のすべてのデバイスグループには一意の名前が付けられています。

NameValueオブジェクト

results[].deviceGroup.memberDevices

（任意）グループのメンバーであるエンドポイントのリスト。

オブジェクトのリスト

results[].deviceGroup.memberDevices[].id

メンバーデバイスの一意のID。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].deviceGroup.associatedUnits

（任意）デバイスグループに関連付けられているユニットのリスト。
現時点では、グループを関連付けることができるユニットは1つです。

オブジェクトのリスト

results[].deviceGroup.associatedUnits[].id

ユニットの一意のID。
unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。
詳細については、クエリ結果のページ分割を処理するを参照してください。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。この値は後続のリクエストで使用します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

ユニットのデバイスグループのリストが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

グループからデバイスを削除する

デバイスグループから指定されたデバイスを削除します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

グループからデバイスを削除するには、/v1/deviceGroups/{id}/memberDevices/リソースに対してDELETEリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

id

パス

既存のデバイスグループを識別します。
amzn1.alexa.endpointGroup.{id}という形式で表します。

文字列

◯

endpointId

パス

グループから削除するデバイスを識別します。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

指定されたデバイスグループからエンドポイントが正常に削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

オブジェクトの定義

デバイスグループAPIでは、以下のオブジェクト定義が定義されています。

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
プロパティ 説明 型

type

発生したエラーのタイプ。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

NameValueオブジェクト

NameValueオブジェクトは、オブジェクトの名前のコンテナーです。

以下の表は、オブジェクトのプロパティの定義です。

プロパティ 説明 型

type

値フィールドの形式。現時点でサポートされる形式は、プレーンテキストのみです。
有効な値は PLAINです。

文字列

value

名前。

オブジェクト

value.text

プレーンテキストで指定された名前。

文字列

このページは役に立ちましたか？

最終更新日: 2024 年 11 月 18 日