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



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

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

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

スキルパッケージの形式

スキルは、以下のコンポーネントで構成されます。一部のコンポーネントはオプションです。開発者コンソールだけを使用してスキルと対話する場合でも、これらのコンポーネントはバックグラウンドで存在しています。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に配置します。オブジェクトを署名付きURLにアップロードするを参照してください。PUTリクエストを使用して指定した署名付きURLにパッケージをアップロードすることもできます。

リクエスト

HTTP/1.1

POST /v1/skills/uploads

応答

201 作成済みです。応答の本文には、以下のサンプルにあるようにuploadUrl値と有効期限が含まれます。

{
  "uploadUrl": "string",
  "expiresAt": "2018-10-11T19:28:34.525Z"
}

エラー

コード 説明
401 認可トークンが無効か、リソースに対するアクセス権限がありません。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数が含まれます。
500 内部サーバーエラーです。
503 サービスを利用できません。

現在のベンダー用に新しいスキルパッケージを作成する

このAPIを使うと、現在のベンダー用に新しいスキルパッケージを作成するリクエストを送信できます。このAPIは「Location」ヘッダーの値を返します。S3から.zip形式のパッケージをダウンロードできる相対URLです。

リクエスト

HTTP/1.1

POST /v1/skills/imports

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

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

応答

202 受け付けられました。「Location」ヘッダーの値は、S3から.zip形式のパッケージをダウンロードできる相対URLです。

{
  HTTP/1.1 202 Accepted
   "headers": {
    "Location": "/v1/skills/imports/{importId}"
}

エラー

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

既存のスキル用にパッケージを作成する

このAPIは、skillIdで指定した既存スキルから.zip形式のパッケージファイルを作成するリクエストを送信します。その後必要に応じて、このパッケージを署名付きURLを使用してインポートできます。

リクエスト

HTTP/1.1

POST /v1/skills/{skillId}/imports

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

{
  "location": "string"
}

応答

202 受け付けられました。「Location」ヘッダーの値は、リクエストで指定したURLです。

{
   HTTP/1.1 202 Accepted
   "headers": {
    "Location": "/v1/skills/imports/{importId}"
}

エラー

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

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

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

リクエスト

HTTP/1.1

GET /v1/skills/imports/{importId}

応答

200 OKステータスは次のいずれかになります。 FAILEDIN_PROGRESSSUCCEEDED。また、resourcesオブジェクトのステータスには、次のいずれかの値が含まれます。 FAILEDIN_PROGRESSSUCCEEDEDROLLBACK_IN_PROGRESSROLLBACK_SUCCEEDEDROLLBACK_FAILED

応答本文

{
  "status": "FAILED",
  "skill": {
    "skillId": "string",
    "eTag": "string",
    "resources": [
      {
        "name": "string",
        "status": "FAILED",
        "errors": [
          {
            "message": "string"
          }
        ],
        "warnings": [
          {
            "message": "string"
          }
        ]
      }
    ]
  }
}

エラー

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

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

既存のスキルのエクスポートリクエストを作成します。その後、エクスポートリクエストのステータスを取得できます。エクスポートが成功した場合、スキルパッケージを含むzipファイルが作成されます。

リクエスト

stageの値はlivedevelopmentのいずれかになります。

HTTP/1.1

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

応答

202 受け付けられました。「Location」ヘッダーの値は、S3から.zip形式のパッケージをダウンロードできる相対URLです。

エラー

コード 説明
401 認可トークンが無効か、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
409 ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数が含まれます。
500 内部サーバーエラーです。
503 サービスを利用できません。

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

リクエスト

スキルのパッケージへのエクスポートは成功、失敗どちらの可能性もあります。既存スキルのエクスポートを作成すると、exportIdが取得されます。

HTTP/1.1

GET /v1/skills/exports/{exportId}

応答

200 OK次のステータスのいずれかを返します。 FAILEDIN_PROGRESSSUCCEEDEDlocationの値は結果のzip形式のスキルパッケージ(ファイル名:<skillname>.zip)の場所を表します。

応答本文のサンプル

{
  "status": "FAILED",
  "skill": {
    "location": "string",
    "expiresAt": "2018-10-11T19:14:04.070Z"
  }
}

エラー

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