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

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

1. スキルコンポーネントを前の図のように配置し、最上位フォルダをzip形式で圧縮します。
   注： スキルパッケージをインターネット上のパブリックにアクセス可能なURLにアップロードすることで、必要に応じて、次の2つの手順をスキップすることができます。
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のファイルを整理できます。

警告： 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を使用してスキルパッケージを既存のスキルにインポートする場合、インポートしたスキルパッケージによって、既存のスキルのコンポーネントが上書きされます。状況によって、既存のスキルの上書きをしないようにしたい場合があります。たとえば、グラフィックデザイナーと開発者が同時に同じスキルについて作業する、次のような状況を考えてみましょう。

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

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

• 指定したインポートIDのステータスを取得する
• エクスポートリクエストのステータスを取得する

既存のスキルのパッケージをインポートするときに、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にアップロードするには、以下の方法があります。

• この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"
}

エラー

新しいスキルパッケージを作成する

このAPIを使うと、新しいスキルパッケージを作成するリクエストを送信できます。

リクエスト

POST /v1/skills/imports

リクエスト本文は以下の形式で指定します。

{
  "vendorId": "string",
  "location": "string"
}

応答

202 Accepted

Locationヘッダーの値は、インポートリクエストのステータスを追跡するために使用できる相対URLです。

エラー

既存のスキル用にパッケージをインポートする

このAPIは、skillIdで指定した既存スキル用に.zip形式のパッケージファイルをインポートするリクエストを送信します。

リクエスト

POST /v1/skills/{skillId}/imports

スキルに対する以前の更新の上書きを防止するために、必要に応じて、If-Match HTTPヘッダーとeTag値を含めることができます。詳細については、eTagを使用してスキルパッケージの上書きを防止するを参照してください。

リクエスト本文は以下の形式で指定されます。locationの値は事前に取得した署名付きURLか、.zip形式のスキルパッケージをダウンロードできる公開URLになります。詳細については、アップロードURLを作成するを参照してください。

{
  "location": "string"
}

応答

202 Accepted

Locationヘッダーの値は、リクエストで指定したURLです。

エラー

指定した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"
          }
        ]
      }
    ]
  }
}

エラー

既存のスキルのエクスポートリクエストを作成する

既存のスキルのエクスポートリクエストを作成します。その後、エクスポートしたスキルのダウンロード元となるURLを含む、エクスポートリクエストのステータスを取得できます。

リクエスト

stageの値は、live（公開中のスキル）またはdevelopment（開発中ステージのスキル）である必要があります。

POST /v1/skills/{skillId}/stages/{stage}/exports

応答

202 Accepted

応答の本文はありません。エクスポートしたスキルのダウンロード元となるURLを含む、エクスポートリクエストのステータスを取得するには、応答のLocationヘッダーにあるパスにGETリクエストを送信します。詳細については、エクスポートリクエストのステータスを取得するを参照してください。

エラー

エクスポートリクエストのステータスを取得する

前述の手順で作成したエクスポートリクエストののステータスを取得します。エクスポートリクエストのステータスが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"
}

エラー