エンドポイントAPI

エンドポイントAPI

エンドポイントREST APIを使用して、Amazon EchoデバイスやAlexaコネクテッド照明など、Alexa Smart Properties（ASP）のAlexaコネクテッドデバイスを管理できます。エンドポイントは、ASPのゲストや居住者が操作できるAlexaコネクテッドデバイスを表します。このAPIを使用すると、Amazonビジネスアカウントで所有されているデバイスの列挙や、エンドポイントと特定のルームの関連付けを行うことができます。

エンドポイントAPIは、エンドポイントの管理を行う以下のAPIと共に使用できます。

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

エンドポイントを所有者別に取得する

GET /v2/endpoints?owner={owner}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}

エンドポイントをユニット別に取得する

GET /v2/endpoints?associatedUnits.id={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}

エンドポイントをID別に取得する

GET /v2/endpoints/{endpointId}?expand={expand}

エンドポイントをシリアル番号別に取得する

GET /v2/endpoints?serialNumber.value.text={serialNumber}&expand={expand}

エンドポイントを照会する（詳細検索）

POST /v2/endpointQuery

関連付けられているユニットを更新する

PUT /v2/endpoints/{endpointId}/associatedUnits

フレンドリー名を更新する

POST /v2/endpoints/{endpointId}/friendlyName

エンドポイントの登録を解除する

POST /v2/endpoints/{endpointId}/deregister

エンドポイントの情報を削除する

POST /v2/endpoints/{endpointId}/forget

エンドポイントのタイマーを削除する

DELETE /v1/alerts/timers?endpoint={endpointId}

エンドポイントを所有者別に取得する

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

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

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

owner

クエリ

エンドポイントをフィルタリングして、所有者に関連付けられているエンドポイントを取得します。~callerはアクセストークンで識別されるユーザーを表します。
有効な値は~callerです。

文字列

◯

expand

クエリ

各エンドポイントに関する詳細情報を取得します。
すべてのエンドポイントアトリビュートを取得する場合は、allを指定します。機能に関する詳細情報を取得する場合は、機能名を指定します。このフィルターは複数指定できます。例：expand=feature:brightness&expand=feature:connectivity。
有効な値はall、feature:brightness、feature:color、feature:colorTemperature、feature:connectivity、feature:power、feature:speaker、feature:temperatureSensor、feature:thermostatです。

文字列

✕

maxResults

クエリ

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

整数

✕

nextToken

クエリ

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

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

リクエスト本文のパラメーター

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

応答

正常に完了すると、HTTP 200 OKと共に、エンドポイントのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

以下は、owner=~callerのクエリパラメーターを含むリクエストへの応答の例です。

以下は、owner=~callerとexpand=feature:speaker&expand=feature:connectivityのクエリパラメーターを含むリクエストへの応答の例です。

以下は、owner=~callerとexpand=allのクエリパラメーターを含むリクエストへの応答の例です。

応答本文のプロパティ

プロパティ 説明 型

results

ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。
リストの順序は、リクエストで指定されたクエリパラメーターによって異なる場合があります。

オブジェクトの配列

results[].id

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

文字列

results[].friendlyName

（オプション）エンドポイントを識別するためにユーザーが使用する名前。

NameValueオブジェクト

results[].manufacturer

（オプション）エンドポイントの製造元。

NameValueオブジェクト

results[].model

（オプション）エンドポイントのモデル。

NameValueオブジェクト

results[].serialNumber

（オプション）エンドポイントのシリアル番号。

NameValueオブジェクト

results[].softwareVersion

（オプション）エンドポイントのソフトウェアバージョン。

NameValueオブジェクト

results[].connections

（オプション）エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。

Connectionオブジェクトの配列

results[].creationTime

（オプション）エンドポイントリソースが作成された日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].features

（オプション）エンドポイントで定義されている機能のリスト。

Featureオブジェクトの配列

results[].associatedUnits

（オプション）エンドポイントに関連付けられているユニットのリスト。

オブジェクトの配列

results[].associatedUnits[].id

ユニットID。amzn1.alexa.unit.did.{id}という形式で表します。

文字列

results[].operations

（オプション）この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

results[].displayCategories

（オプション）エンドポイントが表示されるAlexaアプリの見出し。

文字列

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

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

文字列

HTTPステータスコード

ステータス 説明

200 OK

エンドポイントと関連情報のリストが応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントをユニット別に取得する

指定されたユニット（ルーム）に関連付けられているエンドポイントのリストを取得します。エンドポイントを照会する（詳細検索）操作を使用してエンドポイントを取得することもできます。

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

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

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

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

unitId

クエリ

エンドポイントをフィルタリングして、特定のユニットに関連付けられているエンドポイントを取得します。
amzn1.alexa.unit.did.{id}という形式で表します。
Amazonビジネスアカウントに割り当てられているエンドポイントの場合は、値を~caller.defaultUnitIdに設定します。

文字列

◯

expand

クエリ

各エンドポイントに関する詳細情報を取得します。
すべてのエンドポイントアトリビュートを取得する場合は、allを指定します。機能に関する詳細情報を取得する場合は、機能名を指定します。このフィルターは複数指定できます。例：expand=feature:brightness&expand=feature:connectivity。
有効な値はall、feature:brightness、feature:color、feature:colorTemperature、feature:connectivity、feature:power、feature:speaker、feature:temperatureSensor、feature:thermostatです。

文字列

✕

maxResults

クエリ

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

整数

✕

nextToken

クエリ

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

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたユニットに関連付けられているエンドポイントのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

以下は、expand=allのクエリパラメーターを含むリクエストへの応答の例です。

応答本文のプロパティ

プロパティ 説明 型

results

ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。
リストの順序は、リクエストで指定されたクエリパラメーターによって異なる場合があります。

オブジェクトの配列

results[].id

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

文字列

results[].friendlyName

（オプション）エンドポイントを識別するためにユーザーが使用する名前。

NameValueオブジェクト

results[].manufacturer

（オプション）エンドポイントの製造元。

NameValueオブジェクト

results[].model

（オプション）エンドポイントのモデル。

NameValueオブジェクト

results[].serialNumber

（オプション）エンドポイントのシリアル番号。

NameValueオブジェクト

results[].softwareVersion

（オプション）エンドポイントのソフトウェアバージョン。

NameValueオブジェクト

results[].connections

（オプション）エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。

Connectionオブジェクトの配列

results[].creationTime

（オプション）エンドポイントリソースが作成された日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].features

（オプション）エンドポイントで定義されている機能のリスト。

Featureオブジェクトの配列

results[].associatedUnits

（オプション）エンドポイントに関連付けられているユニットのリスト。

オブジェクトの配列

results[].associatedUnits[].id

ユニットID。amzn1.alexa.unit.did.{id}という形式で表します。

文字列

results[].operations

（オプション）この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

results[].displayCategories

（オプション）エンドポイントが表示されるAlexaアプリの見出し。

文字列

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

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

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたユニットのエンドポイントのリストが応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントを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

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

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

endpoint

パス

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

文字列

◯

expand

クエリ

エンドポイントに関する詳細情報を取得します。
エンドポイントのすべてのアトリビュートを取得する場合は、allを指定します。機能に関する詳細情報を取得する場合は、機能名を指定します。このフィルターは複数指定できます。例：expand=feature:brightness&expand=feature:connectivity。
有効な値はall、feature:brightness、feature:color、feature:colorTemperature、feature:connectivity、feature:power、feature:speaker、feature:temperatureSensor、feature:thermostatです。

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたエンドポイントに関する情報が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

以下は、指定されたエンドポイントのスピーカー機能と接続機能を取得するexpand=feature:speaker&expand=feature:connectivityのクエリパラメーターを含むリクエストへの応答の例です。

以下は、指定されたエンドポイントのすべてのアトリビュートを取得するexpand=allのクエリパラメーターを含むリクエストへの応答の例です。

応答本文のプロパティ

プロパティ 説明 型

id

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

文字列

friendlyName

（オプション）エンドポイントを識別するためにユーザーが使用する名前。

NameValueオブジェクト

manufacturer

（オプション）エンドポイントの製造元。

NameValueオブジェクト

model

（オプション）エンドポイントのモデル。

NameValueオブジェクト

serialNumber

（オプション）エンドポイントのシリアル番号。

NameValueオブジェクト

softwareVersion

（オプション）エンドポイントのソフトウェアバージョン。

NameValueオブジェクト

connections

（オプション）エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。

Connectionオブジェクトの配列

creationTime

（オプション）エンドポイントリソースが作成された日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

features

（オプション）エンドポイントで定義されている機能のリスト。

Featureオブジェクトの配列

associatedUnits

（オプション）エンドポイントに関連付けられているユニットのリスト。

オブジェクトの配列

associatedUnits[].id

ユニットID。amzn1.alexa.unit.did.{id}という形式で表します。

文字列

operations

（オプション）この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

displayCategories

（オプション）エンドポイントが表示されるAlexaアプリの見出し。

文字列

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

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

文字列

HTTPステータスコード

ステータス 説明

200 OK

エンドポイントの情報が応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントをシリアル番号別に取得する

指定されたデバイスシリアル番号に関連付けられているエンドポイントを取得します。呼び出し元には、エンドポイントへのアクセス権限が必要です。通常、エンドポイントとシリアル番号は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

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

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

serialNumber

クエリ

エンドポイントをフィルタリングして、シリアル番号に関連付けられているエンドポイントを取得します。

文字列

◯

expand

クエリ

エンドポイントに関する詳細情報を取得します。
すべてのエンドポイントアトリビュートを取得する場合は、allを指定します。機能に関する詳細情報を取得する場合は、機能名を指定します。このフィルターは複数指定できます。例：expand=feature:brightness&expand=feature:connectivity。
有効な値はall、feature:brightness、feature:color、feature:colorTemperature、feature:connectivity、feature:power、feature:speaker、feature:temperatureSensor、feature:thermostatです。

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたシリアル番号のエンドポイントが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

以下は、指定されたシリアル番号に関連付けられているエンドポイントを取得するリクエストへの応答の例です。

応答本文のプロパティ

プロパティ 説明 型

results

ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。
リストの順序は、リクエストで指定されたクエリパラメーターによって異なる場合があります。

オブジェクトの配列

results[].id

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

文字列

results[].friendlyName

（オプション）エンドポイントを識別するためにユーザーが使用する名前。

NameValueオブジェクト

results[].manufacturer

（オプション）エンドポイントの製造元。

NameValueオブジェクト

results[].model

（オプション）エンドポイントのモデル。

NameValueオブジェクト

results[].serialNumber

（オプション）エンドポイントのシリアル番号。

NameValueオブジェクト

results[].softwareVersion

（オプション）エンドポイントのソフトウェアバージョン。

NameValueオブジェクト

results[].connections

（オプション）エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。

Connectionオブジェクトの配列

results[].creationTime

（オプション）エンドポイントリソースが作成された日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].features

（オプション）エンドポイントで定義されている機能のリスト。

Featureオブジェクトの配列

results[].associatedUnits

（オプション）エンドポイントに関連付けられているユニットのリスト。

オブジェクトの配列

results[].associatedUnits[].id

ユニットID。amzn1.alexa.unit.did.{id}という形式で表します。

文字列

results[].operations

（オプション）この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

results[].displayCategories

（オプション）エンドポイントが表示されるAlexaアプリの見出し。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたシリアル番号のエンドポイントが応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントを照会する（詳細検索）

指定した条件に一致するエンドポイントのリストを取得します。この操作では、ユニット、製造元、モデルによる照会がサポートされます。

クエリは複数の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}

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

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

access token

ヘッダー

LWAトークン。

文字列

◯

リクエスト本文の例

以下は、2つのユニットのエンドポイントを照会するリクエストの例です。

以下は、デバイスの製造元でフィルタリングされた、2つのユニットのエンドポイントを照会するリクエストです。

以下は、デバイスの製造元とモデルでフィルタリングされた、2つのユニットのエンドポイントを照会するリクエストです。

リクエスト本文のパラメーター

パラメーター 説明 型 必須

query

クエリのフィルタリング条件。フィールドは、andまたはorのリストになります。別のandまたはorフィルタリング条件のリストを入れ子として含めることもできます。
少なくとも1つのフィルターを含めてください。

オブジェクト

◯

query.and[]

and論理演算子を使用して2つ以上のパラメーターを論理的に結合するクエリ。

オブジェクトの配列

✕

query.and[].match

クエリフィールド。このクエリフィールドの値は、返されるエンドポイントの対応する値と完全に一致する必要があります。
有効な値は次のとおりです。
  • associatedUnits.id： フィルタリングの条件となるユニットID。例：amzn1.alexa.unit.did.unitOne、~caller.defaultUnitId。
  • manufacturer.value.text： フィルタリングの条件となるAlexa搭載デバイスの製造元。例： Amazon。
  • model.value.text： フィルタリングの条件となるAlexa搭載デバイスのモデル。例： Echo Dot (3rd generation)。

オブジェクト

✕

query.or[]

or論理演算子を使用して2つ以上のパラメーターを論理的に結合するクエリ。

オブジェクトの配列

✕

query.or[].match

クエリフィールド。このクエリフィールドの値は、返されるエンドポイントの対応する値と完全に一致する必要があります。
有効な値は次のとおりです。
  • associatedUnits.id： フィルタリングの条件となるユニットID。
  • manufacturer.value.text： フィルタリングの条件となるAlexa搭載デバイスの製造元。
  • model.value.text： フィルタリングの条件となるAlexa搭載デバイスのモデル。

オブジェクト

✕

expand

取得するエンドポイントアトリビュートのリスト。すべてのエンドポイントアトリビュートを取得する場合は、allを指定します。
有効な値はall、feature:brightness、feature:color、feature:colorTemperature、feature:connectivity、feature:power、feature:speaker、feature:temperatureSensor、feature:thermostatです。

文字列の配列

✕

paginationContext

結果の特定のページを返すかどうかを示します。

オブジェクト

✕

paginationContext.nextToken

ページ分割された結果から特定のページを取得するためのトークン。このトークンがない場合、応答には結果の先頭ページが含められます。

文字列

✕

paginationContext.maxResults

応答本文で返される結果の最大数。
有効な値は 1～10です。

数値

✕

応答

正常に完了すると、HTTP 200 OKと共に、フィルター条件に一致するエンドポイントのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

以下は、expand配列でfeature:connectivityを指定してエンドポイントをフィルタリングするクエリへの応答の例です。

以下は、associatedUnits.idのエンドポイントを取得する応答の例です。

応答本文のパラメーター

パラメーター 説明 型

results

ユーザーのアカウントに関連付けられているコネクテッドエンドポイントのリスト。
リストの順序は、リクエストで指定されたクエリパラメーターによって異なる場合があります。

オブジェクトの配列

results[].id

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

文字列

results[].friendlyName

（オプション）エンドポイントを識別するためにユーザーが使用する名前。

NameValueオブジェクト

results[].manufacturer

（オプション）エンドポイントの製造元。

NameValueオブジェクト

results[].model

（オプション）エンドポイントのモデル。

NameValueオブジェクト

results[].serialNumber

（オプション）エンドポイントのシリアル番号。

NameValueオブジェクト

results[].softwareVersion

（オプション）エンドポイントのソフトウェアバージョン。

NameValueオブジェクト

results[].connections

（オプション）エンドポイントをインターネットやスマートホームハブに接続するための方法のリスト。

Connectionオブジェクトの配列

results[].creationTime

（オプション）エンドポイントリソースが作成された日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].features

（オプション）エンドポイントで定義されている機能のリスト。

Featureオブジェクトの配列

results[].associatedUnits

（オプション）エンドポイントに関連付けられているユニットのリスト。

オブジェクトの配列

results[].associatedUnits[].id

ユニットID。amzn1.alexa.unit.did.{id}という形式で表します。

文字列

results[].operations

（オプション）この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

results[].displayCategories

（オプション）エンドポイントが表示されるAlexaアプリの見出し。

文字列

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

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

文字列

HTTPステータスコード

ステータス 説明

200 OK

フィルタリングされたエンドポイントの情報が応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

関連付けられているユニットを更新する

エンドポイントの関連付けられているユニット（ルーム）のリストを更新します。この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}

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

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

endpoint

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

以下は、指定されたエンドポイントとユニットの関連付けを更新するリクエストの例です。

以下は、エンドポイントとユニットの関連付けを解除するリクエストの例です。

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

プロパティ 説明 型 必須

なし

エンドポイントに関連付けられているユニットのリスト。現時点では、エンドポイントを関連付けることができるユニットは1つです。

文字列の配列

◯

id

ユニットID。amzn1.alexa.unit.did.{id}という形式で表します。
エンドポイントをユニットから削除してAmazonビジネスアカウントに戻すには、値を~caller.defaultUnitIdに設定します。

文字列

◯

応答

正常に完了すると、HTTP 200 OKと共に、エンドポイントIDと関連付けられているユニットが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

以下の応答は、エンドポイントに関連付けられた新しいユニットを示しています。

{
    "endpoint": {
        "id": "amzn1.alexa.endpoint.1",
        "associatedUnits": [{
            "id": "amzn1.alexa.unit.did.unitFour"
        }]
    }
}

応答本文のプロパティ

プロパティ 説明 型

endpoint

エンドポイントの関連付けを表します。

オブジェクト

endpoint.id

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

文字列

endpoint.associatedUnits

エンドポイントに関連付けられているユニットのリスト。現時点では、エンドポイントに関連付けることができるユニットは一度に1つだけです。

文字列の配列

endpoint.associatedUnits[].id

ユニットID。amzn1.alexa.unit.did.{id}または~caller.defaultUnitIdの形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

更新されたユニットの関連付けが応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

フレンドリー名を更新する

指定されたエンドポイントのフレンドリー名を変更します。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}

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

リクエストの形式

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

endpoint

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
    "type": "PLAIN",
    "value": {
        "text": "玄関のインターホン"
    }
}

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

プロパティ 説明 型 必須

type

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

文字列

◯

value

名前を表します。

オブジェクト

◯

value.text

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

文字列

◯

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

200 OK

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

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントの登録を解除する

Amazonビジネスアカウントから、指定されたエンドポイントの登録を解除します。エンドポイントIDを取得するには、エンドポイントを所有者別に取得する、エンドポイントをシリアル番号別に取得する、エンドポイントをユニット別に取得するのいずれかを使用します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

エンドポイントの登録を解除するには、/v2/endpointsリソースに対してPOSTリクエストを実行します。

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

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

POST /v2/endpoints/{endpointId}/deregister
Host: api.amazonalexa.com
Authorization: Bearer {access token}

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

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

endpoint

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

200 OK

エンドポイントの登録が正常に解除されました。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントの情報を削除する

指定されたエンドポイントの情報を削除するよう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}

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

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

endpoint

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

200 OK

リクエストが成功しました。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンドポイントのタイマーを削除する

指定されたエンドポイントのすべてのタイマーを削除します。エンドポイント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}

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

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

endpoint

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

指定されたエンドポイントのタイマーが正常に削除されました。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

オブジェクトの定義

エンドポイントAPIでは、以下のオブジェクトが定義されています。

Connectionオブジェクト

Connectionオブジェクトは、エンドポイントがインターネットやスマートホームハブに接続するために使用する方法を定義します。

プロパティ 説明 型

type

接続の種類。
有効な値は TCP_IP、ZIGBEE、UNKNOWNです。

文字列

macAddress

ネットワークインターフェースコントローラー（NIC）の一意の識別子。
有効な値は 1～32文字です。

文字列

DisplayCategoriesオブジェクト

DisplayCategoriesオブジェクトは、エンドポイントが表示されるAlexaアプリの見出しを、正しいアイコンで定義します。

プロパティ 説明 型

primary

エンドポイントのプライマリー表示カテゴリー。

オブジェクト

primary.value

カテゴリーの名前。

文字列

primary.sources

カテゴリーのソース。ユーザーによって明示的に設定されたか、元のエンドポイントレポートの中で報告されたかのいずれかです。
有効な値は CUSTOMER、ENDPOINT_REPORTERです。

文字列の配列

all

エンドポイントのすべてのカテゴリー。

オブジェクトのリスト

all[].value

カテゴリーの名前。

文字列

all[].sources

カテゴリーのソース。ユーザーによって明示的に設定されたか、元のエンドポイントレポートの中で報告されたかのいずれかです。
有効な値は CUSTOMER、ENDPOINT_REPORTERです。

文字列の配列

Errorオブジェクト

Errorオブジェクトは、発生したエラーを表します。

プロパティ 説明 型

type

発生したエラーのタイプ。
有効な値は ENDPOINT_UNREACHABLE、INTERNAL_ERRORです。

文字列

message

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

文字列

Featureオブジェクト

Featureオブジェクトは、スピーカーの音量など、エンドポイントに関連付けられている機能を定義します。

プロパティ 説明 型

name

機能の名前。
例：speaker、volume。

文字列

path

この機能の詳細な結果を取得するためのURL。例：/v2/endpoints/{endpointID}/features/speaker。
詳細については、エンドポイント機能REST APIリファレンスを参照してください。

文字列

properties

（オプション）リクエストされた機能のプロパティのリスト。クエリパラメーターにexpand=feature:<機能名>が指定されている場合に含まれます。

オブジェクトの配列

properties[].name

プロパティの名前。

文字列

properties[].type

呼び出し元がプロパティ値を読み取ることができるかどうかを示します。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

プロパティの値（typeがRETRIEVABLEの場合）。
値の定義は機能によって異なります。詳細については、エンドポイント機能REST APIリファレンスを参照してください。

各種

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

NameValueオブジェクト

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

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

プロパティ 説明 型

type

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

文字列

value

名前。

オブジェクト

value.text

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

文字列

Operationオブジェクト

Operationオブジェクトは、指定されたエンドポイントや機能で使用可能な更新操作を表します。

プロパティ 説明 型

name

更新操作の名前。

文字列

path

更新操作でnameプロパティの設定に使用できる完全なHTTPパス。

文字列

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

最終更新日: 2024 年 06 月 19 日