スキル管理API


スキル管理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

米国

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

米国、カナダ

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

米国

リクエストの形式

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}"です。

文字列

成功応答ヘッダー

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

スキルのステージです。developmentcertificationliveのいずれかです。

列挙

skill.id

スキルの一意のIDです。

文字列

unit.id

ユニットIDです。形式は"amzn1.alexa.unit.did.{id}"です。

文字列

accountLink.status

ユーザーのAmazonアカウントとサービスのアカウントを接続するアカウントリンクの現在のステータスです。 LINKEDNOT_LINKEDのどちらかです。アカウントリンクをサポートしないスキルでは、NOT_LINKEDが返されます。

文字列

status

スキル有効化のステータスです。 ENABLINGENABLEDのどちらかです。

列挙

エラー応答

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トークン}

リクエスト本文

ありません。

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

フィールド 説明 必須

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

スキルのステージです。developmentcertificationliveのいずれかです。

列挙

skill.id

スキルの一意のIDです。

文字列

unit.id

ユニットIDです。形式は"amzn1.alexa.unit.did.{id}"です。

文字列

accountLink.status

ユーザーのAmazonアカウントとサービスのアカウントを接続するアカウントリンクの現在のステータスです。 LINKEDNOT_LINKEDのどちらかです。アカウントリンクをサポートしないスキルでは、NOT_LINKEDが返されます。

文字列

status

スキル有効化のステータスです。 ENABLINGENABLEDのどちらかです。

列挙

エラー応答

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

米国

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

米国、カナダ

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

米国

リクエストの形式

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

スキルのステージです。developmentliveのどちらかです。

列挙

partitionName

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

文字列

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

スキルのステージです。developmentliveのどちらかです。

列挙

skill.id

スキルの一意のIDです。形式は"amzn1.ask.skill.{id}"です。

文字列

unit.id

ユニットIDです。形式は"amzn1.alexa.unit.did.{id}"です。

文字列

accountLink.status

ユーザーのAmazonアカウントとサービスのアカウントを接続するアカウントリンクの現在のステータスです。 LINKEDNOT_LINKEDのどちらかです。accountLinkオブジェクトは、アカウントリンクをサポートするスキルにのみ存在します。

文字列

status

スキル有効化のステータスです。 ENABLINGENABLEDのどちらかです。

列挙

エラー応答

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トークン}

リクエスト本文

ありません。

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

フィールド 説明 必須

unitId

ユニットIDです。形式は"amzn1.alexa.unit.did.{id}"です。

文字列

skillId

スキルIDです。形式は"amzn1.alexa.skill.{id}"です。

文字列

stage

スキルのステージです。developmentcertificationliveのいずれかです。指定する場合、ステージが有効になっている必要があります。

列挙

成功応答ヘッダー

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トークン}

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

フィールド 説明 必須

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

スキルのステージです。developmentcertificationliveのいずれかです。

列挙

partitionName

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

文字列

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

エラー応答のリストです。それぞれが1つのリクエスト項目に対応します。

配列

itemId

リクエスト項目のIDです。個々の項目ではなくリクエスト全体に対するエラー応答の場合はオプションです。

文字列

status

リクエストまたはリクエスト項目ごとの応答ステータスコードです。

整数

errorCode

エラーのエラーコードです。

列挙

errorDescription

エラーの説明です。

文字列

HTTP応答コード

ステータスコード 名前 説明

202

Accepted

リクエストが受け付けられました。

400

Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。たとえば、次のような理由が考えられます。
  • skillIdがないか、無効です。
  • unitIdがないか、無効です。
  • リクエストされたskillIdstageの組み合わせが見つかりませんでした。
  • リクエスト項目の数が上限を超えています。

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トークン}

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

フィールド 説明 必須

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

スキルのステージです。developmentcertificationliveのいずれかです。指定すると、そのスキルステージが無効になります。

列挙

成功応答

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

米国

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

米国、カナダ

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

米国

リクエストの形式

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}"です。

文字列

成功応答

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

スキルのステージです。developmentcertificationliveのいずれかです。

列挙

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

アカウントリンクのステータスです。 LINKEDNOT_LINKEDのどちらかです。アカウントリンクをサポートしないスキルでは、NOT_LINKEDが返されます。

文字列

results[*].enablements[*].status

スキル有効化のステータスです。 ENABLINGENABLEDのどちらかです。

列挙

エラー応答ヘッダー

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 日