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



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

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

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

スキルパッケージの形式

スキルは、以下のコンポーネントで構成されます。一部のコンポーネントはオプションです。Alexa Skills Kit開発者コンソールだけを使用してスキルと対話する場合でも、これらのコンポーネントはバックグラウンドで存在しています。ASK CLIまたはSMAPIを使用してスキルと対話する場合、これらのコンポーネントは個々のファイルとして表示されます。

  • マニフェスト - 表示名、スキルの機能(ビデオ、スマートホーム、カスタム)、スキルサービスコードのエンドポイント(AWS Lambdaまたは別のウェブエンドポイント)といった一般的なメタデータとコンフィギュレーションです。スキルマニフェストの名前は、skill.jsonです。このマニフェストはすべてのスキルに必須です。

残りのコンポーネントはスキルによってある場合とない場合があります。

  • Alexaスキルストアに表示される大小のアイコンなどの画像アセット。開発者コンソール、ASK CLI、SMAPIを使用してこれらのアセットをアップロードしている場合があります。

  • スキルサービスコード。

  • 対話モデル - スキルの音声ユーザーインターフェースを定義します。呼び出し名、インテント、スロットなどが含まれます。対話モデルの名前は<locale>.jsonの形式で記述します(en-US.jsonなど)。

スキルにはアカウントリンク情報スキル内課金が含まれる場合もありますが、スキルパッケージAPIでは現在これらをサポートしていません。スキルパッケージAPIを使うことはできますが、これらの機能にはSMAPIも使用する必要があります。

スキルパッケージファイルは、これらのコンポーネントをすべてまとめて.zip拡張子の付いたファイルに圧縮します。スキルパッケージフォルダーを以下の図のように設定する必要があります。スマートホームスキルの場合、対話モデルフォルダーはありません。

.zip形式のスキルパッケージファイルを手動で作成するには、スキルコンポーネントを以下のように配置し、最上位フォルダーを含めて.zip形式のファイルを作成します。その後、アップロードURLを作成し、既存スキルの新しいインポートを作成することで、スキルパッケージをインポートします。

開発者ポータルにすでにスキルが存在する場合、スキルをエクスポートして.zip形式のファイルにスキルをダウンロードできます。

スキルパッケージの形式
スキルパッケージの形式

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

このAPIを使うと、署名付きアップロードURLを作成できます。このURLはスキルパッケージのインポートに使用できます。URLはAmazon S3に配置します。詳細については、Amazon S3ドキュメントの署名付きURLを使用したオブジェクトのアップロードを参照してください。PUTリクエストを使用して指定した署名付き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形式のパッケージファイルを作成するリクエストを送信します。その後必要に応じて、このパッケージを署名付きURLを使用してインポートできます。

リクエスト

POST /v1/skills/{skillId}/imports

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

{
  "location": "string"
}

応答

202 Accepted

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

エラー

コード 説明
400 クライアントエラーにより、サーバーがリクエストを処理できません。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
413 ペイロードが大きすぎます。
429 許可されているリクエスト制限を超えています。
500 内部サーバーエラーです。
503 サービスを利用できません。

指定したimportIdのステータスを取得する

指定したimportIdimportStatusを取得します。

リクエスト

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": "FAILED",
  "skill": {
    "skillId": "string",
    "eTag": "string",
    "resources": [
      {
        "name": "string",
        "status": "FAILED",
        "errors": [
          {
            "message": "string"
          }
        ],
        "warnings": [
          {
            "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"
  },
  "status": "SUCCEEDED"
}

エラー

コード 説明
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
429 許可されているリクエスト制限を超えています。
500 内部サーバーエラーです。
503 サービスを利用できません。