検出セッションAPI

検出セッションAPI

検出セッションAPIを使用すると、ユニットに関連付けられているエンドポイントを探すことができます。検出セッションを作成すると、Alexaは、スマートホームスキルを介して接続されたエンドポイントなど、新しいエンドポイントや更新されたエンドポイントを探すよう指示されます。

APIエンドポイント

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを以下のいずれかに設定してください。

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。

操作

検出セッションAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

検出セッションを作成する

POST /v1/discoverySessions?unit={unitId}

検出セッションステータスを取得する

GET /v1/discoverySessions/{id}

検出セッションを作成する

POST /v1/discoverySessions?unit={unitId}を呼び出すと、検出セッションを作成できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

POST /v1/discoverySessions?unit={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
unit ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文の例

{
   "endpointReporter": {
      "type": "SKILL",
      "value": {
         "skillId": "amzn1.ask.skill.skillId",
         "skillStage": "LIVE"
      }
   }
}

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

フィールド 説明 型 必須
endpointReporter Alexaに呼び出されるとエンドポイントを報告するエンティティ。 オブジェクト ◯
endpointReporter.type エンドポイントを報告するエンティティのタイプ。現在、サポートされているのはSKILLのみです。 列挙 ◯
endpointReporter.value エンドポイントを報告するエンティティを記述するアトリビュート値。このエンティティについて検出セッションを作成します。 オブジェクト ◯
skillId スキルID。"amzn1.alexa.skill.{id}"形式で指定します。 文字列 ◯
skillStage スキルステージ。 DEVELOPMENTかLIVEのいずれかです。デフォルト値はLIVEです。 文字列 ✕

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v1/discoverySessions/amzn1.alexa.discoverySession.{id}"
フィールド 説明 型 必須
X-Amzn-RequestId リクエストの一意のID。例：1K82TJNQTXSJFP8NGJP0。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 文字列 ◯
Location 検出セッションの場所。このURIを使用して検出セッションを取得します。
Locationヘッダーに指定されたURIは、応答の受信後、1時間有効です。		 文字列 ◯
id LocationヘッダーのURIに含まれる検出セッションID。 文字列 ◯

応答本文の例

{
   "id": "amzn1.alexa.discoverySession.c777715e-0cf2-433e-89de-4f0f0892150"
}

応答本文のパラメーター

フィールド 説明 型 必須
id 新しい検出セッションのセッションID。 文字列 ◯

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド 説明 型 必須
type エラーのエラータイプ。 文字列 ✕
message エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 文字列 ✕

HTTP応答コード

ステータスコード 名前 説明
201 Created 検出セッションが正常に作成されました。
400 Bad Request リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
401 Unauthorized アクセストークンがないか、期限切れか、無効です。
403 Forbidden アクセストークンは有効ですが、必要なLWAスコープの権限をユーザーが持っていません。
404 Not found リクエストされた構成要素がクライアントについて検出されませんでした。
409 Discovery session conflict 検出セッションが既に進行中です。
429 Too many requests リクエストが制限されています。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。
500 Internal Server Error 内部サービスエラーのためリクエストを処理できませんでした。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は500以外の応答を受信するまで256秒ごとに再試行します。
503 Service Unavailable サービスが一時的に使用できません。

検出セッションステータスを取得する

GET /v1/discoverySessions/{id}を呼び出すと、検出セッションのステータスを確認できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/discoverySessions/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
id 検出セッションID。"amzn1.alexa.discoverySession.{id}"形式で指定します。 文字列 ◯

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 型 必須
X-Amzn-RequestId リクエストの一意のID。例：1K82TJNQTXSJFP8NGJP0。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 文字列 ◯

応答本文の例

{
   "status": {
        "value": "IN_PROGRESS"
    }
}

応答本文のパラメーター

フィールド 説明 型 必須
status 検出セッションのステータス。 オブジェクト ◯
status.value SUCCESS - 検出操作が正常に終了しました。
IN_PROGRESS - 検出操作が進行中です。
FAILURE - 検出操作に失敗しました。次のような理由が考えられます。
- スキルのLambdaが検出ディレクティブに対してエラーを返した
- 内部サーバーエラー		 列挙 ◯

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド 説明 型 必須
type エラーのエラータイプ。 文字列 ✕
message エラーのエラーメッセージ。エラーメッセージの表示はデバッグやログ記録のみを目的としたものであり、ユーザーには表示しないようにする必要があることにご注意ください。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 文字列 ✕

HTTP応答コード

ステータスコード 名前 説明
200 Created 検出セッションステータスが正常に照会されました。
400 Bad Request リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
401 Unauthorized アクセストークンがないか、期限切れか、無効です。
403 Forbidden アクセストークンは有効ですが、必要なLWAスコープの権限をユーザーが持っていません。
404 No such discovery session 検出セッションIDが存在しないか、URIが期限切れです。URIは、検出セッションの作成後1時間で有効期限が切れます。
429 Too many requests リクエストが制限されています。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。
500 Internal Server Error 内部サービスエラーのためリクエストを処理できませんでした。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は500以外の応答を受信するまで256秒ごとに再試行します。
503 Service Unavailable サービスが一時的に使用できません。

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

最終更新日: 2024 年 03 月 21 日