スキル管理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で開発を始めるを参照してください。

ルームなどのAlexa Smart Properties for Hospitalityユニットのスキルを管理するには、スキル管理APIを使用します。

APIエンドポイント

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

認証

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

操作

スキル管理APIには、以下の操作が用意されています。

説明	HTTPメソッドとパス
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つのユニットの特定のスキルに対するスキル有効化レコードを取得するには、GET /v1/skills/{skillId}/enablements?unitId={unitId}を呼び出します。

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

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

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

リクエスト本文

ありません。

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

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

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

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

成功応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

リクエスト本文

ありません。

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

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

成功応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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つのユニットでスキルを有効にするには、POST /v1/skills/{skillId}/enablementsを呼び出します。

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

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

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

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

フィールド	説明	型	必須
`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`のみです。	文字列	◯

成功応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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`	スキルの一意の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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

リクエスト本文

ありません。

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

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

成功応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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
米国	米国、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

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

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

リクエスト本文の例

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

{
    "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つのパーティション名を含む文字列か、複数のパーティション名を含むカンマ区切りリストを指定します。たとえば、「Room101」や「Room101, Room202」は、このパラメーターの値として有効です。一方、「」（空のリスト）、「Room101, ,Room202」（カンマ区切りが正しくない）、「Room 101」（空白を含む）は有効な値ではありません。注：特定の`skillId`と`unitId`に既存の有効化がある場合、同じ`skillId`と`unitId`に対して異なる`partitionName`値（新規、更新、指定なし）を使用して再び`POST`有効化リクエストを実行すると、既存の有効化が最新の`partitionName`値で更新されます。	文字列	✕
`accountLinkRequest`	アカウントリンクのリクエスト情報です。AccountLinkRequestオブジェクトとして指定します。	オブジェクト	◯（アカウントリンクをサポートするスキルの場合）

成功応答

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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`	エラー応答のリストです。それぞれが1つのリクエスト項目に対応します。	配列	◯
`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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

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

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

リクエスト本文の例

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

{
  "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`のいずれかです。指定すると、そのスキルステージが無効になります。	列挙	✕

成功応答

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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`	エラー応答のリストです。それぞれが1つのリクエスト項目に対応します。	配列
`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	サーバーが一時的に使用できません。

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

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

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

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

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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

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

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

リクエスト本文の例

以下は、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}"`です。	文字列	◯

成功応答

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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`	エラー応答のリストです。それぞれが1つのリクエスト項目に対応します。	配列
`errors[*].itemId`	リクエスト項目のIDです。個々の項目ではなくリクエスト全体に対するエラー応答の場合はオプションです。	文字列
`errors[*].status`	リクエストまたはリクエスト項目ごとの応答ステータスコードです。	整数
`errors[*].errorCode`	エラーのエラーコードです。	列挙
`errors[*].errorDescription`	エラーの説明です。	文字列

HTTP応答コード

ステータスコード	名前	説明
200	Accepted	リクエストが受け付けられました。リクエストが（一部だけでも）成功すると、APIは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 月 16 日