エンドポイントAPI
エンドポイントREST APIを使用して、Amazon EchoデバイスやAlexaコネクテッド照明など、Alexa Smart Properties(ASP)のAlexaコネクテッドデバイスを管理できます。エンドポイントは、ASPのゲストや居住者が操作できるAlexaコネクテッドデバイスを表します。このAPIを使用すると、Amazonビジネスアカウントで所有されているデバイスの列挙や、エンドポイントと特定のルームの関連付けを行うことができます。
エンドポイントAPIは、エンドポイントの管理を行う以下のAPIと共に使用できます。
- デバイスの住所、タイムゾーン、接続ステータスなど、デバイスの設定を表示・更新する場合は、エンドポイント設定REST APIリファレンスを参照してください。
- スマートホーム照明の電源状態など、エンドポイントのプロパティを表示・更新する場合は、エンドポイント機能REST APIリファレンスを参照してください。
APIエンドポイント
組織が所在する国に応じて、リクエストヘッダーのHost
パラメーターを、以下のいずれかのAPIエンドポイントに設定してください。
国 | エンドポイント |
---|---|
カナダ、米国 |
|
ドイツ、スペイン、フランス、イタリア、英国 |
|
日本 |
|
認証
すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。
操作
エンドポイントAPIには、以下の操作が用意されています。
操作 | HTTPメソッドとURI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
エンドポイントを所有者別に取得する
Amazonビジネスアカウントに登録されているエンドポイントのリストを取得します。エンドポイントを照会する(詳細検索)操作を使用してエンドポイントを取得することもできます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
エンドポイントのリストを所有者別に取得するには、/v2/endpoints
リソースに対してGET
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
GET /v2/endpoints?owner={owner}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
クエリ |
エンドポイントをフィルタリングして、所有者に関連付けられているエンドポイントを取得します。 |
文字列 |
◯ |
|
クエリ |
各エンドポイントに関する詳細情報を取得します。 |
文字列 |
✕ |
|
クエリ |
応答で返される結果の最大数。 |
整数 |
✕ |
|
クエリ |
前回の応答で受け取ったトークン。 |
文字列 |
✕ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
と共に、エンドポイントのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
以下は、owner=~caller
のクエリパラメーターを含むリクエストへの応答の例です。
以下は、owner=~caller
とexpand=feature:speaker&expand=feature:connectivity
のクエリパラメーターを含むリクエストへの応答の例です。
以下は、owner=~caller
とexpand=all
のクエリパラメーターを含むリクエストへの応答の例です。
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。 |
オブジェクトの配列 |
|
このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。 |
文字列 |
|
(オプション)エンドポイントを識別するためにユーザーが使用する名前。 |
|
|
(オプション)エンドポイントの製造元。 |
|
|
(オプション)エンドポイントのモデル。 |
|
|
(オプション)エンドポイントのシリアル番号。 |
|
|
(オプション)エンドポイントのソフトウェアバージョン。 |
|
|
(オプション)エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。 |
|
|
(オプション)エンドポイントリソースが作成された日時。 |
文字列 |
|
(オプション)エンドポイントで定義されている機能のリスト。 |
|
|
(オプション)エンドポイントに関連付けられているユニットのリスト。 |
オブジェクトの配列 |
|
ユニットID。 |
文字列 |
|
(オプション)この機能とエンドポイントで使用可能な更新操作のリスト。 |
|
|
(オプション)エンドポイントが表示されるAlexaアプリの見出し。 |
文字列 |
|
(オプション)返す結果がほかにもあるかどうかを示します。 |
オブジェクト |
|
応答が分割された場合に含まれます。この値は後続のリクエストで使用します。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
エンドポイントと関連情報のリストが応答本文に含まれます。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントをユニット別に取得する
指定されたユニット(ルーム)に関連付けられているエンドポイントのリストを取得します。エンドポイントを照会する(詳細検索)操作を使用してエンドポイントを取得することもできます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
エンドポイントのリストをユニット別に取得するには、/v2/endpoints
リソースに対してGET
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
GET /v2/endpoints?associatedUnits.id={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
クエリ |
エンドポイントをフィルタリングして、特定のユニットに関連付けられているエンドポイントを取得します。 |
文字列 |
◯ |
|
クエリ |
各エンドポイントに関する詳細情報を取得します。 |
文字列 |
✕ |
|
クエリ |
応答で返される結果の最大数。 |
整数 |
✕ |
|
クエリ |
前回の応答で受け取ったトークン。 |
文字列 |
✕ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
と共に、指定されたユニットに関連付けられているエンドポイントのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
以下は、expand=all
のクエリパラメーターを含むリクエストへの応答の例です。
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。 |
オブジェクトの配列 |
|
このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。 |
文字列 |
|
(オプション)エンドポイントを識別するためにユーザーが使用する名前。 |
|
|
(オプション)エンドポイントの製造元。 |
|
|
(オプション)エンドポイントのモデル。 |
|
|
(オプション)エンドポイントのシリアル番号。 |
|
|
(オプション)エンドポイントのソフトウェアバージョン。 |
|
|
(オプション)エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。 |
|
|
(オプション)エンドポイントリソースが作成された日時。 |
文字列 |
|
(オプション)エンドポイントで定義されている機能のリスト。 |
|
|
(オプション)エンドポイントに関連付けられているユニットのリスト。 |
オブジェクトの配列 |
|
ユニットID。 |
文字列 |
|
(オプション)この機能とエンドポイントで使用可能な更新操作のリスト。 |
|
|
(オプション)エンドポイントが表示されるAlexaアプリの見出し。 |
文字列 |
|
(オプション)返す結果がほかにもあるかどうかを示します。 |
オブジェクト |
|
応答が分割された場合に含まれます。この値は後続のリクエストで使用します。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
指定されたユニットのエンドポイントのリストが応答本文に含まれます。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントをID別に取得する
指定されたエンドポイントのエンドポイントアトリビュートを取得します。呼び出し元には、エンドポイントへのアクセス権限が必要です。
エンドポイントIDを取得するには、エンドポイントを所有者別に取得する、エンドポイントをシリアル番号別に取得する、エンドポイントをユニット別に取得するのいずれかを使用します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
指定されたエンドポイントIDのアトリビュートを取得するには、/v2/endpoints/{endpointId}
リソースに対してGET
リクエストを実行します。このリクエストには、owner
などのフィルタリングパラメーターは必要ありません。
リクエストパスとリクエストヘッダーの例
GET /v2/endpoints/{endpointId}?expand={expand}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
リクエストするエンドポイントのID。 |
文字列 |
◯ |
|
クエリ |
エンドポイントに関する詳細情報を取得します。 |
文字列 |
✕ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
と共に、指定されたエンドポイントに関する情報が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
以下は、指定されたエンドポイントのスピーカー機能と接続機能を取得するexpand=feature:speaker&expand=feature:connectivity
のクエリパラメーターを含むリクエストへの応答の例です。
以下は、指定されたエンドポイントのすべてのアトリビュートを取得するexpand=all
のクエリパラメーターを含むリクエストへの応答の例です。
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。 |
文字列 |
|
(オプション)エンドポイントを識別するためにユーザーが使用する名前。 |
|
|
(オプション)エンドポイントの製造元。 |
|
|
(オプション)エンドポイントのモデル。 |
|
|
(オプション)エンドポイントのシリアル番号。 |
|
|
(オプション)エンドポイントのソフトウェアバージョン。 |
|
|
(オプション)エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。 |
|
|
(オプション)エンドポイントリソースが作成された日時。 |
文字列 |
|
(オプション)エンドポイントで定義されている機能のリスト。 |
|
|
(オプション)エンドポイントに関連付けられているユニットのリスト。 |
オブジェクトの配列 |
|
ユニットID。 |
文字列 |
|
(オプション)この機能とエンドポイントで使用可能な更新操作のリスト。 |
|
|
(オプション)エンドポイントが表示されるAlexaアプリの見出し。 |
文字列 |
|
(オプション)返す結果がほかにもあるかどうかを示します。 |
オブジェクト |
|
応答が分割された場合に含まれます。この値は後続のリクエストで使用します。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
エンドポイントの情報が応答本文に含まれます。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントをシリアル番号別に取得する
指定されたデバイスシリアル番号に関連付けられているエンドポイントを取得します。呼び出し元には、エンドポイントへのアクセス権限が必要です。通常、エンドポイントとシリアル番号は1対1で対応しています。
特定のエンドポイントの検索には、エンドポイントIDを使用することもできます。詳細については、エンドポイントをID別に取得するを参照してください。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
エンドポイントをシリアル番号別に取得するには、/v2/endpoints
リソースに対してGET
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
GET /v2/endpoints?serialNumber.value.text={serialNumber}&expand={expand}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
クエリ |
エンドポイントをフィルタリングして、シリアル番号に関連付けられているエンドポイントを取得します。 |
文字列 |
◯ |
|
クエリ |
エンドポイントに関する詳細情報を取得します。 |
文字列 |
✕ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
と共に、指定されたシリアル番号のエンドポイントが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
以下は、指定されたシリアル番号に関連付けられているエンドポイントを取得するリクエストへの応答の例です。
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。 |
オブジェクトの配列 |
|
このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。 |
文字列 |
|
(オプション)エンドポイントを識別するためにユーザーが使用する名前。 |
|
|
(オプション)エンドポイントの製造元。 |
|
|
(オプション)エンドポイントのモデル。 |
|
|
(オプション)エンドポイントのシリアル番号。 |
|
|
(オプション)エンドポイントのソフトウェアバージョン。 |
|
|
(オプション)エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。 |
|
|
(オプション)エンドポイントリソースが作成された日時。 |
文字列 |
|
(オプション)エンドポイントで定義されている機能のリスト。 |
|
|
(オプション)エンドポイントに関連付けられているユニットのリスト。 |
オブジェクトの配列 |
|
ユニットID。 |
文字列 |
|
(オプション)この機能とエンドポイントで使用可能な更新操作のリスト。 |
|
|
(オプション)エンドポイントが表示されるAlexaアプリの見出し。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
指定されたシリアル番号のエンドポイントが応答本文に含まれます。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントを照会する(詳細検索)
指定した条件に一致するエンドポイントのリストを取得します。この操作では、ユニット、製造元、モデルによる照会がサポートされます。
クエリは複数のAND句またはOR句を使用して作成できます。たとえば、「(ユニットID=amzn1.alexa.unit.unitOne
OR amzn1.alexa.unit.unitTwo
)AND 製造元名=someManufacturer
」という条件を満たすエンドポイントを検索できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
リクエスト
エンドポイントを照会するには、/v2/endpointQuery
リソースにPOST
リクエストを行います。
リクエストヘッダーの例
POST /v2/endpointQuery
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
ヘッダー |
文字列 |
◯ |
リクエスト本文の例
以下は、2つのユニットのエンドポイントを照会するリクエストの例です。
以下は、デバイスの製造元でフィルタリングされた、2つのユニットのエンドポイントを照会するリクエストです。
以下は、デバイスの製造元とモデルでフィルタリングされた、2つのユニットのエンドポイントを照会するリクエストです。
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
クエリのフィルタリング条件。フィールドは、 |
オブジェクト |
◯ |
|
|
オブジェクトの配列 |
✕ |
|
クエリフィールド。このクエリフィールドの値は、返されるエンドポイントの対応する値と完全に一致する必要があります。 |
オブジェクト |
✕ |
|
|
オブジェクトの配列 |
✕ |
|
クエリフィールド。このクエリフィールドの値は、返されるエンドポイントの対応する値と完全に一致する必要があります。 |
オブジェクト |
✕ |
|
取得するエンドポイントアトリビュートのリスト。すべてのエンドポイントアトリビュートを取得する場合は、 |
文字列の配列 |
✕ |
|
結果の特定のページを返すかどうかを示します。 |
オブジェクト |
✕ |
|
ページ分割された結果から特定のページを取得するためのトークン。このトークンがない場合、応答には結果の先頭ページが含められます。 |
文字列 |
✕ |
|
応答本文で返される結果の最大数。 |
数値 |
✕ |
応答
正常に完了すると、HTTP 200 OK
と共に、フィルター条件に一致するエンドポイントのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
以下は、expand
配列でfeature:connectivity
を指定してエンドポイントをフィルタリングするクエリへの応答の例です。
以下は、associatedUnits.id
のエンドポイントを取得する応答の例です。
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。 |
オブジェクトの配列 |
|
このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。 |
文字列 |
|
(オプション)エンドポイントを識別するためにユーザーが使用する名前。 |
|
|
(オプション)エンドポイントの製造元。 |
|
|
(オプション)エンドポイントのモデル。 |
|
|
(オプション)エンドポイントのシリアル番号。 |
|
|
(オプション)エンドポイントのソフトウェアバージョン。 |
|
|
(オプション)エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。 |
|
|
(オプション)エンドポイントリソースが作成された日時。 |
文字列 |
|
(オプション)エンドポイントで定義されている機能のリスト。 |
|
|
(オプション)エンドポイントに関連付けられているユニットのリスト。 |
オブジェクトの配列 |
|
ユニットID。 |
文字列 |
|
(オプション)この機能とエンドポイントで使用可能な更新操作のリスト。 |
|
|
(オプション)エンドポイントが表示されるAlexaアプリの見出し。 |
文字列 |
|
(オプション)返す結果がほかにもあるかどうかを示します。 |
オブジェクト |
|
応答が分割された場合に含まれます。この値は後続のリクエストで使用します。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
フィルタリングされたエンドポイントの情報が応答本文に含まれます。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
関連付けられているユニットを更新する
エンドポイントの関連付けられているユニット(ルーム)のリストを更新します。このAPIは、エンドポイントとユニットの関連付けを解除する場合にも使用します。
エンドポイントとユニットの関連付けを更新する前に、以下の項目を確認してください。
- 現時点では、エンドポイントを関連付けることができるユニットは1つです。
- ユニットの関連付けを変更する場合は、エンドポイントにアクティブな接続が必要です。このAPIの呼び出しに成功してから1分間は、デバイスの電源を入れてオンラインの状態を維持してください。
- エンドポイントをルームに関連付けると、デバイスのフレンドリー名が変更されることがあります。たとえば、「春子のデバイス」が「ゲストのデバイス」に変わることがあります。
- エンドポイントとルームの関連付けを解除するには、ユニットIDをデフォルトのユニットのワイルドカード(
"~caller.defaultUnitId"
)に設定します。 - 設定の適用は、デバイスをユニットに関連付けている場合にのみ行ってください。ユニットの関連付けを更新すると、それまでのデバイスの設定はすべて消去されます。
- エンドポイントとユニットの関連付けを変更すると、
endpointId
が変更されることがあります。応答には新しいendpointId
が含まれます。 - エンドポイントがユニットに関連付けられているときは、セットアップモードが無効になります。セットアップモードが有効になるのは、エンドポイントが呼び出し元のデフォルトのユニットに関連付けられているとき、またはどのユニットにも関連付けられていないときです。
エンドポイントが再起動されたことを確認するには、エンドポイントをユニット別に取得する
操作を使用して、エンドポイントの接続ステータスをポーリングします。ポーリングの間隔は2分以上にすることをお勧めします。たとえば、GET /v2/endpoints?associatedUnits.id=amzn1.alexa.unit.did.unitFour&connections.macAddress=mac.address.1&features[name:connectivity].properties[name:reachability].value.value=OK
の操作を使用して、接続ステータスを取得します。このAPIからendpointId
が返されれば、エンドポイントは再起動され、正常にネットワークに再接続されています。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
関連付けを更新するには、/v2/endpoints
リソースに対してPUT
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
PUT /v2/endpoints/{endpointId}/associatedUnits
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
リクエストするエンドポイントのID。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
以下は、指定されたエンドポイントとユニットの関連付けを更新するリクエストの例です。
以下は、エンドポイントとユニットの関連付けを解除するリクエストの例です。
リクエスト本文のプロパティ
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
なし |
エンドポイントに関連付けられているユニットのリスト。現時点では、エンドポイントを関連付けることができるユニットは1つです。 |
文字列の配列 |
◯ |
|
ユニットID。 |
文字列 |
◯ |
応答
正常に完了すると、HTTP 200 OK
と共に、エンドポイントIDと関連付けられているユニットが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
以下の応答は、エンドポイントに関連付けられた新しいユニットを示しています。
{
"endpoint": {
"id": "amzn1.alexa.endpoint.1",
"associatedUnits": [{
"id": "amzn1.alexa.unit.did.unitFour"
}]
}
}
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
エンドポイントの関連付けを表します。 |
オブジェクト |
|
エンドポイントのID。 注: エンドポイントとユニットの関連付けを変更すると、エンドポイントIDが変更されることがあります。
|
文字列 |
|
エンドポイントに関連付けられているユニットのリスト。現時点では、エンドポイントに関連付けることができるユニットは一度に1つだけです。 |
文字列の配列 |
|
ユニットID。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
更新されたユニットの関連付けが応答本文に含まれます。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
フレンドリー名を更新する
指定されたエンドポイントのフレンドリー名を変更します。Alexaは、GUIとVUIのすべてのエクスペリエンスでフレンドリー名を使用します。ユーザーは、エンドポイントを制御するときにフレンドリー名を使用できます。たとえば、「アレクサ、キッチンの照明をつけて」のように言うことができます。 エンドポイントIDを取得するには、エンドポイントを所有者別に取得する、エンドポイントをシリアル番号別に取得する、エンドポイントをユニット別に取得するのいずれかを使用します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
フレンドリー名を更新するには、/v2/endpoints
リソースに対してPOST
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
POST /v2/endpoints/{endpointId}/friendlyName
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
リクエストの形式
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
リクエストするエンドポイントのID。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
{
"type": "PLAIN",
"value": {
"text": "玄関のインターホン"
}
}
リクエスト本文のプロパティ
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
|
値フィールドの形式。現時点でサポートされる形式は、プレーンテキストのみです。 |
文字列 |
◯ |
|
名前を表します。 |
オブジェクト |
◯ |
|
プレーンテキストで指定されたフレンドリー名。名前には、1文字以上の数字または文字が含まれている必要があります。 |
文字列 |
◯ |
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
フレンドリー名が正常に更新されました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントの登録を解除する
Amazonビジネスアカウントから、指定されたエンドポイントの登録を解除します。エンドポイントIDを取得するには、エンドポイントを所有者別に取得する、エンドポイントをシリアル番号別に取得する、エンドポイントをユニット別に取得するのいずれかを使用します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
エンドポイントの登録を解除するには、/v2/endpoints
リソースに対してPOST
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
POST /v2/endpoints/{endpointId}/deregister
Host: api.amazonalexa.com
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
リクエストするエンドポイントのID。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
エンドポイントの登録が正常に解除されました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントの情報を削除する
指定されたエンドポイントの情報を削除するようAlexaにリクエストします。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエスト
エンドポイントを削除するには、/v2/endpoints
リソースに対してPOST
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
POST /v2/endpoints/{endpointId}/forget
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
リクエストするエンドポイントのID。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
エンドポイントのタイマーを削除する
指定されたエンドポイントのすべてのタイマーを削除します。エンドポイントIDを取得するには、エンドポイントを所有者別に取得する、エンドポイントをシリアル番号別に取得する、エンドポイントをユニット別に取得するのいずれかを使用します。ユニット内のすべてのエンドポイントからタイマーを削除する場合は、ユニットのすべてのタイマーを削除するを参照してください。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
カナダ、ドイツ、スペイン、フランス、イタリア、米国、英国 |
カナダ、ドイツ、スペイン、フランス、イタリア、米国、英国 |
なし |
リクエスト
タイマーを削除するには、/v1/alerts/timers
リソースに対してDELETE
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
DELETE /v1/alerts/timers?endpoint={endpointId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
リクエストするエンドポイントのID。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークン。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 204 No Content
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
指定されたエンドポイントのタイマーが正常に削除されました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。 |
|
リクエストされたリソースが見つかりません。 |
|
許可されたレート制限(単位時間あたりのリクエスト数として指定された値)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
オブジェクトの定義
エンドポイントAPIでは、以下のオブジェクトが定義されています。
Connectionオブジェクト
Connection
オブジェクトは、エンドポイントがインターネットやスマートホームハブに接続するために使用する方法を定義します。
プロパティ | 説明 | 型 |
---|---|---|
|
接続の種類。 |
文字列 |
|
ネットワークインターフェースコントローラー(NIC)の一意の識別子。 |
文字列 |
DisplayCategoriesオブジェクト
DisplayCategories
オブジェクトは、エンドポイントが表示されるAlexaアプリの見出しを、正しいアイコンで定義します。
プロパティ | 説明 | 型 |
---|---|---|
|
エンドポイントのプライマリー表示カテゴリー。 |
オブジェクト |
|
カテゴリーの名前。 |
文字列 |
|
カテゴリーのソース。ユーザーによって明示的に設定されたか、元のエンドポイントレポートの中で報告されたかのいずれかです。 |
文字列の配列 |
|
エンドポイントのすべてのカテゴリー。 |
オブジェクトのリスト |
|
カテゴリーの名前。 |
文字列 |
|
カテゴリーのソース。ユーザーによって明示的に設定されたか、元のエンドポイントレポートの中で報告されたかのいずれかです。 |
文字列の配列 |
Errorオブジェクト
Error
オブジェクトは、発生したエラーを表します。
プロパティ | 説明 | 型 |
---|---|---|
|
発生したエラーのタイプ。 |
文字列 |
|
読み取り可能なエラーメッセージ。 |
文字列 |
Featureオブジェクト
Feature
オブジェクトは、スピーカーの音量など、エンドポイントに関連付けられている機能を定義します。
プロパティ | 説明 | 型 |
---|---|---|
|
機能の名前。 |
文字列 |
|
この機能の詳細な結果を取得するためのURL。例: |
文字列 |
|
(オプション)リクエストされた機能のプロパティのリスト。クエリパラメーターに |
オブジェクトの配列 |
|
プロパティの名前。 |
文字列 |
|
呼び出し元がプロパティ値を読み取ることができるかどうかを示します。 |
文字列 |
|
プロパティの値( |
各種 |
|
エンドポイントが状態変更を検出した時刻。 |
文字列 |
|
(オプション)発生したエラーについての説明。 |
Errorオブジェクト |
NameValueオブジェクト
NameValue
オブジェクトは、オブジェクトの名前のコンテナーです。
以下の表は、オブジェクトのプロパティの定義です。
プロパティ | 説明 | 型 |
---|---|---|
|
値フィールドの形式。現時点でサポートされる形式は、プレーンテキストのみです。 |
文字列 |
|
名前。 |
オブジェクト |
|
プレーンテキストで指定された名前。 |
文字列 |
Operationオブジェクト
Operation
オブジェクトは、指定されたエンドポイントや機能で使用可能な更新操作を表します。
プロパティ | 説明 | 型 |
---|---|---|
|
更新操作の名前。 |
文字列 |
|
更新操作で |
文字列 |
関連トピック
最終更新日: 2024 年 06 月 19 日