Alexaカタログの管理



Alexaカタログの管理

特定の音声モデルAPIでは、カタログコンテンツのAlexaへのアップロードをサポートしています。これにより、Alexaの音声モデルは、Alexaスキルの一部としてカタログデータを参照することで、ユーザーの発話を動的に解決できます。このため、AlexaカタログAPIを使ってコンテンツカタログをAlexaにアップロードすることにより、スキルのユーザーエクスペリエンスを向上できます。

APIのエンドポイントとヘッダー

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

カタログ作成プロセス

カタログを作成し、カタログにコンテンツを追加し、スキルに関連付けるプロセスは以下のとおりです。

  1. カタログを作成します。
  2. アップロードを作成し、uploadIdと複数のアップロードの署名済みのアップロードリクエストURLを取得します。
  3. カタログファイルを部分ごとに、署名済みのアップロードリクエストURLを使ってAmazon S3にアップロードします。
  4. Amazon S3アップロードから、関連する追加のメタデータと情報の両方を提供して、アップロードを完了します。

カタログはスキルに関連付けなくてもかまいませんし、1つまたは複数のスキルに関連付けることもできますが、カタログへのアップロードを開始する前に、カタログをスキルに関連付ける必要があります。

カタログの作成

リクエストで提供された基本的な情報をもとに新しいカタログが作成されます。カタログの作成時には、レコードはありません。レコードのアップロードは別途行います。カタログは、APIを呼び出すvendorIdに関連付けられます。

リクエスト

HTTP/1.1

POST /v0/catalogs

リクエスト本文

{
  "title": "string",
  "type": "string",
  "usage": "string",
  "vendorId": "string"
}
パラメーター説明必須
titleカタログのタイトルです。
typeカタログの種類です。
usageカタログの使用方法です。
vendorId一意のベンダーIDです。

応答

正常に完了すると、コード201とカタログタイトルの文字列が返されます。

応答コード

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

スキルとカタログを関連付ける

このAPIは、指定したカタログを指定したスキルに関連付けます。

リクエスト

HTTP 1.1

PUT /v0/skills/{skillId}/catalogs/{catalogId}
フィールド説明パラメータータイプ必須
skillId一意のスキルIDです。パス
catalogId一意のカタログIDです。パス

リクエスト本文

ありません。

応答

正常に完了すると、コード201が返されます。

応答コード

コード説明
201正常に関連付けられました。
400クライアントエラーにより、サーバーがリクエストを処理できません。
401認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
403リクエストされた操作は許可されていません。
404リクエストされたリソースが見つかりません。
429許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500内部サーバーエラーです。
503サービスを利用できません。

カタログリストを取得する

vendorIdに関連付けられたすべてのカタログのリストを取得します。オプションのmaxResultsnextTokenの値により、結果のページ分割を指定します。

リクエスト

HTTP/1.1

vendorIdによるカタログの取得

GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token}
フィールド説明パラメータータイプ必須
vendorId一意のベンダーIDです。クエリーパラメーター
maxResultsページごとに表示するスキルの最大数です。50を超える値を指定することはできません。クエリーパラメーター
nextToken前回のリストスキル応答で、responseオブジェクトで返された継続トークンです。このパラメーターがnullの場合、応答には最初のセットのスキルが含まれます。クエリーパラメーター

リクエスト本文

ありません。

応答

正常に完了すると、コード200と、返された各catalogIdのリンクであるlinksオブジェクト、それぞれ一意のIDで指定されるカタログの配列のcatalogsオブジェクトが返されます。

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "isTruncated": true,
  "nextToken": "string",
  "catalogs": [
    {
      "id": "string",
      "title": "string",
      "type": "string",
      "usage": "string",
      "lastUpdatedDate": "2018-10-25T08:07:27.057Z",
      "createdDate": "2018-10-25T08:07:27.057Z",
      "associatedSkillIds": [
        "string"
      ]
    }
  ]
}
パラメーター説明
_linksHypertext Application Languageリンクで、リソース間を移動するために使用します。
isTruncated結果が複数ページの場合、値はtrueになります。
nextToken このAPI呼び出しへの応答が切り捨てられる(isTruncatedの値がtrue)と、応答にもnextToken要素が含まれます。nextTokenの値は、オブジェクトの次のセットのリストを表示する継続トークンとして次のリクエストで使用できます。
catalogscatalogオブジェクトを含む配列です。

linksオブジェクトのパラメーター

パラメーター説明
selfアップロードのURLを含むオブジェクトです。
self.hrefアップロードのURL文字列です。

catalogオブジェクトのパラメーター

catalogsオブジェクトは、catalogオブジェクトの配列です。

パラメーター説明
iduploadsオブジェクトの一意のIDです。
titleカタログのタイトルです。
catalogIdカタログの一意のIDです。
statusアップロード全体のステータスです。以下のいずれかになります: PENDINGPROCESSINGFAILEDSUCCEEDED
createdDateアップロード部分が作成された日付です。
lastUpdatedDateアップロード部分が最後に更新された日付です。
associatedSkillIdsこのカタログに関連付けられたskillIdの配列です。

応答コード

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

特定のカタログを取得する

catalogIdで指定されたカタログを返します。

リクエスト

HTTP/1.1

GET /v0/catalogs/{catalogId}
フィールド説明パラメータータイプ必須
catalogId一意のカタログIDです。含まれない場合、カタログのセット全体が返されます。パス

リクエスト本文

本文はありません。

応答

正常に完了すると、コード200とcatalogオブジェクトが返されます。

{
  "id": "string",
  "title": "string",
  "type": "string",
  "usage": "string",
  "lastUpdatedDate": "2018-10-25T08:07:55.752Z",
  "createdDate": "2018-10-25T08:07:55.752Z",
  "associatedSkillIds": [
    "string"
  ]
}

catalogオブジェクトのパラメーター

パラメーター説明
iduploadsオブジェクトの一意のIDです。
titleカタログのタイトルです。
catalogIdカタログの一意のIDです。
statusアップロード全体のステータスです。以下のいずれかになります: PENDINGPROCESSINGFAILEDSUCCEEDED
createdDateアップロード部分が作成された日付です。
lastUpdatedDateアップロード部分が最後に更新された日付です。
associatedSkillIdsこのカタログに関連付けられたskillIdsの配列です。

応答コード

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

指定したカタログのアップロードを作成する

このAPIは指定したカタログの新しいアップロードを作成し、ファイルのAmazon S3への後続のアップロードに使用する署名済みアップロード部分を返します。

リクエスト

HTTP/1.1

POST /v0/catalogs/{catalogId}/uploads

リクエスト本文

numberOfPartsの値は、カタログを分割する数を表す数値です。応答では、同じ数の署名済みURL(部分ごとに1つ)が提供されるため、簡単にアップロードできます。

{
  "numberOfParts": <integer>,
}

応答

正常に完了すると、コード201とuploadオブジェクトが返されます。

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "createdDate": "2018-10-25T08:18:50.297Z",
  "lastUpdatedDate": "2018-10-25T08:18:50.297Z",
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ],
  "presignedUploadParts": [
    {
      "url": "string",
      "partNumber": <integer>
    }
  ]
}
パラメーター説明
iduploadオブジェクトの一意のIDです。
catalogIdカタログの一意のIDです。
statusアップロード全体のステータスです。以下のいずれかになります: PENDINGPROCESSINGFAILEDSUCCEEDED
createdDateアップロード部分が作成された日付です。
lastUpdatedDateアップロード部分が最後に更新された日付です。
ingestionSteps新しいアップロードの取り込みプロセスの1ステップを表すオブジェクトです。

ingestionStepsオブジェクトのパラメーター

パラメーター説明
name取り込みのどのステップかを表します。以下のいずれかになります: UPLOAD、SCHEMA_VALIDATION
statusアップロードの取り込みプロセス内で、特定のステップのステータスを表します。以下のいずれかになります: PENDINGSUCCEEDEDFAILEDCANCELLED
logUrl取り込みステップのログを含むファイルのURLを表します。
errorsステップの実行中に発生したエラーを含みます。正常に実行されると、この配列は空になります。

応答コード

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

特定のカタログのアップロードを取得する

特定のカタログのアップロードのリストを取得します。アップロードは、検証された後、カタログに取り込まれるファイルになります。オプションのmaxResultsnextTokenの値により、結果のページ分割を指定します。

リクエスト

HTTP/1.1

GET /v0/catalogs/{catalogId}/uploads?maxResults={num}&nextToken={token}
フィールド説明パラメータータイプ必須
catalogId一意のカタログIDです。パス
maxResultsページごとに表示するスキルの最大数です。50を超える値を指定することはできません。クエリーパラメーター
nextToken前回のリストスキル応答で、responseオブジェクトで返された継続トークンです。このパラメーターがnullの場合、応答には最初のセットのスキルが含まれます。クエリーパラメーター

リクエスト本文

ありません。

応答

正常に完了すると、コード200とアップロード部分へのリンクを含むオブジェクト、アップロードのリストが返されます。

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "isTruncated": true,
  "nextToken": "string",
  "uploads": [
    {
      "id": "string",
      "catalogId": "string",
      "status": "PENDING",
      "createdDate": "2018-10-27T05:26:15.811Z",
      "lastUpdatedDate": "2018-10-27T05:26:15.811Z"
    }
  ]
}
パラメーター説明
_linksHypertext Application Languageリンクで、リソース間を移動するために使用します。
isTruncated結果が複数ページの場合、値はtrueになります。
nextToken このAPI呼び出しへの応答が切り捨てられる(isTruncatedの値がtrue)と、応答にもnextToken要素が含まれます。nextTokenの値は、オブジェクトの次のセットのリストを表示する継続トークンとして次のリクエストで使用できます。
uploads各アップロードの詳細リストを含むオブジェクトの配列です。

linksオブジェクトのパラメーター

パラメーター説明
selfアップロードのURLを含むオブジェクトです。
self.hrefアップロードのURL文字列です。

uploadsオブジェクトのパラメーター

パラメーター説明
iduploadsオブジェクトの一意のIDです。
catalogIdカタログの一意のIDです。
statusアップロード全体のステータスです。以下のいずれかになります: PENDINGPROCESSINGFAILEDSUCCEEDED
createdDateアップロード部分が作成された日付です。
lastUpdatedDateアップロード部分が最後に更新された日付です。

応答コード

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

特定のアップロードを取得する

指定したカタログ用に作成されたアップロードに関する詳細情報を取得します。アップロードの取り込みステップとファイルダウンロードの署名済みURLを含みます。

catalogIdはカタログの一意のID、uploadIdはアップロードの一意のIDです。

リクエスト

HTTP/1.1

GET /v0/catalogs/{catalogId}/uploads/{uploadId}
フィールド説明パラメータータイプ必須
catalogId 一意のカタログIDです。パスパラメーター

リクエスト本文

ありません。

応答

コード200とuploadオブジェクトが返されます。

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "createdDate": "2018-10-25T08:25:04.679Z",
  "lastUpdatedDate": "2018-10-25T08:25:04.679Z",
  "presignedDownloadUrl": "string",
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

uploadオブジェクトのパラメーター

パラメーター説明
iduploadオブジェクトの一意のIDです。
catalogIdカタログの一意のIDです。
statusアップロード全体のステータスです。以下のいずれかになります: PENDING、PROCESSING、FAILED、SUCCEEDED
createdDateアップロード部分が作成された日付です。
lastUpdatedDateアップロード部分が最後に更新された日付です。
presignedDownloadUrlその部分のダウンロード元の署名済みURLです。
ingestionSteps取り込みステップは、新しいアップロードの取り込みプロセスの1ステップです。

ingestionStepsオブジェクトのパラメーター

パラメーター説明
name取り込みのどのステップかを表します。以下のいずれかになります: UPLOADSCHEMA_VALIDATION
statusアップロードの取り込みプロセス内で、特定のステップのステータスを表します。以下のいずれかになります: PENDINGSUCCEEDEDFAILEDCANCELLED
logUrl取り込みステップのログを含むファイルのURLを表します。
errorsステップの実行中に発生したエラーを含みます。正常に実行されると、この配列は空になります。

応答コード

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

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

カタログの新しいアップロードを作成し、ファイルアップロードの署名済みアップロード部分を返します。

HTTP/1.1

POST /catalogs/{catalogId}/uploads

リクエスト

リクエスト本文

{
  "numberOfUploadParts": 0,
  "locales": [
    "string"
  ]
}

応答

作成が正常に完了すると、成功したことを表すコード201が返されます。

応答本文

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "locales": [
    "string"
  ],
  "createdDate": "2018-11-06T23:52:20.528Z",
  "lastUpdatedDate": "2018-11-06T23:52:20.528Z",
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ],
  "presignedUploadParts": [
    {
      "url": "string",
      "partNumber": 0
    }
  ]
}

応答コード

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

アップロードを実行する

アップロードを実行します。ファイルが署名済みのURLを使用してバックエンドのデータストアにアップロード(新しいアップロードの作成を参照)された後に呼び出されます。

リクエスト

HTTP/1.1

POST /v0/catalogs/{catalogId}/uploads/{uploadId}
フィールド説明パラメータータイプ必須
catalogId 一意のカタログIDです。パス
uploadId 一意のアップロードIDです。パス

応答

正常に完了すると、アップデートが受け付けられたことを表すコード202が返されます。

応答コード

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