カタログコンテンツのアップロード



特定の音声モデルAPIでは、Alexaからアクセス可能なカタログコンテンツのアップロードをサポートしています。Alexaの音声モデルは、Alexaスキルの一部としてカタログデータを参照することで、ユーザーの発話を動的に解決できます。Catalog Content Upload APIを使ってカタログコンテンツをアップロードし、Alexaが参照することで、スキルのユーザーエクスペリエンスを向上できます。

カタログコンテンツは、Amazon S3、独自ホスティングURL、Alexa-hostedサイトのいずれかにアップロードできます。

• APIのエンドポイントとヘッダー
• APIのバージョン
• カタログを作成し、Amazon S3にアップロードする
• カタログを作成し、独自ホスティングドメインまたはAlexa-hostedドメインにアップロードする
• カタログを作成する
• カタログをスキルに関連付ける
• カタログリストを取得する（v0）
• 特定のカタログを取得する（v0）
• アップロードを作成する（v0）
• アップロードを実行する（v0）
• アップロードリストを取得する（v0）
• 指定したアップロードについての情報を取得する（v0）
• 独自ホスティングドメイン用のアップロードを作成する（v1）
• 指定したアップロードについての情報を取得する（v1）
• カタログコンテンツをアップロードするURLを生成する（v1）

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

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

APIのバージョン

どのような方法でカタログをホスティングする場合でも、適切な/v0 APIを使用してカタログを作成します。

Amazon S3でホスティングする場合は、適切な/v0 APIを使用して、カタログコンテンツのアップロードと管理を行います。

独自ホスティングサイトまたはAlexa-hostedサイトでホスティングする場合は、適切な/v1 APIを使用することで、独自ドメインによるカタログのアップロードと管理を行うことができます。

カタログを作成し、Amazon S3にアップロードする

以下のプロセスでは、/v0 APIを使用して、カタログの作成、スキルへの関連付け、コンテンツの追加、Amazon S3へのアップロードを行います。

1. カタログを作成します。
2. カタログをスキルに関連付けます。カタログはスキルに関連付けなくてもかまいませんし、1つまたは複数のスキルに関連付けることもできますが、カタログをスキルに関連付ける場合は、カタログへのアップロードを開始する前に関連付ける必要があります。
3. アップロードを作成（v0）して、カタログのアップロードに使用するuploadIdと1つまたは複数の署名済みURLを取得します。

4. 前の手順で取得した1つまたは複数の署名済みURLを使用して、カタログをAmazon S3にアップロードします。カタログをアップロードするには、PUTリクエストの本文にカタログ（またはカタログパート）を含めて、署名済みURL（マルチパートアップロードを使用する場合は複数のURL）に送信します。各PUTリクエストに対する応答のETagヘッダーにはETag値が含まれています。このETag値は、次の手順でアップロードを実行する際に必要です。コンテンツをAmazon S3にアップロードする方法の詳細については、Amazon S3 - 署名付きURLを使用したオブジェクトのアップロードを参照してください。

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

   • 1回のオペレーションでアップロード – 5GB以下のカタログの場合、1つのPUTリクエストを署名済みURLに送信することで、カタログ全体をアップロードできます。

   • マルチパートアップロード – マルチパートアップロードでは、カタログを一度にすべてアップロードするのではなく分割してアップロードできるため、サイズの大きなカタログのアップロードエクスペリエンスを向上させることができます。5MB以上のカタログでは、必要に応じてマルチパートアップロードを使用できます。5GBを超えるカタログの場合は、マルチパートアップロードを使用する必要があります。カタログの合計サイズは5TB未満である必要があります。

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

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

5. 前の手順で完了した各Amazon S3アップロードのETagを使用して、アップロードを実行します。
6. 必要に応じて、指定したアップロードについての情報を取得（v0）します。
7. 必要に応じて、カタログリストの取得や、指定したカタログの取得（v0）を行います。

カタログを作成し、独自ホスティングドメインまたはAlexa-hostedドメインにアップロードする

以下のプロセスでは、/v0 APIと/v1 APIを使用して、カタログの作成、スキルへの関連付け、コンテンツの追加、独自ドメインへのアップロードを行います。

1. /v0 APIを使用してカタログを作成します。
2. /v0 APIを使用してカタログをスキルに関連付けます。カタログはスキルに関連付けなくてもかまいませんし、1つまたは複数のスキルに関連付けることもできますが、カタログをスキルに関連付ける場合は、カタログへのアップロードを開始する前に関連付ける必要があります。
3. 独自ホスティングURLにカタログをアップロードする場合、独自ホスティングドメイン用のアップロードを作成する（v1）の手順に従います。
4. Alexa-hosted URLにカタログをアップロードする場合、カタログコンテンツをアップロードするURLを生成する（v1）の手順に従います。
5. 必要に応じて、指定したアップロードについての情報を取得（v1）します。
6. 必要に応じて、カタログリストの取得（v1）や、指定したカタログの取得（v1）を行います。
7. 独自ホスティングURLを使用する場合、カタログをそのURLに対応する場所にアップロードします。

8. Alexa-hosted URLを使用する場合、手順4で生成した1つまたは複数の署名済みURLにカタログをアップロードします。カタログをアップロードするには、PUTリクエストの本文にカタログ（またはカタログパート）を含めて、署名済みURL（マルチパートアップロードを使用する場合は複数のURL）に送信します。各PUTリクエストに対する応答のETagヘッダーにはETag値が含まれています。

   • 1回のオペレーションでアップロード – 5GB以下のカタログの場合、1つのPUTリクエストを署名済みURLに送信することで、カタログ全体をアップロードできます。

   • マルチパートアップロード – マルチパートアップロードでは、カタログを一度にすべてアップロードするのではなく分割してアップロードできるため、サイズの大きなカタログのアップロードエクスペリエンスを向上させることができます。5MB以上のカタログでは、必要に応じてマルチパートアップロードを使用できます。5GBを超えるカタログの場合は、マルチパートアップロードを使用する必要があります。カタログの合計サイズは5TB未満である必要があります。

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

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

カタログを作成する

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

リクエスト

POST /v0/catalogs

リクエスト本文の例

{
  "title": "string",
  "type": "string",
  "usage": "string",
  "vendorId": "string"
}

応答

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

応答コード

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

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

リクエスト

PUT /v0/skills/{skillId}/catalogs/{catalogId}

リクエスト本文はありません。

応答

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

応答コード

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

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

リクエスト

GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token}

リクエスト本文はありません。

応答

正常に完了すると、コード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"
      ]
    }
  ]
}

応答コード

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

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

リクエスト

GET /v0/catalogs/{catalogId}

応答

正常に完了すると、コード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オブジェクトのパラメーター

応答コード

アップロードを作成する（v0）

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

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

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

リクエスト

POST /v0/catalogs/{catalogId}/uploads

リクエスト本文の例

{
  "numberOfUploadParts": 2
}

応答

正常に完了すると、作成が成功したことを表すコード201とupload（v0）オブジェクトが返されます。uploadオブジェクトのパラメーター（v0）を参照してください。

応答本文の例

{
  "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
    }
  ]
}

応答コード

アップロードを実行する（v0）

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

リクエスト

POST /v0/catalogs/{catalogId}/uploads/{uploadId}

リクエスト本文の例

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

応答

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

応答コード

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

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

リクエスト

GET /v0/catalogs/{catalogId}/uploads?maxResults={num}&nextToken={token}

リクエスト本文はありません。

応答

正常に完了すると、コード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"
    }
  ]
}

応答コード

指定したアップロードについての情報を取得する（v0）

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

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

リクエスト

GET /v0/catalogs/{catalogId}/uploads/{uploadId}

リクエスト本文はありません。

応答

コード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オブジェクトのパラメーター（v0）

応答コード

独自ホスティングドメイン用のアップロードを作成する（v1）

カタログの新しいアップロードを作成し、アップロードを追跡するためのLocationヘッダーに相対URLを返します。

リクエスト

POST /v1/catalogs/{catalogId}/uploads

リクエスト本文

リクエスト本文には、独自ホスティングURLが含まれます。Alexa-hosted URLを使用する場合は、1つ以上のパートを参照する署名済みURLオブジェクトが含まれます。カタログが5GBより大きい場合は、マルチパートを使用してアップロードしてください。

独自ホスティングURLのリクエスト本文の例

{
    "location": "string"
}

署名済みURLのリクエスト本文の例

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

応答

正常に完了すると、コード202が返され、アップロードを追跡するためのLocationヘッダーに相対URLが設定されます。

応答コード

指定したアップロードについての情報を取得する（v1）

指定したカタログ用に作成されたアップロードに関する詳細情報を取得します。

リクエスト

GET /v1/catalogs/{catalogId}/uploads/{uploadId}

リクエスト本文はありません。

応答

正常に完了すると、コード200のほかに、アップロードの取り込みステップ、ファイルをダウンロードするURLを含むオブジェクトが返されます。

{
  "id": "string",
  "catalogId": "string",
  "status": "PENDING",
  "createdDate": "2019-10-04T00:37:13.593Z",
  "lastUpdatedDate": "2019-10-04T00:37:13.593Z",
  "file": {
    "downloadUrl": "string",
    "expiresAt": "string",
    "status": "PENDING"
  },
  "ingestionSteps": [
    {
      "name": "UPLOAD",
      "status": "PENDING",
      "logUrl": "string",
      "violations": [
        {
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

応答コード

カタログコンテンツをアップロードするURLを生成する（v1）

カタログコンテンツをアップロードできるAlexa-hosted URLを生成します。カタログを作成し、独自ホスティングドメインまたはAlexa-hostedドメインにアップロードするの説明に従って、生成されたURLと付随するパート番号を使用し、マルチパートアップロードを実行できます。

リクエスト

POST /v1/catalogs/{catalogId}/urls

リクエスト本文の例

{
  "numberOfUploadParts": 2
}

応答

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

応答本文

{
  "urlId": "string",
  "preSignedUploadParts": [
    ...
    {
      "url": "string",
      "partNumber": integer,
      "expiresAt": "string"
    }, ...
  ]
}

応答コード