Alexaカタログの管理



Alexaカタログの管理

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

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

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

カタログ作成プロセス

以下のプロセスに従って、カタログを作成し、スキルに関連付け、カタログにコンテンツを追加します。

  1. カタログを作成します。
  2. カタログをスキルに関連付けます。カタログはスキルに関連付けなくてもかまいませんし、1つまたは複数のスキルに関連付けることもできますが、カタログをスキルに関連付ける場合は、カタログへのアップロードを開始する前に関連付ける必要があります。
  3. アップロードを作成して、カタログのアップロードに使用するuploadIdと1つまたは複数の署名済みURLを取得します。
  4. 前の手順で取得した1つまたは複数の署名済みURLを使用して、カタログをAmazon S3にアップロードします。カタログをアップロードするには、PUTリクエストの本文にカタログ(またはカタログパート)を含めて、署名済みURL(マルチパートアップロードを使用する場合は複数のURL)に送信します。各PUTリクエストに対する応答のETagヘッダーにはETag値が含まれています。このETag値は、次の手順でアップロードを実行する際に必要です。

    必要に応じて、マルチパートアップロードを使用して、サイズの大きいカタログをアップロードすることもできます。

    • 1回のオペレーションでアップロード – 5 GB以下のカタログの場合、1つのPUTリクエストを署名済みURLに送信することで、カタログ全体をアップロードできます。
    • マルチパートアップロード – マルチパートアップロードでは、カタログを一度にすべてアップロードするのではなく分割してアップロードできるため、サイズの大きいカタログのアップロードエクスペリエンスを向上させることができます。5MB以上のカタログでは、必要に応じてマルチパートアップロードを使用できます。5GBを超えるカタログの場合は、マルチパートアップロードを使用する必要があります。カタログの合計サイズは5TB未満である必要があります。

      マルチパートアップロードを使用するには、各パートが5MB以上、5GB以下になるようにカタログを分割します。最後のパートは5MB未満でもかまいません。前の手順の署名済みURLにPUTリクエストを送信しますが、各リクエストの本文には別のカタログパートが含まれています。これらのPUTリクエストは、個別に、任意の順序で、並行して送信できます。

      各PUTリクエストの応答で受信したETag値を保存し、次の手順でアップロードを実行します。アップロードが完了すると、複数のパートが1つのカタログに再構成されます。

  5. 前の手順で完了した各Amazon S3アップロードのETagを使用して、アップロードを実行します。

カタログを作成する

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

リクエスト

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は、指定したカタログを指定したスキルに関連付けます。

リクエスト

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

リクエスト本文

ありません。

応答

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

応答コード

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

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

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

リクエスト

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で指定されたカタログを返します。

リクエスト

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サービスを利用できません。

アップロードを作成する

カタログの新しいアップロードを作成し、カタログのアップロードに使用するuploadIdと1つまたは複数の署名済みURLを返します。

このAPIを呼び出した後、応答で受信した1つまたは複数の署名済みURLを使用して、カタログをAmazon S3にアップロードします。カタログをアップロードする方法の詳細については、カタログ作成プロセスを参照してください。

カタログのアップロードが終了したら、各Amazon S3アップロードリクエストで取得したETag値を使用して、アップロードを実行します。

リクエスト

POST /catalogs/{catalogId}/uploads
フィールド説明パラメーターの型必須
catalogId 一意のカタログIDです。パス
numberOfUploadPartsマルチパートアップロードを使用する場合に、アップロードのパート数を指定します。構造については、以下のJSONを参照してください。本文マルチパートアップロードを使用する場合は必須です。このパラメーターが含まれていない場合、デフォルト値は1です。

リクエスト本文

{
  "numberOfUploadParts": 2
}

応答

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

応答本文

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

応答コード

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

アップロードを実行する

アップロードを実行します。署名済みURLを使用してAmazon S3にカタログをアップロードした後、このリクエストを送信します。カタログをアップロードする方法の詳細については、カタログ作成プロセスを参照してください。

リクエスト

POST /v0/catalogs/{catalogId}/uploads/{uploadId}
フィールド説明パラメーターの型必須
catalogId 一意のカタログIDです。パス
uploadId 一意のアップロードIDです。パス
partETagsETag(文字列)とパート番号(整数)のペアのリストです。マルチパートアップロードでアップロードされたカタログのパートごとに1つあります。構造については、以下のJSONを参照してください。本文カタログがマルチパートアップロードでアップロードされた場合は必須です。

リクエスト本文

{
  "partETags": [
    {
      "eTag": "string",
      "partNumber": 1
    },
    {
      "eTag": "string",
      "partNumber": 2
    }
  ]
}

応答

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

応答コード

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

アップロードリストを取得する

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

リクエスト

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": "string",
      "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サービスを利用できません。

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

特定のカタログの特定のアップロードに関する情報を取得します。

catalogIdはカタログを指定し、uploadIdはアップロードを指定します。

リクエスト

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

リクエスト本文

ありません。

応答

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

{
  "id": "string",
  "catalogId": "string",
  "status": "string",
  "createdDate": "date time stamp",
  "lastUpdatedDate": "date time stamp",
  "file": {
    "presignedDownloadUrl": "string",
    "status": "string"
  },
  "ingestionSteps": [
    {
      "name": "string",
      "status": "string",
      "logUrl": "string",
      "errors": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

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

パラメーター説明
iduploadオブジェクトの一意のIDです。
catalogIdカタログの一意のIDです。
statusアップロード全体のステータスです。以下のいずれかになります: PENDINGPROCESSINGFAILEDSUCCEEDED
createdDateアップロード部分が作成された日時です。形式は次のとおりです。 2018-10-25T08:25:04.679Z
lastUpdatedDateアップロード部分が更新された日時です。形式は次のとおりです。 2018-10-25T08:25:04.679Z
filefileオブジェクトは、特定のカタログの以前にアップロードしたファイルを表します。
ingestionSteps取り込みステップは、新しいアップロードの取り込みプロセスの1ステップです。

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

パラメーター 説明
presignedDownloadUrl 以前にアップロードしたファイルをダウンロードできるURLです。
status ファイルのステータスです。次のいずれかになります。 PENDINGAVAILABLEUNAVAILABLEPURGED

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

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

応答コード

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