Alexaスキル有効化API

Alexaスキル有効化API

Alexaスキル有効化APIを使うと、ユーザーに対してAlexaスキルの有効と無効を切り替えたり、ユーザーのAmazonアカウントを別のサービスのアカウントにリンクしたりすることができます。

Alexaスキル有効化APIに使用するエンドポイントは、ユーザーの所在地によって異なります。エンドポイントは、https://api.amazonalexa.com、https://api.eu.amazonalexa.com、https://api.fe.amazonalexa.comのいずれかです。エンドポイントの確認方法については、ユーザーのエンドポイントを取得するを参照してください。

前提条件

サービスがAlexa Skill有効化APIを呼び出すには、その前にOAuth 2.0を使ってユーザーのAmazonアクセストークンを取得しなければなりません。サービスがユーザーのAmazonアクセストークンを取得するには、以下の処理が必要です。

  1. ユーザーのAmazon認可コードを取得する - Amazon認可コードがあれば、次のステップでAmazonアクセストークンを取得できます。ユースケースによっては、AlexaアプリのURL（アプリ間アカウントリンクの場合）またはLogin with Amazon（LWA）認可サーバーにHTTP GETリクエストを行って、ユーザーのAmazon認可コードを取得します。詳細については、アプリ間アカウントリンクまたはLogin with Amazonに関するドキュメントを参照してください。ユーザーのAmazon認可コードのリクエストでは、alexa::skills:account_linkingスコープへのアクセス権限を必ずリクエストしてください。Amazonアクセストークンはこのスコープへのアクセスが必要になります。Amazon認可コードの有効期限は5分間です。
  2. Amazon認可コードをAmazonアクセストークンと交換する - Alexaスキル有効化APIを使用してスキルを有効にし、アカウントリンクを完了するには、Amazonアクセストークンが必要です。Amazonアクセストークンを取得するには、前のステップで取得したAmazon認可コードを使用してLWA認可サーバーを呼び出します。Amazonアクセストークンの有効期限は1時間です。有効期限経過後にAlexa Skill有効化APIを呼び出すことが予想される場合は、LWAが提供するAmazon更新トークンを保存しておきます。Amazon更新トークンがあれば、Amazonアクセストークンを新たに取得して有効期限を1時間延長することができます。

アカウントリンクとAlexaスキル全般については、アカウントリンクとはを参照してください。

ユーザーのエンドポイントを取得する

Alexa Skill有効化APIを呼び出す際に使用するエンドポイントを取得するには、まず、AlexaエンドポイントAPIにGETリクエストを行います。このAPIは、ユーザーのAmazonアカウントが登録されている場所に基づいてエンドポイントを返します。Alexaスキル有効化APIの操作では、常に返されたこのエンドポイントを使用します。

GETリクエストから複数のエンドポイントが返された場合、Alexaサービスはどれがユーザーの正しいエンドポイントか判断できません。この場合、ユーザーについてAlexa Skill有効化APIを呼び出す際に、返されたすべてのエンドポイントを1つずつ順に呼び出します。正しいエンドポイントのみが呼び出しに成功します。

リクエスト

GET /v1/alexaApiEndpoint HTTP/1.1
Host: <api.amazonalexa.com、api.eu.amazonalexa.com、またはapi.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"

パラメーター

名前 位置 説明 必須 型
Authorization ヘッダー LWAから取得したAmazonアクセストークンです。Amazonアクセストークンは、ユーザーとスキルに固有です。アクセストークンの詳細については、アクセストークンを参照してください。 ◯ 文字列

応答

コード 説明 型
200 Alexaエンドポイントの配列を含む成功応答です。配列に1つのエンドポイントだけが含まれている場合、それがユーザーの正しいエンドポイントです。複数のエンドポイントが配列に含まれている場合、Alexaサービスはユーザーに対してどのエンドポイントを使用すべきかを判断できません。この場合、ユーザーについてAlexa Skill有効化APIを呼び出す際に、返されたすべてのエンドポイントを1つずつ順に呼び出します。正しいエンドポイントのみが呼び出しに成功します。

文字列の配列
403

アクセス拒否です。考えられる原因は次のとおりです。

  • Amazonアクセストークンが無効か、このリクエストを行うアクセス権限がありません。
 エラー
5xx

ユーザーの正しいエンドポイントが見つかりませんでした。この場合、ユーザーについてAlexaスキル有効化APIを呼び出すときに、https://api.amazonalexa.com、https://api.eu.amazonalexa.com、https://api.fe.amazonalexa.comを1つずつ順番に呼び出します。正しいエンドポイントのみが呼び出しに成功します。

 エラー

応答例

以下は、1つのエンドポイントを含む成功応答の例です。

HTTP/1.1 200 OK
Content-Type: application/json,
Cache-Control: no-cache
{
    "endpoints": [
        "api.amazonalexa.com"
    ]
}

以下は、複数のエンドポイントを含む成功応答の例です。これは正しいエンドポイントが見つからなかったことを意味します。

HTTP/1.1 200 OK
Content-Type: application/json,
Cache-Control: no-cache
{
    "endpoints": [
        "api.amazonalexa.com",
        "api.eu.amazonalexa.com",
        "api.fe.amazonalexa.com"
    ]
}

ユーザーに対してスキルを有効にし、アカウントをリンクするには、Alexa Skill有効化APIにPOSTリクエストを行います。ユーザーのエンドポイントを取得するの手順で検出したエンドポイントを使用します。

リクエスト

POST /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: <api.amazonalexa.com、api.eu.amazonalexa.com、またはapi.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"
// 本文は生のJSONです。
{
    "stage": "<skill stage>",
    "accountLinkRequest": {
      "redirectUri": "https://yourRedirectURI",
      "authCode": "認可サーバーから取得したユーザーの認可コード",
      "type": "AUTH_CODE"
    }
}

パラメーター

名前 位置 説明 必須 型
Authorization ヘッダー LWAから取得したAmazonアクセストークンです。Amazonアクセストークンは、ユーザーとスキルに固有です。アクセストークンの詳細については、アクセストークンを参照してください。 ◯ 文字列
skillId パス 更新するスキルのスキルIDです。 ◯ 文字列
stage 本文 スキルのステージです。スキルを公開するまでは、stageをdevelopmentに設定します。スキルの公開時にliveに変更します。 ◯ 文字列です。developmentか liveのいずれかです。
accountLinkRequest 本文 アカウントリンクのリクエスト情報 ◯ オブジェクト
accountLinkRequest.redirectUri 本文 ユーザーの認可コードを取得するための、OAuth 2.0サーバー宛ての認可リクエストに含まれていたredirect_uriパラメーターです。Amazonが開発者のトークンサーバーからアクセストークンを取得するのに使用されます。このURLはAmazonに対してopaqueでなければなりません。 ◯ 文字列
accountLinkRequest.authCode 本文 認可サーバーから取得したユーザーの認可コードです。 ◯ 文字列
accountLinkRequest.type 本文 OAuth 2.0認可リクエストプロトコルに従って分類されたアカウントリンクリクエストの種類です。 ◯ 文字列です。有効な値はAUTH_CODEのみです。

応答

コード 説明 型
201 スキル有効化オブジェクトを含む成功応答です。

skillEnablement object
400

不正なリクエストです。考えられる原因は次のとおりです。

  • skillId、stage、accountLinkingRequest.authCode、accountLinkingRequest.redirectUri、accountLinkingRequest.Typeのいずれかが指定されていません。
  • サービスのトークンサーバーから、サービスのアクセストークンと更新トークンのペアをリクエスト中に、エラーが発生しました。
 エラー
403

アクセス拒否です。考えられる原因は次のとおりです。

  • Amazonアクセストークンが無効です。
  • Amazonアクセストークンに、スキルの有効化についてのユーザーの同意が含まれていません。
  • Amazonアクセストークンは、リクエストで指定されたskillIdに属していません。
  • ユーザーには、リクエストで指定されたskill_idのスキルを有効にする権限がありません。
 エラー
404

見つかりません考えられる原因は次のとおりです。

  • skillIdまたはstageが無効です。
 エラー
409

競合しています。考えられる原因は次のとおりです。

  • スキルは既に有効です。
 エラー
500

内部サーバーエラーです。

 エラー

応答例

以下は、成功応答の例です。

HTTP/1.1 201 CREATED
Content-Type: application/json
{
    "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.123456789"
    },
    "user": {
        "id": "amzn1.ask.account.123456789"
    },
    "accountLink": {
        "status": "LINKED"
    },
    "status": "ENABLED"
}

以下は、失敗応答の例です。

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json
{
    "message": ”認証トークンが無効か、このリクエストを行うアクセス権限がありません。”
}

アカウントリンクとスキルステータス

アカウントリンクのステータスの取得や、スキルが有効かどうかの確認など、ユーザーとスキルの間の関係について情報を収集するには、Alexa Skill有効化APIにGETリクエストを行います。

このリクエストは、スキルを有効にし、アカウントをリンクしたのと同じ地域、つまりユーザーのエンドポイントを取得するの手順で検出したエンドポイントで行う必要があります。たとえば、https://api.eu.amazonalexa.com/でスキルを有効化し、アカウントをリンクした場合に、https://api.amazon.comでGETリクエストを実行すると失敗します。

リクエスト

GET /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: <api.amazonalexa.com、api.eu.amazonalexa.com、またはapi.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"

パラメーター

名前 位置 説明 必須 型
Authorization ヘッダー LWAから取得したAmazonアクセストークンです。Amazonアクセストークンは、ユーザーとスキルに固有です。アクセストークンの詳細については、アクセストークンを参照してください。 ◯ 文字列
skillId パス スキルのスキルIDです。 ◯ 文字列

応答

コード 説明 型
200 スキル有効化オブジェクトを含む成功応答です。

skillEnablement object
403

アクセス拒否です。考えられる原因は次のとおりです。

  • Amazonアクセストークンが、ユーザーのスキル有効化にアクセスできません。
  • Amazonアクセストークンは、リクエストで指定されたskillIdに属していません。
  • Amazonアクセストークンが期限切れのため更新が必要です。
 エラー
404

見つかりません考えられる原因は次のとおりです。

  • skillIdが無効です。
  • スキルが有効化されていません。
 エラー
500 内部サーバーエラーです。 エラー

応答例

以下は、成功応答の例です。

HTTP/1.1 200 OK
Content-Type: application/json
{
    "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.123456789"
    },
    "user": {
        "id": "amzn1.ask.account.123456789"
    },
    "accountLink": {
        "status": "LINKED"
    },
    "status": "ENABLED"
}

以下は、失敗応答の例です。

HTTP/1.1 404 NOT FOUND
Content-Type: application/json
{
    "message": "リクエストされた有効化が見つかりませんでした"
}

ユーザーに対してスキルを無効にし、アカウントをリンク解除するには、Alexa Skill有効化APIにDELETEリクエストを行います。

このリクエストは、スキルを有効にし、アカウントをリンクしたのと同じ地域、つまりユーザーのエンドポイントを取得するの手順で検出したエンドポイントで行う必要があります。たとえば、https://api.eu.amazonalexa.com/でスキルを有効化し、アカウントをリンクした場合に、https://api.amazon.comでDELETEリクエストを実行すると失敗します。

リクエスト

DELETE /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: <api.amazonalexa.com、api.eu.amazonalexa.com、またはapi.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"

パラメーター

名前 位置 説明 必須 型
Authorization ヘッダー LWAから取得したAmazonアクセストークンです。Amazonアクセストークンは、ユーザーとスキルに固有です。アクセストークンの詳細については、アクセストークンを参照してください。 ◯ 文字列
skillId パス 無効にするスキルのスキルIDです。 ◯ 文字列

応答

コード 説明 型
204 成功応答です。 HTTP 204 Content-Type: application/json
403

アクセス拒否です。考えられる原因は次のとおりです。

  • Amazonアクセストークンが、ユーザーのスキル有効化にアクセスできません。
  • Amazonアクセストークンは、リクエストで指定されたskillIdに属していません。
  • Amazonアクセストークンが期限切れのため更新が必要です。
 エラー
404

見つかりません考えられる原因は次のとおりです。

  • skillIdが無効です。
  • スキルが有効化されていません。
 エラー
500 内部サーバーエラーです。 エラー

応答例

以下は、成功応答の例です。

HTTP/1.1 204 NO CONTENT

以下は、失敗応答の例です。

HTTP/1.1 404 NOT FOUND
Content-Type: application/json
{
    "message": "リクエストされたスキルIDとステージの組み合わせが見つかりませんでした。値が正しく入力されているか確認してください。"
}

タイプスキーマ

skillEnablement

{
   "skill": {
      "id": "スキルID",      
      "stage": "スキルのステージ"
   },
   "user": {
      "id": "ユーザーID"
   },
    "accountLink": {
      "status": "LINKED"
   },
   "status": "ENABLED"
}
名前 説明 型
skill スキルIDとステージが含まれたオブジェクトです。 オブジェクト
skill.id スキルのスキルIDです。 文字列
skill.stage スキルのステージです。 文字列です。developmentか liveのいずれかです。スキルを公開するまでは、stageをdevelopmentに設定します。スキルの公開後にliveに変更します。
user ユーザーIDが含まれたオブジェクトです。 オブジェクト
user.id ユーザーの一意のIDです。ユーザーがスキルを無効化してから再有効化した場合には変更されます。 文字列
accountLink 現在のアカウントリンクステータスが含まれたオブジェクトです。 オブジェクト
accountLink.status ユーザーのAmazonアカウントと開発者サービスのアカウントを接続するアカウントリンクの現在のステータスです。 文字列です。LINKEDまたはNOT LINKEDです。
status スキルの現在の有効化ステータスです。 EnablementStatus型の文字列

EnablementStatus列挙値

アカウントリンクのステータスは、次のいずれかの値に変わります。

  • ENABLED: スキルの有効化に成功。
  • ENABLING: 有効化が開始されたが、バックグラウンドプロセスが進行中。
  • ENABLING_FAILED: ユーザーによって有効化が開始されたが、バックグラウンドプロセスが回復不能に失敗。
  • DISABLED: スキルは以前有効化されたが、現在は無効になっている。
  • DISABLING: ユーザーがスキルの有効を停止したが、バックグラウンドプロセスがまだ終了していない。
  • DISABLING_FAILED: ユーザーがスキルの有効を停止したが、バックグラウンドプロセスが回復不能に失敗。
  • NO_ASSOCIATION: ユーザーがスキルを有効にしたことがない。ほとんどの実装では、これを404のように扱う必要がある。

エラー

名前 説明 型
message ユーザーが読める形式のエラー詳細です。 文字列

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

最終更新日: 2022 年 06 月 30 日