スキルパッケージAPIリファレンス
スキルパッケージAPIは、コンポーネントごとではなく、1つのパッケージとしてスキルと対話するために使用できます。
- スキルパッケージ
eTag
を使用してスキルパッケージの上書きを防止する- APIのエンドポイントと認可
- 新しいアップロードURLを作成する
- 新しいスキルパッケージを作成する
- 既存のスキル用にパッケージをインポートする
- 指定したimportIdのステータスを取得する
- 既存のスキルのエクスポートリクエストを作成する
- エクスポートリクエストのステータスを取得する
スキルパッケージ
スキルパッケージは1つ以上のコンポーネントで構成されます。
- マニフェスト - スキルマニフェストには、表示名、スキルの機能(ビデオ、スマートホーム、カスタム)、スキルサービスコードのエンドポイント(AWS Lambdaまたは別のウェブエンドポイント)などの、スキルに関するメタデータとコンフィギュレーションが含まれます。スキルマニフェストファイルの名前は、skill.jsonです。スキルにはそれぞれマニフェストが必要です。
スキルパッケージの以下のコンポーネントはオプションです。
- 画像アセット - これらの画像はスキルに関連付けられ、Alexaスキルストアまたはスキル内商品でアイコンとして表示されます。
- スキル内商品 - ユーザーがスキル内で購入できるスキル内商品を定義します。購入のタイプや価格などの詳細を指定します。
- 対話モデル - スキルの音声ユーザーインターフェースを定義します。呼び出し名、インテント、スロットなどが含まれます。対話モデルを含むのはカスタムスキルのみであり、スキルがサポートするロケールごとに1つのモデルが存在します。対話モデルの名前は<locale>.jsonの形式で記述します(ja-JP.jsonなど)。スキルパッケージ形式では、対話モデルはcustomという名前のフォルダに存在している必要があり、このフォルダ自体もinteractionModelsという名前のフォルダに存在している必要があります。
スキルにはアカウントリンク情報が含まれる場合もありますが、スキルパッケージAPIでは現在これをサポートしていません。スキルパッケージAPIを使うことはできますが、アカウントリンクを管理するにはSMAPIも使用する必要があります。
Alexa Skills Kit開発者コンソールだけを使用してスキルと対話する場合でも、これらのコンポーネントはバックグラウンドで存在しています。Alexa Skills Kitコマンドラインインターフェース(ASK CLI)またはスキル管理API(SMAPI)を使用してスキルと対話する場合、これらのコンポーネントは個別のファイルとして表示されます。スキルパッケージは、これらのコンポーネントを1つのファイルにまとめて、1つのユニットとして操作できるようにします。
スキルパッケージの形式
スキルパッケージファイルは、スキルコンポーネントをすべてまとめて.zip拡張子の付いたファイルに圧縮します。スキルパッケージのコンポーネントは次のように整理されます。
SkillPackageName.zip
├── assets
│ └── images
│ ├── ja-JP_largeIcon.png
│ ├── ja-JP_smallIcon.png
│ ├── isp1
│ │ ├── ja-JP_largeIcon.png
│ │ └── ja-JP_smallIcon.png
│ └── isp2
│ ├── ja-JP_largeIcon.png
│ └── ja-JP_smallIcon.png
├── interactionModels
│ └── custom
│ └── ja-JP.json
├── isps
│ ├── isps.json
│ ├── isp1.json
│ └── exampleDirectory
│ └── isp2.json
└── skill.json
スキルパッケージの形式を使用して、スキルを作成およびインポートするには:
- スキルコンポーネントを前の図のように配置し、最上位フォルダをzip形式で圧縮します。
注: スキルパッケージをインターネット上のパブリックにアクセス可能なURLにアップロードすることで、必要に応じて、次の2つの手順をスキップすることができます。
- アップロードURLを作成します。
- 前の手順で作成したURLを使用して、.zipファイルをAmazon S3にアップロードします。
- スキルパッケージをS3または独自のURLにアップロードすると、以下の処理ができるようになります。
既存のスキルをスキルパッケージ形式でエクスポートし、ローカルで編集した後、前の手順に従ってアップロードしてインポートすることで、既存のスキルを更新することもできます。
スキルパッケージでスキル内商品を管理する
スキルパッケージに含めることで、スキル内商品(ISP)を管理できます。ISPをスキルパッケージに含める場合、isps.jsonという名前のファイルが保存されたispsという名前のフォルダを含める必要があります。前のセクションを参照してください。このファイルには、次の例に示すように、作成または更新するISPに関する情報と、そのスキルに関連付けられた(リンクされた)ISPが含まれています。
{
"isps": {
"Unique ISP Name 1": {
"path": "file://isps/isp1.json"
},
"Unique ISP Name 2": {
"path": "file://isps/exampleDirectory/isp2.json"
}
},
"associations": [
"amzn1.adg.UUID3",
"amzn1.adg.UUID4"
]
}
次のリストでは、isps.jsonファイルの各オブジェクトについて説明します。
isps
- 1つまたは複数のISPを含んでいます。それぞれ開発者が指定した一意の名前が付けられています。各ISPには、skill.jsonから相対的にISPスキーマファイルの場所を指定する
path
が含まれます(skill.jsonをパッケージのルートと考えることができます)。各ISPのpath
値を使用して編成を指定することで、任意のディレクトリ構造でISPのファイルを整理できます。 -
警告: ISPの一意の名前を作成した後、isps.jsonファイル内で名前を変更しないでください。変更した場合、スキルパッケージAPIによって、新しい名前で新しいISPが作成され、以前のISPは使われなくなります。
associations
- ISPの一意の識別子である商品IDのリストが含まれています。リスト内の各商品IDは、スキルに関連付けられた(リンクされた)ISPを表します。ISPの商品IDを取得するには、スキル内商品管理APIまたは開発者コンソールを使用します。
既存のスキルにインポートするスキルパッケージに、ISPを含める場合、isps.json内のisps
とassociations
が、スキルパッケージAPIの動作を決定します。
- isps.jsonに新しい
isps
またはassociations
が含まれている場合、スキルパッケージAPIは適宜ISPを作成するか、または関連付けます。 - isps.jsonに、以前にスキルパッケージに存在していた
isps
に対する更新が含まれている場合、スキルパッケージAPIはそれに応じてISPを更新します。 - isps.jsonで、以前にスキルパッケージに存在していた
associations
が省略されている場合、スキルパッケージAPIはそれに応じてISPの関連付けを解除します。スキルパッケージAPIはISPを削除しません。
スキルパッケージAPIを使用してこれらのアクションを実行しない場合は、スキルパッケージからispsフォルダを省略し、引き続き個別にISPを管理することもできます。
ISPの詳細については、スキル内課金の概要とスキル内課金のスキーマを参照してください。
eTag
を使用してスキルパッケージの上書きを防止する
スキルパッケージAPIを使用してスキルパッケージを既存のスキルにインポートする場合、インポートしたスキルパッケージによって、既存のスキルのコンポーネントが上書きされます。状況によって、既存のスキルの上書きをしないようにしたい場合があります。たとえば、グラフィックデザイナーと開発者が同時に同じスキルについて作業する、次のような状況を考えてみましょう。
- グラフィックデザイナーと開発者はそれぞれスキルパッケージAPIを使用して、スキルの別々のコピーを自分のノートPCにエクスポートしています。
- グラフィックデザイナーは新しい画像をスキルパッケージに追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。
- 開発者はスキルの対話モデルを更新し、新しいISPを追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。このインポートによってグラフィックデザイナーが加えた変更は上書きされます。開発者のスキルパッケージのローカルコピーにはこの変更が含まれていないためです。
このような状況を回避するために、スキルパッケージのeTag
を利用できます。eTag
は、スキルパッケージのopaqueバージョン識別子と考えることができます。eTag
は、以下の操作をしたときに応答の本文で取得されます。
既存のスキルのパッケージをインポートするときに、If-Match
HTTPリクエストヘッダーにeTag
値を含めることができます。
eTagを使用して、前の状況を考えてみましょう。
- グラフィックデザイナーと開発者はそれぞれスキルパッケージAPIを使用して、スキルの別々のコピーを自分のノートPCにエクスポートしています。それぞれがスキルパッケージの.zipファイルに加えて、
eTag
値を保存します。 - グラフィックデザイナーは新しい画像をスキルパッケージに追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。グラフィックデザイナーのインポートリクエストの
If-Match
HTTPヘッダーにはeTag
値が含まれており、サーバー側のスキルパッケージのeTag
値と一致します。インポートが成功すると、この最新バージョンのスキルパッケージ用に新しいeTag
値が生成されます。 - 開発者はスキルの対話モデルを更新し、新しいISPを追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。開発者のインポートリクエストの
If-Match
HTTPヘッダーにはeTag
値が含まれていますが、サーバー側のスキルパッケージのeTag
値と一致しないため、インポートリクエストは失敗します。 - 開発者は、スキルパッケージをエクスポートして、最新のバージョンおよび対応する
eTag
値を取得します。このバージョンには、グラフィックデザイナーが加えた以前の更新も含まれています。 - 開発者は自分のローカルの変更と最新バージョンを比較し、その差分を解決します。
- 開発者は、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。開発者のインポートリクエストの
If-Match
HTTPヘッダーにはeTag
値が含まれており、今回はサーバー側のスキルパッケージのeTag
値と一致するため、インポートリクエストは成功します。
APIのエンドポイントと認可
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。
新しいアップロードURLを作成する
このAPIを使うと、署名付きアップロードURLを作成できます。このURLはAmazon S3へのスキルパッケージのアップロードに使用できます。スキルパッケージをS3にアップロードするには、以下の方法があります。
- このAPIへの応答で受信した署名付きURLに、HTTP
PUT
リクエストを送信します。 - AWS SDKを使用します。詳細については、Amazon S3ドキュメントの署名付きURLを使用したオブジェクトのアップロードを参照してください。
スキルパッケージをインターネット上のパブリックにアクセス可能なURLにアップロードすることで、このAPI全体をバイパスすることもできます。
スキルパッケージをS3または独自のURLにアップロードすると、以下の処理ができるようになります。
リクエスト
POST /v1/skills/uploads
応答
201 Created
応答の本文には、以下のサンプルにあるようにuploadUrl
値と有効期限が含まれます。
{
"uploadUrl": "string",
"expiresAt": "2018-10-11T19:28:34.525Z"
}
エラー
コード | 説明 |
---|---|
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
429 | 許可されているリクエスト制限を超えています。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
新しいスキルパッケージを作成する
このAPIを使うと、新しいスキルパッケージを作成するリクエストを送信できます。
リクエスト
POST /v1/skills/imports
リクエスト本文は以下の形式で指定します。
{
"vendorId": "string",
"location": "string"
}
応答
202 Accepted
Location
ヘッダーの値は、インポートリクエストのステータスを追跡するために使用できる相対URLです。
エラー
コード | 説明 |
---|---|
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
413 | ペイロードが大きすぎます。 |
429 | 許可されているリクエスト制限を超えています。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
既存のスキル用にパッケージをインポートする
このAPIは、skillId
で指定した既存スキル用に.zip形式のパッケージファイルをインポートするリクエストを送信します。
リクエスト
POST /v1/skills/{skillId}/imports
スキルに対する以前の更新の上書きを防止するために、必要に応じて、If-Match
HTTPヘッダーとeTag
値を含めることができます。詳細については、eTag
を使用してスキルパッケージの上書きを防止するを参照してください。
リクエスト本文は以下の形式で指定されます。location
の値は事前に取得した署名付きURLか、.zip形式のスキルパッケージをダウンロードできる公開URLになります。詳細については、アップロードURLを作成するを参照してください。
{
"location": "string"
}
応答
202 Accepted
Location
ヘッダーの値は、リクエストで指定したURLです。
エラー
コード | 説明 |
---|---|
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
409 | 競合しています。 |
413 | ペイロードが大きすぎます。 |
429 | 許可されているリクエスト制限を超えています。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
指定したimportIdのステータスを取得する
指定したimportId
のimportStatus
を取得します。
リクエスト
GET /v1/skills/imports/{importId}
応答
200 OK
ステータスは次のいずれかになります。 FAILED
, IN_PROGRESS
, or SUCCEEDED
.また、resources
オブジェクトのステータスには、次のいずれかの値が含まれます。 FAILED
, IN_PROGRESS
, SUCCEEDED
, ROLLBACK_IN_PROGRESS
, ROLLBACK_SUCCEEDED
, or ROLLBACK_FAILED
.
応答の本文
{
"status": "enum",
"errors": [
{
"code": "string",
"message": "string"
}
],
"warnings": [
{
"code": "string",
"message": "string"
}
],
"skill": {
"skillId": "string",
"eTag": "string",
"resources": [
{
"name": "string",
"status": "enum",
"errors": [
{
"code": "string",
"message": "string"
}
],
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
]
}
}
エラー
コード | 説明 |
---|---|
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
既存のスキルのエクスポートリクエストを作成する
既存のスキルのエクスポートリクエストを作成します。その後、エクスポートしたスキルのダウンロード元となるURLを含む、エクスポートリクエストのステータスを取得できます。
リクエスト
stage
の値は、live
(公開中のスキル)またはdevelopment
(開発中ステージのスキル)である必要があります。
POST /v1/skills/{skillId}/stages/{stage}/exports
応答
202 Accepted
応答の本文はありません。エクスポートしたスキルのダウンロード元となるURLを含む、エクスポートリクエストのステータスを取得するには、応答のLocation
ヘッダーにあるパスにGET
リクエストを送信します。詳細については、エクスポートリクエストのステータスを取得するを参照してください。
エラー
コード | 説明 |
---|---|
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
404 | リクエストされたリソースが見つかりません。 |
409 | ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。 |
429 | 許可されているリクエスト制限を超えています。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
エクスポートリクエストのステータスを取得する
前述の手順で作成したエクスポートリクエストののステータスを取得します。エクスポートリクエストのステータスがSUCCEEDED
の場合、応答には、エクスポートしたスキルが格納された.zip形式のファイルをダウンロードできるURLが示されます。
リクエスト
前述の手順で作成したエクスポートリクエストに対する応答のLocation
ヘッダーに含まれるパスに、GET
リクエストを送信します。このパスにはexportId
が含まれているので、exportIdを取得するための追加の手順は必要ありません。
GET /v1/skills/exports/{exportId}
応答
200 OK
応答の本文には、次のいずれかのステータスが含まれます。 FAILED
, IN_PROGRESS
, or SUCCEEDED
.ステータスがSUCCEEDED
の場合、skill.location
の値には、エクスポートしたスキルが格納された.zip形式のファイルをダウンロードできるURLが示されます。
応答本文の例
{
"skill": {
"expiresAt": "1550521786056",
"location": "エクスポートしたスキルのダウンロード元となるURL",
"eTag": "string"
},
"status": "SUCCEEDED"
}
エラー
コード | 説明 |
---|---|
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |