スキル管理API


スキル管理API

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

APIエンドポイント

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを以下のいずれかに設定してください。

エンドポイント

カナダ、米国

https://api.amazonalexa.com

ドイツ、スペイン、フランス、イタリア、英国

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

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

操作

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

説明 HTTPメソッドとパス

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

GET /v1/skills/{skillId}/enablements?unitId={unitId}

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

GET /v1/skills/enablements?unitId={unitId}

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

POST /v1/skills/enablements/batchGet

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

スキル有効化を取得する

以下の操作では、1つまたは複数のユニットで有効化されているスキルに関する情報を取得できます。

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

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式の例

スキル有効化とアカウントリンクの詳細のみのリストを取得する

以下の例では、ユニットのスキル有効化レコードのリストを取得します。デフォルトでは、結果に無指名対話の詳細は含まれません。

この呼び出しでは、特定のスキルの有効化レコードのみが返されます。1つのユニットのすべてのスキル有効化を取得するには、1つのユニットのスキル有効化リストを取得するを参照してください。

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

無指名対話の詳細を含める

以下の例では、expand=nameFreeInvocationパラメーターを使用して、スキル有効化に無指名対話の詳細を含める方法を示しています。

GET /v1/skills/{skillId}/enablements?unitId={unitId}&expand=nameFreeInvocation HTTP/1.1

リクエスト本文

なし。

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

フィールド 説明 必須

skillId

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

文字列

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

フィールド 説明 必須

unitId

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

文字列

expand

応答に含めるアトリビュート(またはアトリビュートのセット)。現在サポートされている値は、nameFreeInvocationです。

文字列

成功応答のヘッダー

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

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

列挙

skill.id

スキルの一意のID。

文字列

unit.id

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

文字列

accountLink.status

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

文字列

status

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

列挙

nameFreeInvocation.status

無指名対話の有効化ステータス。 DISABLEDENABLEDのどちらかです。無指名対話をサポートしないスキルでは、DISABLEDが返されます。

列挙

nameFreeInvocation.locales

ユニットでの無指名対話を利用可能なロケール。値は、en-USes-USen-CAfr-CAen-GBfr-FRes-ESit-ITde-DEです。この値は、nameFreeInvocation.statusENABLEDの場合にのみ返されます。ロケールは5つまでに限られます。

配列

エラー応答

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

内部サービスエラーのためリクエストを処理できませんでした。

500

Internal Server Error

NameFreeInvocationの取得中に内部サービスエラーが発生したため、リクエストを処理できませんでした。

503

Service Unavailable

サーバーが一時的に使用できません。

503

Service Unavailable

サーバーで一時的にNameFreeInvocationを取得できません。

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

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式の例

スキル有効化とアカウントリンクの詳細のみのリストを取得する

以下の例では、1つのユニットに対するすべてのスキル有効化レコードのリストを取得します。デフォルトでは、結果に無指名対話の詳細は含まれません。

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

無指名対話の詳細を含める

以下の例では、expand=nameFreeInvocationパラメーターを使用して、各スキル有効化レコードに無指名対話の詳細を含める方法を示しています。

/v1/skills/enablements?unitId={unitId}&maxResults={maxResults}&expand=nameFreeInvocation&nextToken={nextToken} HTTP/1.1

リクエスト本文

なし。

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

フィールド 説明 必須

unitId

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

文字列

nextToken

前回のスキル有効化リストの取得に対する応答で、応答オブジェクトに返された継続トークン。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

maxResults

表示する結果の最大数。値は1~10の間で指定します。デフォルトは10です。

整数

expand

応答に含めるアトリビュート(またはアトリビュートのセット)。現在サポートされている値は、nameFreeInvocationです。

文字列

成功応答のヘッダー

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文のパラメーター

フィールド 説明

paginationContext

ページ分割を制御するために必要なすべてのデータを含むコンテキスト。

オブジェクト

paginationContext.nextToken

後続データを取得するために使用するトークン。これ以上レコードがない場合、このトークンは存在しません。

文字列

items

スキル有効化のリスト。

リスト(セット)

skill.stage

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

列挙

skill.id

スキルの一意のID。

文字列

unit.id

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

文字列

accountLink.status

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

文字列

status

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

列挙

nameFreeInvocation.status

無指名対話の有効化ステータス。 DISABLEDENABLEDのどちらかです。無指名対話をサポートしないスキルでは、DISABLEDが返されます。

列挙

nameFreeInvocation.locales

ユニットでの無指名対話を利用可能なロケール。値は、en-USes-USen-CAfr-CAen-GBfr-FRes-ESit-ITde-DEです。この値は、nameFreeInvocation.statusENABLEDの場合にのみ返されます。ロケールは5つまでに限られます。

配列

エラー応答

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

内部サービスエラーのためリクエストを処理できませんでした。

500

Internal Server Error

NameFreeInvocationの取得中に内部サービスエラーが発生したため、リクエストを処理できませんでした。

503

Service Unavailable

サーバーが一時的に使用できません。

503

Service Unavailable

サーバーで一時的にNameFreeInvocationを取得できません。

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

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式の例

スキル有効化とアカウントリンクの詳細のみのリストを取得する

以下の例では、複数のユニットにまたがる1つのスキルについて、すべてのスキル有効化レコードのリストを取得します。デフォルトでは、結果に無指名対話の詳細は含まれません。

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

無指名対話の詳細を含める

以下の例では、expand=nameFreeInvocationパラメーターを使用して、各スキル有効化レコードに無指名対話の詳細を含める方法を示しています。

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

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

リクエスト本文の例

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

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

フィールド 説明 必須

paginationContext

ページ分割を制御するために必要なすべてのデータを含むコンテキスト。

オブジェクト

paginationContext.maxResults

表示する結果の最大数。値は1~10の間で指定します。デフォルトは10です。

整数

paginationContext.nextToken

前回のスキル有効化リストの取得に対する応答で、応答オブジェクトに返された継続トークン。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

items

リクエスト項目のリスト。各項目は1つのユニットを表します。

配列

items[*].itemId

リクエスト項目の一意のID。リクエスト内で一意である必要があります。

整数

items[*].unitId

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

文字列

expand

応答に含めるアトリビュート(またはアトリビュートのセット)。現在サポートされている値は、nameFreeInvocationです。

配列

成功応答

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

応答本文のパラメーター

フィールド 説明

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のどちらかです。

列挙

results[*].enablements[*].nameFreeInvocation.status

無指名対話の有効化ステータス。 DISABLEDENABLEDのどちらかです。無指名対話をサポートしないスキルでは、DISABLEDが返されます。

列挙

results[*].enablements[*].nameFreeInvocation.locales

ユニットでの無指名対話を利用可能なロケール。値は、en-USes-USen-CAfr-CAen-GBfr-FRes-ESit-ITde-DEです。この値は、nameFreeInvocation.statusENABLEDの場合にのみ返されます。ロケールは5つまでに限られます。

配列

エラー応答ヘッダー

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

内部サービスエラーのためリクエストを処理できませんでした。

500

Internal Server Error

NameFreeInvocationの取得中に内部サービスエラーが発生したため、リクエストを処理できませんでした。

503

Service Unavailable

サーバーが一時的に使用できません。

503

Service Unavailable

サーバーで一時的にNameFreeInvocationを取得できません。

スキルを有効にする

以下の操作では、1つまたは複数のユニットでスキルを有効にすることができます。

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

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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}"形式で表します。

文字列

リクエスト本文の例

アカウントリンクや無指名対話なしでスキルを有効にする

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

リクエスト本文の例
{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live"
}
アカウントリンクありでスキルを有効にする

以下の例は、パーティションを使用したアカウントリンクありでの1つのユニットに対するスキルの有効化を示しています。

リクエスト本文の例
{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "partitionName": "Room101-Kitchenette",
  "accountLinkRequest": {
    "redirectUri": "https://example.com",
    "authCode": "3pauthcode",
    "type": "AUTH_CODE"
  }
}
無指名対話ありでスキルを有効にする

以下の例は、無指名対話ありでの1つのユニットに対するスキルの有効化を示しています。

リクエスト本文の例
{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "nameFreeInvocationRequest": {
      "locales" : ["en-US"]
  }
}

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

フィールド 説明 必須

unitId

ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。

文字列

stage

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

列挙

partitionName

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

文字列

accountLinkRequest

アカウントリンクのリクエスト情報。AccountLinkRequestオブジェクトとして指定します。

オブジェクト

◯(アカウントリンクが必要なスキルの場合)

nameFreeInvocationRequest

無指名対話のリクエスト情報。NameFreeInvocationRequestオブジェクトとして指定します。

オブジェクト

✕(無指名対話をサポートしているスキルでのみ使用可能)

フィールド 説明 必須

redirectUri

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

文字列

authCode

OAuth 2.0認可コード。この値は、アカウントリンクを実行するために必要です。詳細については、Authorization Code Grantフローの概要を参照してください。

文字列

type

OAuth 2.0認可リクエストプロトコルに基づくアカウントリンクリクエストのタイプ。現時点でサポートされる値は、AUTH_CODEのみです。

文字列

NameFreeInvocationRequestオブジェクトスキーマ

フィールド 説明 必須

locales

無指名対話を有効にするユニットのロケール。スキルには、ロケールをサポートする対話モデルが必要です。サポートされる値は、en-USes-USen-CAfr-CAen-GBfr-FRit-ITde-DEes-ESです。ロケールは5つまでに限られます。

文字列

成功応答のヘッダー

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"
  },
  "nameFreeInvocation": {
    "status": "ENABLED",
    "locales": ["ja-JP"]
  },
  "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のどちらかです。

列挙

nameFreeInvocation.status

無指名対話の有効化ステータス。 DISABLEDENABLEDのどちらかです。無指名対話をサポートしないスキルでは、DISABLEDが返されます。

列挙

nameFreeInvocation.locales

ユニットでの無指名対話を利用可能なロケール。値は、en-USes-USen-CAfr-CAen-GBfr-FRes-ESit-ITde-DEです。この値は、nameFreeInvocation.statusENABLEDの場合にのみ返されます。ロケールは5つまでに限られます。

配列

エラー応答

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

内部サービスエラーのためリクエストを処理できませんでした。

500

Internal Server Error

NameFreeInvocationの取得中に内部サービスエラーが発生したため、リクエストを処理できませんでした。

503

Service Unavailable

サーバーが一時的に使用できません。

503

Service Unavailable

サーバーで一時的にNameFreeInvocationを取得できません。

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

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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}"形式で表します。

文字列

リクエスト本文の例

アカウントリンクや無指名対話なしでスキルを有効にする

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

リクエスト本文の例
{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live"
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live"
        }
    ]
}
アカウントリンクありでスキルを有効にする

以下の例は、パーティションを使用したアカウントリンクありでの複数のユニットに対するスキルの有効化を示しています。

リクエスト本文の例
{
    "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": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live",
            "nameFreeInvocationRequest": {
                "locales" : ["en-CA"]
            }
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live",
            "nameFreeInvocationRequest": {
                "locales" : ["en-CA","fr-CA"]
            }
        }
    ]
}

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

フィールド 説明 必須

items

リクエスト項目のリスト。各項目は、1つのユニットに対する有効化リクエストを表します。

配列

itemId

リクエスト項目の一意のID。リクエスト内で一意である必要があります。

整数

unitId

ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。

文字列

stage

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

列挙

partitionName

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

文字列

accountLinkRequest

アカウントリンクのリクエスト情報。AccountLinkRequestオブジェクトとして指定します。

オブジェクト

◯(アカウントリンクが必要なスキルの場合)

nameFreeInvocationRequest

無指名対話のリクエスト情報。NameFreeInvocationRequestオブジェクトとして指定します。

オブジェクト

✕(無指名対話をサポートしているスキルでのみ使用可能)

成功応答

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

内部サービスエラーのためリクエストを処理できませんでした。

500

Internal Server Error

NameFreeInvocationの取得中に内部サービスエラーが発生したため、リクエストを処理できませんでした。

503

Service Unavailable

サーバーが一時的に使用できません。

503

Service Unavailable

サーバーで一時的にNameFreeInvocationを取得できません。

スキルを無効にする

以下の操作では、1つまたは複数のユニットでスキルを無効にすることができます。

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

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

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

列挙

成功応答のヘッダー

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/batchDeleteを呼び出します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

スキルのステージ。developmentliveのどちらかです。指定すると、そのスキルステージが無効になります。

列挙

成功応答

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

サーバーが一時的に使用できません。


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

最終更新日: 2024 年 03 月 21 日