スキル管理API

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

スキル管理API

注：このAPIは、登録済みのAlexa Smart Properties in Senior Livingパートナーのみ使用できます。Alexa Smart Properties in Senior Living APIで開発を始めるを参照してください。

ルームのようなAlexa Smart Properties in Senior Livingのユニットに対するスキルを管理するには、スキル管理APIを使用します。

APIエンドポイント

スキル管理APIのエンドポイントはhttps://api.amazonalexa.comです。

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。

操作

スキル管理APIには、以下の操作があります。

説明	HTTPメソッドとパス
1つのユニットの1つのスキル有効化レコードを取得する	`GET /v1/skills/{skillId}/enablements?unitId={unitId}`
1つのユニットのスキル有効化リストを取得する	`GET /v1/skills/enablements?unitId={unitId}`
1つのユニットでスキルを有効にする	`POST /v1/skills/{skillId}/enablements`
1つのユニットでスキルを無効にする	`DELETE /v1/skills/{skillId}/enablements?unitId={unitId}`
複数のユニットでスキルを有効にする	`POST /v1/skills/{skillId}/enablements/batch`
複数のユニットでスキルを無効にする	`POST /v1/skills/{skillId}/enablements/batchDelete`
複数のユニットのスキル有効化を取得する	`POST /v1/skills/enablements/batchGet`

1つのユニットの1つのスキル有効化レコードを取得する

1つのユニットの特定のスキルに対するスキル有効化レコードを取得するには、GET /v1/skills/{skillId}/enablements?unitId={unitId}を呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

GET /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

リクエスト本文

なし。

リクエストのパスパラメーター

フィールド	説明	型	必須
`skillId`	スキルID。形式は`"amzn1.alexa.skill.{id}"`。	文字列	◯

リクエストのクエリパラメーター

フィールド	説明	型	必須
`unitId`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列	◯

成功応答のヘッダー

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

応答本文の例

{
   "skill": {
      "stage": "stage",
      "id": "amzn1.ask.skill.skillId"
   },
   "unit": {
      "id": "amzn1.alexa.unit.unitId"
   },
   "accountLink": {
      "status": "LINKED"
  },
   "status": "ENABLED",
}

応答本文のパラメーター

フィールド	説明	型
`skill.stage`	スキルステージは`development`、`certification`、`live`のいずれかになります。	列挙
`skill.id`	スキルの一意のIDです。	文字列
`unit.id`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列
`accountLink.status`	ユーザーのAmazonアカウントと開発者サービスのアカウントを接続するアカウントリンクの現在のステータスです。 `LINKED`または`NOT LINKED`です。アカウントリンクをサポートしないスキルの場合、`NOT_LINKED`が返されます。	文字列
`status`	スキルの有効化ステータス： `ENABLING`または`ENABLED`。	列挙

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド	説明	型
`type`	エラータイプ。	文字列
`message`	エラーのエラーメッセージです。注：エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。	文字列

HTTP応答コード

ステータスコード	名前	説明
200	OK	リクエストが成功しました。
400	Bad Request	リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
401	Unauthorized	アクセストークンがないか、期限切れか、無効です。
403	Forbidden	操作を実行する権限がユーザーにありません。
404	Not found	リクエストされたスキルIDまたはユニットIDが見つかりません。
429	Too many requests	リクエストが制限されています。
500	Internal Server Error	内部サービスエラーのためリクエストを処理できませんでした。
503	Service Unavailable	サーバーが一時的に使用できません。

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

1つのユニットのすべてのスキル有効化を含むリストを取得するには、GET /v1/skills/enablements?unitId={unitId}を呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

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

リクエスト本文

なし。

リクエストのクエリパラメーター

フィールド	説明	型	必須
`unitId`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列	◯
`nextToken`	スキル有効化のリストを取得する前回の応答で、応答オブジェクトに返された継続トークン。詳細については、クエリ結果のページ分割を処理するを参照してください。	文字列	✕
`maxResults`	表示する結果の最大数。値は1～10の間で指定します。デフォルトは10です。	整数	✕

成功応答のヘッダー

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

応答本文の例

{
  "paginationContext": {
    "nextToken": "amzn1.ask.skill.tokenUUID"
  },
  "items": [
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId1"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "accountLink": {
        "status": "NOT_LINKED"
      },
      "status": "ENABLED"
    },
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId2"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "accountLink": {
        "status": "NOT_LINKED"
      },
      "status": "ENABLED",
    }
  ]
}

応答本文のパラメーター

フィールド	説明	型
`paginationContext`	ページ分割が必要なデータを含むコンテキスト。	オブジェクト
`paginationContext.nextToken`	後続データを取得するために使用するトークン。もうレコードがない場合、このトークンは存在しません。	文字列
`items`	スキル有効化のリスト。	リスト（セット）
`skill.stage`	スキルステージは`development`、`certification`、`live`のいずれかになります。	列挙
`skill.id`	スキルの一意のIDです。	文字列
`unit.id`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列
`accountLink.status`	ユーザーのAmazonアカウントと開発者サービスのアカウントを接続するアカウントリンクの現在のステータスです。 `LINKED`または`NOT LINKED`です。アカウントリンクをサポートしないスキルの場合、`NOT_LINKED`が返されます。	文字列
`status`	スキルの有効化ステータス： `ENABLING`または`ENABLED`。	列挙

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド	説明	型
`type`	エラータイプ。	文字列
`message`	エラーのエラーメッセージです。注：エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。	文字列

HTTP応答コード

ステータスコード	名前	説明
200	OK	リクエストが成功しました。
400	Bad Request	リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
401	Unauthorized	アクセストークンがないか、期限切れか、無効です。
403	Forbidden	操作を実行する権限がユーザーにありません。
429	Too many requests	リクエストが制限されています。
500	Internal Server Error	内部サービスエラーのためリクエストを処理できませんでした。
503	Service Unavailable	サーバーが一時的に使用できません。

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

1つのユニットで1つのスキルを有効にするには、POST /v1/skills/{skillId}/enablementsを呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

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

リクエストのパスパラメーター

フィールド	説明	型	必須
`skillId`	スキルID。形式は`"amzn1.alexa.skill.{id}"`。	文字列	◯

リクエスト本文の例

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "partitionName": "Room101-Kitchenette",
  "accountLinkRequest": {
    "redirectUri": "https://example.com",
    "authCode": "3pauthcode",
    "type": "AUTH_CODE"
  }
}

リクエスト本文のパラメーター

フィールド	説明	型	必須
`unitId`	ユニットID。`"amzn1.alexa.unit.did.{id}"`形式で指定します。	文字列	◯
`stage`	スキルステージは`development`または`live`です。	列挙	◯
`partitionName`	パーティション名は、デバイス、エンドポイント、スキルなどのリソースの論理グループを表す識別子です。このパラメーターには、1つのパーティション名を含む文字列か、複数のパーティション名を含むカンマ区切りリストを指定します。各パーティション名は空でない単一の文字列で、英数字とハイフンを含めることができますが、空白は使用できません。たとえば、「Room-101」や「Room101, Room202」は、このパラメーターの値として有効です。一方、「」（空のリスト）、「Room101, ,Room202」（カンマ区切りが正しくない）、「Room 101」（空白を含む）は有効な値ではありません。注：特定の`skillId`と`unitId`に既存の有効化がある場合、同じ`skillId`と`unitId`に対して異なる`partitionName`値（新規、更新、指定なし）を使用して`POST`有効化リクエストを実行すると、既存の有効化が最新の`partitionName`値で更新されます。注：既存の有効化に対して`accountLinkRequest`と`partitionName`の両方を指定して`POST`有効化リクエストを実行すると、そのAPI呼び出しにより、既存のアカウントリンクとパーティション名が更新されます。	文字列	✕
`accountLinkRequest`	アカウントリンクリクエスト情報（AccountLinkRequestオブジェクトとして）。	オブジェクト	◯（アカウントリンクをサポートしているスキルの場合）

AccountLinkRequestオブジェクトスキーマ

フィールド	説明	型	必須
`redirectUri`	ユーザーの認可コードを取得するための、OAuth 2.0サーバー宛ての認可リクエストに含まれていた`redirect_uri`パラメーターです。Amazonが開発者のトークンサーバーからアクセストークンを取得するのに使用されます。このURLはAmazonに対してopaqueでなければなりません。	文字列	◯
`authCode`	OAuth 2.0認可コード。この値は、アカウントリンクを実行するのに必要です。詳細については、Authorization Code Grantフローを参照してください。	文字列	◯
`type`	OAuth 2.0認可リクエストプロトコルに従って分類されたアカウントリンクリクエストの種類です。現時点でサポートされる値は、`AUTH_CODE`のみです。	文字列	◯

成功応答のヘッダー

HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

応答本文の例

{
  "skill": {
    "stage": "stage",
    "id": "{skillId}"
  },
  "unit": {
    "id": "{unitId}"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "status": "ENABLING",
}

応答本文のパラメーター

フィールド	説明	型
`skill.stage`	スキルステージは`development`または`live`です。	列挙
`skill.id`	スキルの一意の識別子。形式は`"amzn1.ask.skill.{id}"`。	文字列
`unit.id`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列
`accountLink.status`	ユーザーのAmazonアカウントと開発者サービスのアカウントを接続するアカウントリンクの現在のステータスです。 `LINKED`または`NOT LINKED`です。`accountLink`オブジェクトは、アカウントリンクをサポートするスキルにのみ存在します。	文字列
`status`	スキルの有効化ステータス： `ENABLING`または`ENABLED`。	列挙

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド	説明	型
`type`	エラータイプ。	文字列
`message`	エラーのエラーメッセージです。注：エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。	文字列

HTTP応答コード

ステータスコード	名前	説明
201	Created	スキルは正常に有効化されました。
400	Bad Request	リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
401	Unauthorized	アクセストークンがないか、期限切れか、無効です。
403	Forbidden	操作を実行する権限がユーザーにありません。
404	Not found	リクエストされたスキルIDまたはユニットIDが見つかりません。
429	Too many requests	リクエストが制限されています。
500	Internal Server Error	内部サービスエラーのためリクエストを処理できませんでした。
503	Service Unavailable	サーバーが一時的に使用できません。

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

1つのユニットに対してスキルを無効にするには、DELETE /v1/skills/{skillId}/enablements?unitId={unitId}を呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

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

リクエスト本文

なし。

リクエストのパラメーター

フィールド	説明	型	必須
`unitId`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列	◯
`skillId`	スキルID。形式は`"amzn1.alexa.skill.{id}"`。	文字列	◯
`stage`	スキルステージは`development`、`certification`、`live`のいずれかになります。指定する場合、このステージが有効である必要があります。	列挙	✕

成功応答のヘッダー

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

成功応答のパラメーター

なし。

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド	説明	型
`type`	エラータイプ。	文字列
`message`	エラーのエラーメッセージです。注：エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。	文字列

HTTP応答コード

ステータスコード	名前	説明
204	No Content	スキル有効化は正常に削除されました。
400	Bad Request	リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
401	Unauthorized	アクセストークンがないか、期限切れか、無効です。
403	Forbidden	操作を実行する権限がユーザーにありません。
404	Not found	リクエストされたスキルIDまたはユニットIDが見つかりません。
429	Too many requests	リクエストが制限されています。
500	Internal Server Error	内部サービスエラーのためリクエストを処理できませんでした。
503	Service Unavailable	サーバーが一時的に使用できません。

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

単一のリクエストで複数のユニットに対して1つのスキルを有効にするには、POST /v1/skills/{skillId}/enablements/batchを呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

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

リクエストのパスパラメーター

フィールド	説明	型	必須
`skillId`	スキルID。形式は`"amzn1.alexa.skill.{id}"`。	文字列	◯

リクエスト本文の例

以下の例は、2つのユニットに対して1つのスキルを有効にするリクエスト本文の例です。この本文には2つの項目が含まれ、それぞれが各ユニットに対応しています。

{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live",
            "partitionName": "10-101", // 任意
            "accountLinkRequest": { // 任意。アカウントリンクをサポートするスキルのみ
                "redirectUri": "https://redirecturi.com",
                "authCode": "3pauthcode1",
                "type": "AUTH_CODE"
            }
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live",
            "partitionName": "11-101,11-102,11-103" // 任意
        }
    ]
}

リクエスト本文のパラメーター

フィールド	説明	型	必須
`items`	リクエスト項目のリスト。各項目が1つのユニットに対する有効化リクエストを表します。	配列	◯
`itemId`	リクエスト項目の一意のID。リクエスト内で一意である必要があります。	整数	◯
`unitId`	ユニットID。`"amzn1.alexa.unit.did.{id}"`形式で指定します。	文字列	◯
`stage`	スキルステージは`development`、`certification`、`live`のいずれかになります。	列挙	◯
`partitionName`	パーティション名は、デバイス、エンドポイント、スキルなどのリソースの論理グループを表す識別子です。このパラメーターには、1つのパーティション名を含む文字列か、複数のパーティション名を含むカンマ区切りリストを指定します。たとえば、「Room-101」や「Room101, Room202」は、このパラメーターの値として有効です。一方、「」（空のリスト）、「Room101, ,Room202」（カンマ区切りが正しくない）、「Room 101」（空白を含む）は有効な値ではありません。注：特定の`skillId`と`unitId`に既存の有効化がある場合、同じ`skillId`と`unitId`に対して異なる`partitionName`値（新規、更新、指定なし）を使用して再び`POST`有効化リクエストを実行すると、既存の有効化が最新の`partitionName`値で更新されます。	文字列	✕
`accountLinkRequest`	アカウントリンクリクエスト情報（AccountLinkRequestオブジェクトとして）。	オブジェクト	◯（アカウントリンクをサポートしているスキルの場合）

成功応答

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

成功応答のパラメーター

なし。

エラー応答のヘッダー

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答本文の例

以下の例に示されているのは、リクエスト全体のエラー応答本文であって、個々の項目のエラー応答本文ではありません。

{
    "errors": [
        {
            "status": 401,
            "erorrCode": "INVALID_LWA_TOKEN",
            "errorDescription": "The access token is invalid."
        }
    ]
}

以下の例は、個々の項目に対するエラー応答本文の例です。

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "unitId is missing or invalid"
        },
        {
            "itemId": 20,
            "status": 403,
            "errorCode": "FORBIDDEN",
            "errorDescription": "The operator doesn't have the right permission to perform the operation."
        }
    ]
}

エラー応答のパラメーター

フィールド	説明	型	必須
`errors`	エラー応答のリスト。それぞれが各リクエスト項目に対応しています。	配列	◯
`itemId`	リクエスト項目のID。個々の項目ではなくリクエスト全体に対するエラー応答である場合は任意です。	文字列	✕
`status`	リクエストまたはリクエスト項目ごとの応答ステータスコード。	整数	◯
`errorCode`	エラーのエラーコード。	列挙	◯
`errorDescription`	エラーの説明です。	文字列	◯

HTTP応答コード

ステータスコード	名前	説明
202	Accepted	リクエストは受け付けられました。
400	Bad Request	リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。たとえば、次のような理由が考えられます。 • `skillId`がないか無効です。 • `unitId`がないか無効です。 • リクエストされた`skillId`と`stage`の組み合わせが見つかりませんでした。 • リクエスト項目の数が上限を超えています。
401	Unauthorized	アクセストークンがないか、期限切れか、無効です。
403	Forbidden	操作を実行する権限がユーザーにありません。
429	Too many requests	リクエストが制限されています。
500	Internal Server Error	内部サービスエラーのためリクエストを処理できませんでした。
503	Service Unavailable	サーバーが一時的に使用できません。

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

単一のリクエストで複数のユニットに対して1つのスキルを削除するには、POST /v1/skills/{skillId}/enablements/batchDeleteを呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

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

リクエストのパスパラメーター

フィールド	説明	型	必須
`skillId`	スキルID。形式は`"amzn1.alexa.skill.{id}"`。	文字列	◯

リクエスト本文の例

以下の例は、3つのユニットに対して1つのスキルを無効にするリクエスト本文の例です。

{
  "items": [
    {
        "itemId": 0,
        "unitId": "amzn1.alexa.unit.unitId1",
        "stage": "live"
    },
    {
        "itemId": 1
        "unitId": "amzn1.alexa.unit.unitId2",
        "stage": "development"
    },
    {
        "itemId": 2
        "unitId": "amzn1.alexa.unit.unitId3"
    }
  ]
}

リクエスト本文のパラメーター

フィールド	説明	型	必須
`items`	リクエスト項目のリスト。各項目が1つのユニットに対する無効化リクエストを表します。	配列	◯
`items[*].itemId`	リクエスト項目の一意のIDです。リクエスト内で一意である必要があります。	整数	◯
`items[*].unitId`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列	◯
`stage`	スキルステージは`development`、`certification`、`live`のいずれかになります。指定する場合、このスキルステージが無効になります。	列挙	✕

成功応答

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

成功応答のパラメーター

なし。

エラー応答のヘッダー

HTTP/1.1 {ErrorCode}
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

エラー応答本文の例

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

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]
}

エラー応答のパラメーター

フィールド	説明	型
`errors`	エラー応答のリスト。それぞれが各リクエスト項目に対応しています。	配列
`errors[*].itemId`	リクエスト項目のID。個々の項目ではなくリクエスト全体に対するエラー応答である場合は任意です。	文字列
`errors[*].status`	リクエストまたはリクエスト項目ごとの応答ステータスコード。	整数
`errors[*].errorCode`	エラーのエラーコード。	列挙
`errors[*].errorDescription`	エラーの説明です。	文字列

HTTP応答コード

ステータスコード	名前	説明
202	Accepted	リクエストは受け付けられました。
400	INVALID_PARAM	リクエスト内に不足している、または無効のパラメーターがあります。
400	BAD_REQUEST	リクエスト項目の数が上限を超えています。
401	UNAUTHENTICATED	アクセストークンがないか、期限切れか、無効です。
403	FORBIDDEN	操作を実行する権限がユーザーにありません。
404	ENABLEMENT_NOT_FOUND	リクエストされた有効化が見つかりませんでした。
404	SKILL_STAGE_NOT_FOUND	リクエストされたスキルIDとステージの組み合わせが見つかりませんでした。
429	TOO_MANY_REQUESTS	リクエストが制限されています。
500	INTERNAL_SERVER_ERROR	内部サービスエラーのためリクエストを処理できませんでした。
503	SERVICE_UNAVAILABLE	サーバーが一時的に使用できません。

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

単一のリクエストで複数のユニットに対するスキル有効化を取得するには、POST /v1/skills/enablements/batchGetを呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

POST /v1/skills/enablements/batchGet HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

リクエストのパスパラメーター

リクエストのパスにはパラメーターはありません。

リクエスト本文の例

以下の例は、4つのユニットに対するスキル有効化を取得するリクエスト本文の例です。

{
  "paginationContext": {
      "maxResults" : 5,
      "nextToken": "paginationTokenString"
  },
  "items": [
    {
      "itemId": 0,
      "unitId": "amzn1.alexa.unit.unitId1"
    },
    {
      "itemId": 1,
      "unitId": "amzn1.alexa.unit.unitId2"
    },
    {
      "itemId": 2,
      "unitId": "amzn1.alexa.unit.unitId3"
    },
    {
      "itemId": 3,
      "unitId": "amzn1.alexa.unit.unitId4"
    },
  ]
}

リクエスト本文のパラメーター

フィールド	説明	型	必須
`paginationContext`	ページ分割が必要なデータを含むコンテキスト。	オブジェクト	✕
`paginationContext.maxResults`	表示する結果の最大数。値は1～10の間で指定します。デフォルトは10です。	整数	✕
`paginationContext.nextToken`	スキル有効化のリストを取得する前回の応答で、応答オブジェクトに返された継続トークン。詳細については、クエリ結果のページ分割を処理するを参照してください。	文字列	✕
`items`	リクエスト項目のリスト。各項目が1つのユニットを表します。	配列	◯
`items[*].itemId`	リクエスト項目の一意のIDです。リクエスト内で一意である必要があります。	整数	◯
`items[*].unitId`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列	◯

成功応答

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

応答本文の例

{
    "paginationContext": {
           "nextToken": "paginationTokenString"
     },
    "results": [
        {
            "itemId": 0,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLED"
                },
                {
                    "skill": {
                        "stage": "development",
                        "id": "amzn1.ask.skill.skillId2"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED"
                }
            ]
        },
        {
            "itemId": 1,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLING"
                },
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId2"
                    },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED"
                }
            ]
        },
        {
            "itemId": 3,
            "enablements": [
            ]
        }
    ],
    "errors": [  
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]    
}

応答本文のパラメーター

フィールド	説明	型
`paginationContext`	ページ分割が必要なデータを含むコンテキスト。	オブジェクト
`paginationContext.nextToken`	後続データを取得するために使用するトークン。もうレコードがない場合、このトークンは存在しません。	文字列
`results`	スキル有効化のリスト。	リスト（セット）
`results[*].itemId`	リクエスト項目の一意のID。リクエストで指定されている値です。	整数
`results[*].enablements`	スキル有効化のリスト。	リスト（セット）
`results[].enablements[].skill`	スキルステージとID。	オブジェクト
`results[].enablements[].skill.stage`	スキルステージは`development`、`certification`、`live`のいずれかになります。	列挙
`results[].enablements[].skill.id`	スキルの一意のIDです。	文字列
`results[].enablements[].unit`	ユニットの一意のID。	文字列
`results[].enablements[].unit.id`	ユニットID。形式は`"amzn1.alexa.unit.did.{id}"`。	文字列
`results[].enablements[].accountLink`	ユーザーのAmazonアカウントと開発者サービスのアカウントを接続するアカウントリンクの現在のステータスです。	オブジェクト
`results[].enablements[].accountLink.status`	アカウントリンクのステータス： `LINKED`または`NOT LINKED`です。アカウントリンクをサポートしないスキルの場合、`NOT_LINKED`が返されます。	文字列
`results[].enablements[].status`	スキルの有効化ステータス： `ENABLING`または`ENABLED`。	列挙

エラー応答のヘッダー

HTTP/1.1 {ErrorCode}
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

エラー応答本文の例

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

{
    "errors": [
        {
            "itemId": 0,
            "status": 401,
            "errorCode": "UNAUTHENTICATED",
            "errorDescription": "The access token is invalid."
        }
    ]
}

エラー応答のパラメーター

フィールド	説明	型
`errors`	エラー応答のリスト。それぞれが各リクエスト項目に対応しています。	配列
`errors[*].itemId`	リクエスト項目のID。個々の項目ではなくリクエスト全体に対するエラー応答である場合は任意です。	文字列
`errors[*].status`	リクエストまたはリクエスト項目ごとの応答ステータスコード。	整数
`errors[*].errorCode`	エラーのエラーコード。	列挙
`errors[*].errorDescription`	エラーの説明です。	文字列

HTTP応答コード

ステータスコード	名前	説明
200	Accepted	リクエストは受け付けられました。リクエストが成功した場合（一部のみの成功であっても）、各ユニットの有効化リストを含む応答本文で200ステータスコードが返されます。有効化レコードがないユニットがあれば、関連付けられている`itemId`が空の配列になります。
400	INVALID_PARAM	リクエスト内に不足している、または無効のパラメーターがあります。
400	BAD_REQUEST	リクエスト項目の数が上限を超えています。
401	UNAUTHENTICATED	アクセストークンがないか、期限切れか、無効です。
403	FORBIDDEN	操作を実行する権限がユーザーにありません。
429	TOO_MANY_REQUESTS	リクエストが制限されています。
500	INTERNAL_SERVER_ERROR	内部サービスエラーのためリクエストを処理できませんでした。
503	SERVICE_UNAVAILABLE	サーバーが一時的に使用できません。

最終更新日: 2023 年 03 月 06 日