スキルパッケージAPIリファレンス



スキルパッケージAPIのリファレンス

スキルパッケージAPIは、コンポーネントごとではなく、1つのパッケージとしてスキルと対話するために使用できます。

スキルパッケージ

スキルパッケージは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

スキルパッケージの形式を使用して、スキルを作成およびインポートするには：

  1. スキルコンポーネントを前の図のように配置し、最上位フォルダをzip形式で圧縮します。
  2. アップロードURLを作成します。
  3. 前の手順で作成したURLを使用して、.zipファイルをAmazon S3にアップロードします。
  4. スキルパッケージを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のファイルを整理できます。
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を使用してスキルパッケージを既存のスキルにインポートする場合、インポートしたスキルパッケージによって、既存のスキルのコンポーネントが上書きされます。状況によって、既存のスキルの上書きをしないようにしたい場合があります。たとえば、グラフィックデザイナーと開発者が同時に同じスキルについて作業する、次のような状況を考えてみましょう。

  1. グラフィックデザイナーと開発者はそれぞれスキルパッケージAPIを使用して、スキルの別々のコピーを自分のノートPCにエクスポートしています。
  2. グラフィックデザイナーは新しい画像をスキルパッケージに追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。
  3. 開発者はスキルの対話モデルを更新し、新しいISPを追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。このインポートによってグラフィックデザイナーが加えた変更は上書きされます。開発者のスキルパッケージのローカルコピーにはこの変更が含まれていないためです。

このような状況を回避するために、スキルパッケージのeTagを利用できます。eTagは、スキルパッケージのopaqueバージョン識別子と考えることができます。eTagは、以下の操作をしたときに応答の本文で取得されます。

既存のスキルのパッケージをインポートするときに、If-Match HTTPリクエストヘッダーにeTag値を含めることができます。

eTagを使用して、前の状況を考えてみましょう。

  1. グラフィックデザイナーと開発者はそれぞれスキルパッケージAPIを使用して、スキルの別々のコピーを自分のノートPCにエクスポートしています。それぞれがスキルパッケージの.zipファイルに加えて、eTag値を保存します。
  2. グラフィックデザイナーは新しい画像をスキルパッケージに追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。グラフィックデザイナーのインポートリクエストのIf-Match HTTPヘッダーにはeTag値が含まれており、サーバー側のスキルパッケージのeTag値と一致します。インポートが成功すると、この最新バージョンのスキルパッケージ用に新しいeTag値が生成されます。
  3. 開発者はスキルの対話モデルを更新し、新しいISPを追加した後、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。開発者のインポートリクエストのIf-Match HTTPヘッダーにはeTag値が含まれていますが、サーバー側のスキルパッケージのeTag値と一致しないため、インポートリクエストは失敗します。
  4. 開発者は、スキルパッケージをエクスポートして、最新のバージョンおよび対応するeTag値を取得します。このバージョンには、グラフィックデザイナーが加えた以前の更新も含まれています。
  5. 開発者は自分のローカルの変更と最新バージョンを比較し、その差分を解決します。
  6. 開発者は、スキルパッケージAPIを使用して、スキルパッケージをアップロードし、既存のスキルにインポートします。開発者のインポートリクエストのIf-Match HTTPヘッダーにはeTag値が含まれており、今回はサーバー側のスキルパッケージのeTag値と一致するため、インポートリクエストは成功します。

APIのエンドポイントと認可

このAPIのエンドポイントは、https://api.amazonalexa.comです。すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。

新しいアップロードURLを作成する

このAPIを使うと、署名付きアップロードURLを作成できます。このURLはAmazon S3へのスキルパッケージのアップロードに使用できます。スキルパッケージをS3にアップロードするには、以下の方法があります。

スキルパッケージをインターネット上のパブリックにアクセス可能な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 サービスを利用できません。