検出セッションAPI

Note: Sign in to the developer console to build or publish your skill.

検出セッションAPI

注：このAPIは、登録済みのAlexa Smart Properties in Hospitalityパートナーのみ使用できます。Alexa Smart Properties for Hospitality 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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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値は、リクエストのHost値と同じになります。

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}を呼び出します。