スキル管理API

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

スキル管理API

注：このAPIは、登録済みのAlexa Smart Propertiesパートナーのみが使用できます。Alexa Smart Properties 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パラメーターを使用して、スキル有効化に無指名対話の詳細を含める方法を示しています。

注：この機能は、Alexa Smart Propertiesの施設用スキルでのみ使用できます。Alexa Smart Propertiesスキルに無指名対話を追加するを参照してください。

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`です。	文字列	✕

成功応答のヘッダー

注：応答ヘッダーで返される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`	スキルのステージ。`development`、`live`のどちらかです。	列挙
`skill.id`	スキルの一意のID。	文字列
`unit.id`	ユニットID。`"amzn1.alexa.unit.did.{id}"`形式で表します。	文字列
`accountLink.status`	ユーザーのAmazonアカウントとサービスのアカウントを接続するアカウントリンクの現在のステータス。 `LINKED`、`NOT_LINKED`のどちらかです。アカウントリンクをサポートしないスキルでは、`NOT_LINKED`が返されます。	文字列
`status`	スキルの有効化ステータス。 `ENABLING`、`ENABLED`のどちらかです。	列挙
`nameFreeInvocation.status`	無指名対話の有効化ステータス。 `DISABLED`、`ENABLED`のどちらかです。無指名対話をサポートしないスキルでは、`DISABLED`が返されます。	列挙
`nameFreeInvocation.locales`	ユニットでの無指名対話を利用可能なロケール。値は、`en-US`、`es-US`、`en-CA`、`fr-CA`、`en-GB`、`fr-FR`、`es-ES`、`it-IT`、`de-DE`です。この値は、`nameFreeInvocation.status`が`ENABLED`の場合にのみ返されます。ロケールは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つのユニットに対するすべてのスキル有効化レコードのリストを取得します。デフォルトでは、結果に無指名対話の詳細は含まれません。

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パラメーターを使用して、各スキル有効化レコードに無指名対話の詳細を含める方法を示しています。

注：この機能は、Alexa Smart Propertiesの施設用スキルでのみ使用できます。Alexa Smart Propertiesスキルに無指名対話を追加するを参照してください。

/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`です。	文字列	✕

成功応答のヘッダー

注：応答ヘッダーで返される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`	ページ分割を制御するために必要なすべてのデータを含むコンテキスト。	オブジェクト
`paginationContext.nextToken`	後続データを取得するために使用するトークン。これ以上レコードがない場合、このトークンは存在しません。	文字列
`items`	スキル有効化のリスト。	リスト（セット）
`skill.stage`	スキルのステージ。`development`、`live`のどちらかです。	列挙
`skill.id`	スキルの一意のID。	文字列
`unit.id`	ユニットID。`"amzn1.alexa.unit.did.{id}"`形式で表します。	文字列
`accountLink.status`	ユーザーのAmazonアカウントとサービスのアカウントを接続するアカウントリンクの現在のステータス。 `LINKED`、`NOT_LINKED`のどちらかです。アカウントリンクをサポートしないスキルでは、`NOT_LINKED`が返されます。	文字列
`status`	スキルの有効化ステータス。 `ENABLING`、`ENABLED`のどちらかです。	列挙
`nameFreeInvocation.status`	無指名対話の有効化ステータス。 `DISABLED`、`ENABLED`のどちらかです。無指名対話をサポートしないスキルでは、`DISABLED`が返されます。	列挙
`nameFreeInvocation.locales`	ユニットでの無指名対話を利用可能なロケール。値は、`en-US`、`es-US`、`en-CA`、`fr-CA`、`en-GB`、`fr-FR`、`es-ES`、`it-IT`、`de-DE`です。この値は、`nameFreeInvocation.status`が`ENABLED`の場合にのみ返されます。ロケールは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つのスキルについて、すべてのスキル有効化レコードのリストを取得します。デフォルトでは、結果に無指名対話の詳細は含まれません。

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

{
    "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"
        }
    ]    
}

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

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

注：この機能は、Alexa Smart Propertiesの施設用スキルでのみ使用できます。Alexa Smart Propertiesスキルに無指名対話を追加するを参照してください。

{
    "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",
                    "nameFreeInvocation": {
                        "status": "ENABLED",
                        "locales": ["ja-JP"]
                    }
                },
                {
                    "skill": {
                        "stage": "development",
                        "id": "amzn1.ask.skill.skillId2"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED",
                    "nameFreeInvocation": {
                        "status": "ENABLED",
                        "locales": ["ja-JP"]
                    }
                }
            ]
        },
        {
            "itemId": 1,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLING",
                    "nameFreeInvocation": {
                        "status": "DISABLED"
                    }
                },
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId2"
                    },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED",
                    "nameFreeInvocation": {
                        "status": "ENABLED",
                        "locales": ["ja-JP"]
                    }
                }
            ]
        },
        {
            "itemId": 3,
            "enablements": [
            ]
        }
    ],
    "errors": [  
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]    
}

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

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

リクエスト本文の例

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

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

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

成功応答

注：応答ヘッダーで返される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`のどちらかです。	列挙
`results[].enablements[].nameFreeInvocation.status`	無指名対話の有効化ステータス。 `DISABLED`、`ENABLED`のどちらかです。無指名対話をサポートしないスキルでは、`DISABLED`が返されます。	列挙
`results[].enablements[].nameFreeInvocation.locales`	ユニットでの無指名対話を利用可能なロケール。値は、`en-US`、`es-US`、`en-CA`、`fr-CA`、`en-GB`、`fr-FR`、`es-ES`、`it-IT`、`de-DE`です。この値は、`nameFreeInvocation.status`が`ENABLED`の場合にのみ返されます。ロケールは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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国

リクエストの形式

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つのユニットに対するスキルの有効化を示しています。

注：この機能は、Alexa Smart Propertiesの施設用スキルでのみ使用できます。Alexa Smart Propertiesスキルに無指名対話を追加するを参照してください。

リクエスト本文の例

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "nameFreeInvocationRequest": {
      "locales" : ["en-US"]
  }
}

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

フィールド	説明	型	必須
`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オブジェクトとして指定します。	オブジェクト	◯（アカウントリンクが必要なスキルの場合）
`nameFreeInvocationRequest`	無指名対話のリクエスト情報。NameFreeInvocationRequestオブジェクトとして指定します。	オブジェクト	✕（無指名対話をサポートしているスキルでのみ使用可能）

AccountLinkRequestオブジェクトスキーマ

フィールド	説明	型	必須
`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-US`、`es-US`、`en-CA`、`fr-CA`、`en-GB`、`fr-FR`、`it-IT`、`de-DE`、`es-ES`です。ロケールは5つまでに限られます。	文字列	◯

成功応答のヘッダー

注：応答ヘッダーで返される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"
  },
  "nameFreeInvocation": {
    "status": "ENABLED",
    "locales": ["ja-JP"]
  },
  "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`のどちらかです。	列挙
`nameFreeInvocation.status`	無指名対話の有効化ステータス。 `DISABLED`、`ENABLED`のどちらかです。無指名対話をサポートしないスキルでは、`DISABLED`が返されます。	列挙
`nameFreeInvocation.locales`	ユニットでの無指名対話を利用可能なロケール。値は、`en-US`、`es-US`、`en-CA`、`fr-CA`、`en-GB`、`fr-FR`、`es-ES`、`it-IT`、`de-DE`です。この値は、`nameFreeInvocation.status`が`ENABLED`の場合にのみ返されます。ロケールは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
米国	米国、カナダ、イタリア、ドイツ、スペイン、日本	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国

リクエストの形式

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" // オプション
        }
    ]
}

無指名対話ありでスキルを有効にする

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

注：この機能は、Alexa Smart Propertiesの施設用スキルでのみ使用できます。Alexa Smart Propertiesスキルに無指名対話を追加するを参照してください。

リクエスト本文の例

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

成功応答

注：応答ヘッダーで返される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	内部サービスエラーのためリクエストを処理できませんでした。
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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国

リクエストの形式

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

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

Healthcare	Hospitality	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`、`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	サーバーが一時的に使用できません。

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

フィードバックを送信

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