検出セッション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}
を呼び出します。
この操作は以下の国で使用できます。
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
値は、リクエストの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}
を呼び出します。
この操作は以下の国で使用できます。
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
値は、リクエストのHost
値と同じになります。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 日