スキル管理API

スキル管理API

スキル管理REST APIを使用すると、ルームなどのAlexa Smart Properties（ASP）ユニットのスキルを有効または無効にできます。

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メソッドとパス

ユニットのスキルを無効にする

DELETE /v1/skills/{skillId}/enablements?unitId={unitId}&stage={stage}

複数のユニットのスキルを無効にする

POST /v1/skills/{skillId}/enablements/batchDelete

ユニットのスキルを有効にする

POST /v1/skills/{skillId}/enablements

複数のユニットのスキルを有効にする

POST /v1/skills/{skillId}/enablements/batch

ユニットのスキル有効化を取得する

GET /v1/skills/{skillId}/enablements?unitId={unitId}&stage={stage}&expand={expand}

複数のユニットのスキル有効化を取得する

POST /v1/skills/enablements/batchGet

ユニットの有効なスキルのリストを取得する

GET /v1/skills/enablements?unitId={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}

ユニットのスキルを無効にする

指定されたユニットのスキルを無効にします。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

スキルを無効にするには、/v1/skills/{skillId}/enablementsリソースに対してDELETEリクエストを実行します。

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

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

DELETE /v1/skills/{skillId}/enablements?unitId={unitId}&stage={stage} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

skillId

パス

スキルを識別します。
amzn1.alexa.skill.did.{id}というAmazon Common Identifier（ACI）形式で表します。
有効な値は 1～255文字です。

文字列

◯

unitId

クエリ

指定されたユニットでフィルタリングします。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

stage

クエリ

スキルのステージでフィルタリングします。
有効な値はlive、developmentです。

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

指定されたユニットのスキルが正常に無効化されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

複数のユニットのスキルを無効にする

ユニットのリストに対して指定されたスキルを無効にします。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

複数のユニットのスキルを無効にするには、/v1/skills/{skillId}/enablements/batchDeleteリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/skills/{skillId}/enablements/batchDelete HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

skillId

パス

スキルを識別します。
amzn1.alexa.skill.did.{id}というAmazon Common Identifier（ACI）形式で表します。
有効な値は 1～255文字です。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
    "items": [{
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.101",
            "stage": "live"
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.102",
            "stage": "development"
        },
        {
            "itemId": 2,
            "unitId": "amzn1.alexa.unit.103"
        }
    ]
}

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

プロパティ 説明 型 必須

items

指定されたスキルを無効にするユニットのリスト。
リストには最大100個のユニットを含めることができます。

オブジェクトの配列

◯

items[].itemId

無効化の一意のID。

整数

◯

items[].unitId

ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

items[].stage

スキルのステージを識別します。
有効な値はlive、developmentです。

文字列

✕

応答

正常に完了すると、HTTP 202 Acceptedが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にBatchErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

202 Accepted

スキルが正常に無効化されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • BAD_REQUEST - リクエストの形式が正しくないか、必須パラメーターが不足しています。
  • INVALID_PARAM - リクエストのパラメーターがないか、無効です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • ENABLEMENT_NOT_FOUND - リクエストされた有効化が見つかりませんでした。
  • SKILL_STAGE_NOT_FOUND - リクエストされたスキルIDとステージの組み合わせが見つかりませんでした。

429 Too Many Requests

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

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。
このエラーは、無指名呼び出しのステータスの取得に失敗した場合に発生することがあります。

503 Service Unavailable

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

ユニットのスキルを有効にする

指定されたユニットのスキルを有効にします。パーティション、無指名対話、アカウントリンクの情報を含めることができます。アカウントリンクの情報を含めると、Alexaはアカウントのリンクを試行します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

スキルを有効にするには、/v1/skills/{skillId}/enablementsリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/skills/{skillId}/enablements HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

skillId

パス

スキルを識別します。
amzn1.alexa.skill.did.{id}というAmazon Common Identifier（ACI）形式で表します。
有効な値は 1～255文字です。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

以下の例は、アカウントリンクや無指名対話といった追加情報を含まない、1つのユニットに対する基本的なスキルの有効化を示しています。

以下の例は、アカウントリンクとパーティションの情報を含む、1つのユニットに対するスキルの有効化を示しています。

以下の例は、無指名対話をサポートするスキルに対する有効化を示しています。

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

プロパティ 説明 型 必須

unitId

ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

stage

スキルのステージを識別します。
有効な値はlive、developmentです。

文字列

◯

partitionName

デバイス、エンドポイント、スキルなどのリソースの論理グループを識別します。1つのパーティション名か、複数のパーティション名のカンマ区切りリストを指定します。各パーティション名は空でない単一の文字列で、英数字とハイフンを含めることができますが、空白は使用できません。
たとえば、「Room-101」や「Room101, Room202」は、このパラメーターの値として有効ですが、「」（空のリスト）、「Room101, ,Room202」（カンマ区切りが正しくない）、「Room 101」（空白を含む）は有効な値ではありません。

文字列

✕

accountLinkRequest

アカウントリンクの情報。
アカウントリンクが必要なスキルの場合は必須です。

オブジェクト

✕

accountLinkRequest.redirectUri

ユーザーの認可コードを取得するためにOAuth 2.0サーバー宛ての認可リクエストに含まれていたredirect_uriパラメーターと同じ値を使用します。このURIにより、Amazonは開発者のトークンサーバーからアクセストークンを取得できます。このURLはAmazonに対してopaqueでなければなりません。

文字列

◯

accountLinkRequest.authCode

OAuth 2.0認可コード。詳細については、Authorization Code Grantフローの概要を参照してください。

文字列

◯

accountLinkRequest.type

OAuth 2.0認可リクエストプロトコルに基づくアカウントリンクリクエストのタイプ。
有効な値は AUTH_CODEです。

文字列

◯

nameFreeInvocationRequest

無指名対話の情報。
無指名対話をサポートしているスキルの場合にのみ含めます。

オブジェクト

✕

nameFreeInvocationRequest.locales

無指名対話を有効にするロケール。スキルには、ロケールをサポートする対話モデルが必要です。最大5つのロケールを含めることができます。
有効な値はen-US、es-US、en-CA、fr-CA、en-GB、fr-FR、it-IT、de-DE、es-ESです。

文字列の配列

◯

応答

正常に完了すると、HTTP 201 Createdと共に、指定されたユニットの有効化の詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
  "skill": {
    "stage": "stage",
    "id": "{skillId}"
  },
  "unit": {
    "id": "{unitId}"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "nameFreeInvocation": {
    "status": "ENABLED",
    "locales": ["ja-JP"]
  },
  "status": "ENABLING",
}

応答本文のプロパティ

プロパティ 説明 型

skill

スキルの情報。

オブジェクト

skill.id

スキルを識別します。

文字列

skill.stage

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

unit

ユニットを識別します。

オブジェクト

unit.id

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

文字列

accountLink

Amazonビジネスアカウントとシステム内のアカウント間のアカウントリンクのステータス。アカウントリンクが必要なスキルの場合に含めます。

オブジェクト

accountLink.status

アカウントリンクのステータス。アカウントリンクをサポートしないスキルの場合はNOT_LINKEDに設定します。
有効な値は LINKED、NOT_LINKEDです。

文字列

nameFreeInvocation

無指名対話の情報。

オブジェクト

nameFreeInvocation.status

無指名対話の有効化ステータス。無指名対話をサポートしないスキルの場合はDISABLEDに設定します。
有効な値は DISABLED、ENABLEDです。

文字列

nameFreeInvocation.locales

（オプション）無指名対話を有効にするロケール。スキルには、ロケールをサポートする対話モデルが必要です。最大5つのロケールを含めることができます。
有効な値はen-US、es-US、en-CA、fr-CA、en-GB、fr-FR、it-IT、de-DE、es-ESです。

文字列の配列

status

スキルの有効化ステータス。
有効な値は次のとおりです。

  • ENABLED： スキルが正常に有効化されました。
  • ENABLING： 有効化が開始されました。

文字列

HTTPステータスコード

ステータス 説明

201 Created

有効化の結果が応答本文に含まれます。

400 Bad Request

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

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

複数のユニットのスキルを有効にする

1回のリクエストで複数のユニットのスキルを有効にします。パーティション、無指名対話、アカウントリンクの情報を含めることができます。アカウントリンクの情報を含めると、Alexaはアカウントのリンクを試行します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

複数のユニットのスキルを有効にするには、/v1/skills/{skillId}/enablements/batchリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/skills/{skillId}/enablements/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

skillId

パス

スキルを識別します。
amzn1.alexa.skill.did.{id}というAmazon Common Identifier（ACI）形式で表します。
有効な値は 1～255文字です。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

以下の例は、アカウントリンクや無指名対話といった追加情報を含まない、複数のユニットに対する基本的なスキルの有効化を示しています。

以下の例は、アカウントリンクとパーティションの情報を含む、複数のユニットに対するスキルの有効化を示しています。

以下の例は、無指名対話をサポートするスキルに対する有効化を示しています。

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

プロパティ 説明 型 必須

items

指定されたスキルを有効にするユニットのリスト。
リストには最大100個のユニットを含めることができます。

オブジェクトの配列

◯

items[].itemId

有効化の一意のID。

整数

◯

items[].unitId

ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

items[].stage

スキルのステージを識別します。
有効な値はlive、developmentです。

文字列

✕

items[].partitionName

デバイス、エンドポイント、スキルなどのリソースの論理グループを識別します。1つのパーティション名か、複数のパーティション名のカンマ区切りリストを指定します。各パーティション名は空でない単一の文字列で、英数字とハイフンを含めることができますが、空白は使用できません。
たとえば、「Room-101」や「Room101, Room202」は、このパラメーターの値として有効ですが、「」（空のリスト）、「Room101, ,Room202」（カンマ区切りが正しくない）、「Room 101」（空白を含む）は有効な値ではありません。

文字列

✕

items[].accountLinkRequest

アカウントリンクの情報。
アカウントリンクが必要なスキルの場合は必須です。

オブジェクト

✕

items[].accountLinkRequest.redirectUri

ユーザーの認可コードを取得するためにOAuth 2.0サーバー宛ての認可リクエストに含まれていたredirect_uriパラメーターと同じ値を使用します。このURIにより、Amazonは開発者のトークンサーバーからアクセストークンを取得できます。このURLはAmazonに対してopaqueでなければなりません。

文字列

◯

items[].accountLinkRequest.authCode

OAuth 2.0認可コード。詳細については、Authorization Code Grantフローの概要を参照してください。

文字列

◯

items[].accountLinkRequest.type

OAuth 2.0認可リクエストプロトコルに基づくアカウントリンクリクエストのタイプ。
有効な値は AUTH_CODEです。

文字列

◯

items[].nameFreeInvocationRequest

無指名対話の情報。
無指名対話をサポートしているスキルの場合にのみ含めます。

オブジェクト

✕

items[].nameFreeInvocationRequest.locales

無指名対話を有効にするロケール。スキルには、ロケールをサポートする対話モデルが必要です。最大5つのロケールを含めることができます。
有効な値はen-US、es-US、en-CA、fr-CA、en-GB、fr-FR、it-IT、de-DE、es-ESです。

文字列の配列

◯

応答

正常に完了すると、HTTP 202 Acceptedが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にBatchErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

202 Accepted

各ユニットでスキルが正常に有効化されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • BAD_REQUEST - リクエストの形式が正しくないか、必須パラメーターが不足しています。
  • INVALID_PARAM - リクエストのパラメーターがないか、無効です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • ENABLEMENT_NOT_FOUND - リクエストされた有効化が見つかりませんでした。
  • SKILL_STAGE_NOT_FOUND - リクエストされたスキルIDとステージの組み合わせが見つかりませんでした。

429 Too Many Requests

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

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。
このエラーは、無指名呼び出しのステータスの取得に失敗した場合に発生することがあります。

503 Service Unavailable

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

ユニットのスキル有効化を取得する

特定のスキルおよびユニットのスキル有効化レコードを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

有効化レコードを取得するには、/v1/skills/{skillId}/enablementsリソースに対してGETリクエストを実行します。

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

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

GET /v1/skills/{skillId}/enablements?unitId={unitId}&stage={stage}&expand={expand} HTTP/1.1
Host: api.amazonalexa.com 
Accept: application/json
Authorization: Bearer {access token}

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

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

skillId

パス

スキルを識別します。
amzn1.alexa.skill.did.{id}というAmazon Common Identifier（ACI）形式で表します。
有効な値は 1～255文字です。

文字列

◯

unitId

クエリ

指定されたユニットでフィルタリングします。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

stage

クエリ

スキルのステージでフィルタリングします。
有効な値はlive、developmentです。

文字列

✕

expand

クエリ

応答に含めるアトリビュートまたはアトリビュートのセットを識別します。
有効な値はnameFreeInvocationです。

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたスキルおよびユニットの有効化の詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下の例は、指定されたスキルおよびユニットのスキル有効化の詳細を示しています。

以下の例は、expandアトリビュートを含むリクエストに対する、指定されたスキルおよびユニットのスキル有効化の詳細を示しています。

応答本文のプロパティ

プロパティ 説明 型

skill

スキルの情報。

オブジェクト

skill.id

スキルを識別します。

文字列

skill.stage

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

unit

ユニットを識別します。

オブジェクト

unit.id

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

文字列

accountLink

Amazonビジネスアカウントとシステム内のアカウント間のアカウントリンクのステータス。

オブジェクト

accountLink.status

アカウントリンクのステータス。
アカウントリンクをサポートしないスキルの場合はNOT_LINKEDに設定します。
有効な値は LINKED、NOT_LINKEDです。

文字列

nameFreeInvocation

無指名対話の情報。

オブジェクト

nameFreeInvocation.status

無指名対話の有効化ステータス。無指名対話をサポートしないスキルの場合はDISABLEDに設定します。
有効な値は DISABLED、ENABLEDです。

文字列

nameFreeInvocation.locales

（オプション）無指名対話を有効にするロケール。スキルには、ロケールをサポートする対話モデルが必要です。無指名呼び出しをサポートしているスキルの場合、最大5つのロケールを含めることができます。
有効な値はen-US、es-US、en-CA、fr-CA、en-GB、fr-FR、it-IT、de-DE、es-ESです。

文字列の配列

status

スキルの有効化ステータス。
有効な値は次のとおりです。

  • ENABLED： スキルが正常に有効化されました。
  • ENABLING： 有効化が開始されました。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたスキルおよびユニットの有効化の詳細が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

複数のユニットのスキル有効化を取得する

特定のスキルおよび1つ以上のユニットのスキル有効化レコードを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

スキルを有効にするには、/v1/skills/enablements/batchGetリソースに対してPOSTリクエストを実行します。

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

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

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

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

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

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

以下の例では、4つのユニットのスキル有効化レコードをリクエストしています。このリクエストの例には、expandパラメーターが含まれています。

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

{
  "items": [
    {
      "itemId": 0,
      "unitId": "amzn1.alexa.unit.101"
    },
    {
      "itemId": 1,
      "unitId": "amzn1.alexa.unit.102"
    },
    {
      "itemId": 2,
      "unitId": "amzn1.alexa.unit.103"
    },
    {
      "itemId": 3,
      "unitId": "amzn1.alexa.unit.104"
    },
  ],
  "expand": ["nameFreeInvocation"],
  "paginationContext": {
      "maxResults" : 5,
      "nextToken": "someToken.1"
  }
}

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

プロパティ 説明 型 必須

items

リクエストされたユニットのリスト。
リストには最大100個のユニットを含めることができます。

オブジェクトの配列

◯

items[].itemId

リクエストの一意のID。

整数

◯

items[].unitId

ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

expand

応答に含めるアトリビュートまたはアトリビュートのセットを識別します。
有効な値はnameFreeInvocationです。

文字列

✕

paginationContext

次の結果セットを取得する場合に含めます。
詳細については、APIのクエリ結果のページ分割を処理するを参照してください。

オブジェクト

✕

paginationContext.maxResults

応答で返される結果の最大数。
有効な値は 1～10です。デフォルト値は 10です。

整数

✕

paginationContext.nextToken

前回の応答で受け取ったものを含めます。

文字列

✕

応答

正常に完了すると、HTTP 200 OKと共に、指定されたユニットの有効なスキルのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にBatchErrorオブジェクトが追加されます。

応答本文の例

応答本文のプロパティ

プロパティ 説明 型

results

指定されたユニットの有効なスキルのリスト。

オブジェクトの配列

results[].itemId

リクエスト内の項目を識別します。

整数

results[].enablements

ユニットの有効なスキルのリスト。

オブジェクトの配列

results[].enablements[].skill

スキルの情報。

オブジェクト

results[].enablements[].skill.id

スキルを識別します。

文字列

results[].enablements[].skill.stage

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

results[].enablements[].unit

ユニットを識別します。

オブジェクト

results[].enablements[].unit.id

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

文字列

results[].enablements[].accountLink

Amazonビジネスアカウントとシステム内のアカウント間のアカウントリンクのステータス。

オブジェクト

results[].enablements[].accountLink.status

アカウントリンクのステータス。
アカウントリンクを必要としないスキルの場合はNOT_LINKEDに設定します。
有効な値は LINKED、NOT_LINKEDです。

文字列

results[].enablements[].nameFreeInvocation

無指名対話の情報。

オブジェクト

results[].enablements[].nameFreeInvocation.status

無指名対話の有効化ステータス。無指名対話をサポートしないスキルの場合はDISABLEDに設定します。
有効な値は DISABLED、ENABLEDです。

文字列

results[].enablements[].nameFreeInvocation.locales

（オプション）無指名対話を有効にするロケール。スキルには、ロケールをサポートする対話モデルが必要です。最大5つのロケールを含めることができます。
有効な値はen-US、es-US、en-CA、fr-CA、en-GB、fr-FR、it-IT、de-DE、es-ESです。

文字列の配列

results[].enablements[].status

スキルの有効化ステータス。
有効な値は次のとおりです。

  • ENABLED： スキルが正常に有効化されました。
  • ENABLING： 有効化が開始されました。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。この値は後続のリクエストで使用します。
この値が存在しない場合は、これ以上結果がないことを示します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたユニットごとの有効化ステータスのリストが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • BAD_REQUEST - リクエストの形式が正しくないか、必須パラメーターが不足しています。
  • INVALID_PARAM - リクエストのパラメーターがないか、無効です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • ENABLEMENT_NOT_FOUND - リクエストされた有効化が見つかりませんでした。
  • SKILL_STAGE_NOT_FOUND - リクエストされたスキルIDとステージの組み合わせが見つかりませんでした。

429 Too Many Requests

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

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。
このエラーは、無指名呼び出しのステータスの取得に失敗した場合に発生することがあります。

503 Service Unavailable

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

ユニットの有効なスキルのリストを取得する

指定されたユニットの有効なスキルのリストを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

スキルのリストを取得するには、/v1/skills/enablementsリソースに対してGETリクエストを実行します。

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

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

GET /v1/skills/enablements?unitId={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

unitId

クエリ

ユニットでフィルタリングします。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

expand

クエリ

応答に含めるアトリビュートまたはアトリビュートのセットを識別します。
有効な値はnameFreeInvocationです。

文字列

✕

maxResults

クエリ

応答で返される結果の最大数。
有効な値は 1～10です。デフォルト値は 10です。

整数

✕

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたユニットの有効なスキルのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下の例では、指定されたユニットの有効なすべてのスキルのリストが返されます。

以下の例では、expandアトリビュートを含むリクエストに対して、指定されたユニットの有効なすべてのスキルのリストが返されます。

応答本文のプロパティ

プロパティ 説明 型

items

指定されたユニットの有効なスキルのリスト。

オブジェクトの配列

items[].skill

スキルの情報。

オブジェクト

items[].skill.id

スキルを識別します。

文字列

items[].skill.stage

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

items[].unit

スキルが関連付けられているユニット。

オブジェクト

items[].unit.id

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

文字列

items[].accountLink

Amazonビジネスアカウントとシステム内のアカウント間のアカウントリンクのステータス。

オブジェクト

items[].accountLink.status

アカウントリンクのステータス。
アカウントリンクを必要としないスキルの場合はNOT_LINKEDに設定します。
有効な値は LINKED、NOT_LINKEDです。

文字列

items[].status

スキルの有効化ステータス。
有効な値は次のとおりです。

  • ENABLED： スキルが正常に有効化されました。
  • ENABLING： 有効化が開始されました。

文字列

items[].nameFreeInvocation

（オプション）無指名対話の情報。リクエストでexpandパラメーターを指定した場合に応答に含まれます。

オブジェクト

items[].nameFreeInvocation.status

無指名対話の有効化ステータス。無指名対話をサポートしないスキルの場合はDISABLEDに設定します。
有効な値は DISABLED、ENABLEDです。

文字列

items[].nameFreeInvocation.locales

（オプション）無指名対話を有効にするロケール。スキルには、ロケールをサポートする対話モデルが必要です。最大5つのロケールを含めることができます。
有効な値はen-US、es-US、en-CA、fr-CA、en-GB、fr-FR、it-IT、de-DE、es-ESです。

文字列の配列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。この値は後続のリクエストで使用します。
結果がこれ以上ない場合は、nextTokenは含まれません。

文字列

オブジェクトの定義

スキル管理APIでは、以下のオブジェクト定義が定義されています。

BatchErrorオブジェクト

BatchErrorオブジェクトは、バッチ操作中にエラーが発生した場合に応答に含まれるエラーコードと説明を定義します。itemIdは、失敗したリクエスト内の項目を表します。

以下は、応答本文の例です。

{
  "errors": [
    {
       "itemId": 0,
       "status": 400,   
       "errorCode" : "INVALID_PRINCIPAL_ID",   
       "errorDescription": "Invalid principalId specified."
    },
    {
       "itemId": 3,
       "status": 400,      
       "errorCode" : "REQUEST_LIMIT_EXCEEDED",
       "errorDescription": "The number of request items in the batch request exceeds the limit (50)."
    }
  ]
}

BatchErrorオブジェクトには、以下のプロパティが定義されています。

プロパティ 説明 型

itemId

（オプション）失敗したリクエスト項目を識別します。

整数

status

HTTPステータスコード。

文字列

errorCode

発生したエラーのタイプ。

文字列

errorDescription

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

文字列

Errorオブジェクト

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

以下は、応答本文の例です。

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

Errorオブジェクトには、以下のプロパティが定義されています。

プロパティ 説明 型

type

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

文字列

message

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

文字列

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

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