検出セッションREST APIリファレンス

検出セッションREST APIリファレンス

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

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

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

POST /v1/discoverySessions?unit={unitId}

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

GET /v1/discoverySessions/{id}

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

検出セッションを作成して、ユニットに割り当てられているエンドポイントを探します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

検出セッションを作成するには、/v1/discoverySessionsリソースに対してPOSTリクエストを実行します。

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

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

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

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

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

unitId

クエリ

ユニットの一意のID。
unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

プロパティ 説明 型 必須

endpointReporter

Alexaにエンドポイント情報を報告するエンティティ。

オブジェクト

◯

endpointReporter.type

レポーターのタイプ。
有効な値は SKILLです。

文字列

◯

endpointReporter.value

新しい検出セッションのエンドポイントレポーターを表します。

オブジェクト

◯

endpointReporter.value.id

スキルID。
amzn1.alexa.skill.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

endpointReporter.value.skillStage

（任意）スキルのステージ。
有効な値はdevelopment、liveです。
デフォルト値はliveです。

文字列

✕

応答

正常に完了すると、HTTP 201 Createdと共に、検出セッションのIDが返されます。応答ヘッダーには、セッションのURLの場所に設定されたLocationパラメーター（/v1/discoverySessions/amzn1.alexa.discoverySession.1など）が含まれます。このURLを使用してセッションのステータスを確認できます。URLの有効期限は1時間です。

エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、応答の例です。

{
   "id": "amzn1.alexa.discoverySession.1"
}

応答本文のプロパティ

プロパティ 説明 型

id

検出セッションを識別します。
amzn1.alexa.discoverySession.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

201 Created

検出セッションが正常に作成されました。

400 Bad Request

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

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

指定された検出セッションのステータスを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ステータスを取得するには、/v1/discoverySessions/リソースに対してGETリクエストを実行します。

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

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

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

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

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

id

クエリ

セッションの一意のID。
amzn1.alexa.discoverySession.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、セッションのステータスが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

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

応答本文のプロパティ

プロパティ 説明 型

status

検出セッションの現在のステータス。

オブジェクト

status.value

ステータスの値。
失敗の場合は、スキルがDiscoveryディレクティブにAlexa.ErrorResponseを返したか、内部サーバーエラーが発生した可能性があります。
有効な値は SUCCESS、IN_PROGRESS、FAILUREです。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定された検出セッションのステータスが応答本文に含まれます。

400 Bad Request

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

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

オブジェクトの定義

検出セッションAPIでは、以下のオブジェクト定義が定義されています。

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
プロパティ 説明 型

type

発生したエラーのタイプ。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

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

文字列

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

最終更新日: 2024 年 11 月 18 日