検出セッションAPI


検出セッションAPI

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

APIエンドポイント

検出セッションAPIのエンドポイントは、https://api.amazonalexa.comです。

認証

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

操作

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

操作 HTTPメソッドとURI

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

POST /v1/discoverySessions?unit={unitId}

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

GET /v1/discoverySessions/{id}

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

検出セッションを作成するには、POST /v1/discoverySessions?unit={unitId}を呼び出します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国、カナダ

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

米国

リクエストの形式

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

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

フィールド 説明 必須
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 検出セッションIDです。LocationヘッダーにURIの一部として含まれます。 文字列

応答本文の例

{
   "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 Residential Senior Living Core

米国

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

米国、カナダ

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

米国

リクエストの形式

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

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

フィールド 説明 必須
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 サービスが一時的に使用できません。


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

最終更新日: 2023 年 03 月 16 日