カタログコンテンツのアップロード
特定の音声モデル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つまたは複数のスキルに関連付けることもできますが、カタログをスキルに関連付ける場合は、カタログへのアップロードを開始する前に関連付ける必要があります。
- アップロードを作成(v0)して、カタログのアップロードに使用する
uploadId
と1つまたは複数の署名済みURLを取得します。 -
前の手順で取得した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つのカタログに再構成されます。
- 前の手順で完了した各Amazon S3アップロードのETagを使用して、アップロードを実行します。
- 必要に応じて、指定したアップロードについての情報を取得(v0)します。
- 必要に応じて、カタログリストの取得や、指定したカタログの取得(v0)を行います。
カタログを作成し、独自ホスティングドメインまたはAlexa-hostedドメインにアップロードする
以下のプロセスでは、/v0 APIと/v1 APIを使用して、カタログの作成、スキルへの関連付け、コンテンツの追加、独自ドメインへのアップロードを行います。
- /v0 APIを使用してカタログを作成します。
- /v0 APIを使用してカタログをスキルに関連付けます。カタログはスキルに関連付けなくてもかまいませんし、1つまたは複数のスキルに関連付けることもできますが、カタログをスキルに関連付ける場合は、カタログへのアップロードを開始する前に関連付ける必要があります。
- 独自ホスティングURLにカタログをアップロードする場合、独自ホスティングドメイン用のアップロードを作成する(v1)の手順に従います。
- Alexa-hosted URLにカタログをアップロードする場合、カタログコンテンツをアップロードするURLを生成する(v1)の手順に従います。
- 必要に応じて、指定したアップロードについての情報を取得(v1)します。
- 必要に応じて、カタログリストの取得(v1)や、指定したカタログの取得(v1)を行います。
- 独自ホスティングURLを使用する場合、カタログをそのURLに対応する場所にアップロードします。
-
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"
}
パラメーター | 説明 | 必須 |
---|---|---|
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 | サービスを利用できません。 |
カタログリストを取得する(v0)
vendorId
に関連付けられたすべてのカタログのリストを取得します。オプションのmaxResults
とnextToken
の値により、結果のページ分割を指定します。
リクエスト
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"
]
}
]
}
パラメーター | 説明 |
---|---|
_links
| Hypertext Application Languageリンクで、リソース間を移動するために使用します。 |
_links.self
| アップロードのURLを含むオブジェクトです。 |
_links.self.href
| アップロードのURL文字列です。 |
isTruncated
| 結果が複数ページの場合、値はtrue になります。
|
nextToken
|
このAPI呼び出しへの応答が切り捨てられる(isTruncated の値がtrue )と、応答にもnextToken 要素が含まれます。nextToken の値は、オブジェクトの次のセットのリストを表示する継続トークンとして次のリクエストで使用できます。
|
catalogs
| catalogオブジェクトを含む配列です。 |
catalogs.id
| uploads オブジェクトの一意のIDです。
|
catalogs.title
| カタログのタイトルです。 |
catalogs.type
| カタログの種類です。 |
catalogs.usage
| カタログの用途です。 |
catalogs.createdDate
| アップロード部分が作成された日付です。 |
catalogs.lastUpdatedDate
| アップロード部分が最後に更新された日付です。 |
catalogs.associatedSkillIds
| このカタログに関連付けられたskillIdの配列です。 |
応答コード
コード | 説明 |
---|---|
200 | 正常に完了しました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
特定のカタログを取得する(v0)
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オブジェクトのパラメーター
パラメーター | 説明 |
---|---|
id
| uploads オブジェクトの一意のIDです。
|
title
| カタログのタイトルです。 |
type
| カタログの種類です。 |
usage
| カタログの用途です。 |
createdDate
| アップロード部分が作成された日付です。 |
lastUpdatedDate
| カタログが最後に更新された日付です。 |
associatedSkillIds | このカタログに関連付けられたskillIds の配列です。
|
応答コード
コード | 説明 |
---|---|
200 | 正常に完了しました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
アップロードを作成する(v0)
カタログの新しいアップロードを作成し、カタログのアップロードに使用するuploadId
と1つまたは複数の署名済みURLを返します。
このAPIを呼び出した後、応答で受信した1つまたは複数の署名済みURLを使用して、カタログをAmazon S3にアップロードします。カタログをアップロードする方法の詳細については、カタログ作成プロセスを参照してください。
カタログのアップロードが終了したら、各Amazon S3アップロードリクエストで取得したETag値を使用して、アップロードを実行します。
リクエスト
POST /v0/catalogs/{catalogId}/uploads
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
catalogId
| 一意のカタログIDです。 | パス | ◯ |
リクエスト本文の例
{
"numberOfUploadParts": 2
}
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
numberOfUploadParts
| マルチパートアップロードを使用する場合に、アップロードのパート数を指定します。構造については、以下のJSONを参照してください。 | 本文 | マルチパートアップロードを使用する場合は必須です。このパラメーターが含まれていない場合、デフォルト値は1です。 |
応答
正常に完了すると、作成が成功したことを表すコード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
}
]
}
応答コード
コード | 説明 |
---|---|
201 | 作成されました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
アップロードを実行する(v0)
アップロードを実行します。署名済みURLを使用してAmazon S3にカタログをアップロードした後、このリクエストを送信します。カタログをアップロードする方法の詳細については、カタログ作成プロセスを参照してください。
リクエスト
POST /v0/catalogs/{catalogId}/uploads/{uploadId}
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
catalogId
| 一意のカタログIDです。 | パス | ◯ |
uploadId
| 一意のアップロードIDです。 | パス | ◯ |
リクエスト本文の例
{
"partETags": [
{
"eTag": "string",
"partNumber": 1
},
{
"eTag": "string",
"partNumber": 2
}
]
}
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
partETags
|
ETag(文字列)とパート番号(整数)のペアのリストです。マルチパートアップロードでアップロードされたカタログのパートごとに1つあります。構造については、以下のJSONを参照してください。 | 本文 | カタログがマルチパートアップロードでアップロードされた場合は必須です。 |
応答
正常に完了すると、アップデートが受け付けられたことを表すコード202が返されます。
応答コード
コード | 説明 |
---|---|
202 | 受け付けられました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
409 | ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
アップロードリストを取得する(v0)
特定のカタログのアップロードのリストを取得します。アップロードは、検証された後、カタログに取り込まれるファイルになります。オプションのmaxResults
とnextToken
の値により、結果のページ分割を指定します。
リクエスト
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"
}
]
}
パラメーター | 説明 |
---|---|
_links
| Hypertext Application Languageリンクで、リソース間を移動するために使用します。 |
_links.self
| アップロードのURLを含むオブジェクトです。 |
_links.self.href
| アップロードのURL文字列です。 |
_links.next
|
_links.self の後に次のアップロードがある場合、次のアップロードのURLを含むオブジェクトです。_links.self のほかに複数のURLがある場合、_links オブジェクトには、それらの各URLの_links.next オブジェクトが含まれています。
|
_links.next.href
| 次のアップロードのURL文字列です。 |
isTruncated
| 結果が複数ページの場合、値はtrue になります。
|
nextToken
|
このAPI呼び出しへの応答が切り捨てられる(isTruncated の値がtrue )と、応答にもnextToken 要素が含まれます。nextToken の値は、オブジェクトの次のセットのリストを表示する継続トークンとして次のリクエストで使用できます。
|
uploads
| 各アップロードの詳細リストを含むオブジェクト配列です。 |
uploads.id
| uploadsオブジェクトの一意のIDです。 |
uploads.catalogId | カタログの一意のIDです。 |
uploads.status
| アップロード全体のステータスです。次のいずれかになります。 PENDING 、PROCESSING 、FAILED 、SUCCEEDED
|
uploads.createdDate
| アップロード部分が作成された日付です。 |
uploads.lastUpdatedDate
| アップロード部分が最後に更新された日付です。 |
応答コード
コード | 説明 |
---|---|
200 | 正常に完了しました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
指定したアップロードについての情報を取得する(v0)
特定のカタログの指定したアップロードに関する情報を取得します。
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"
}
]
}
]
}
パラメーター | 説明 |
---|---|
id
|
upload オブジェクトの一意のIDです。
|
catalogId
| カタログの一意のIDです。 |
status
|
アップロード全体のステータスです。次のいずれかになります。 PENDING 、PROCESSING 、FAILED 、SUCCEEDED |
createdDate
| アップロード部分が作成された日時です。形式は次のとおりです。 2018-10-25T08:25:04.679Z |
lastUpdatedDate
|
アップロード部分が更新された日時です。形式は次のとおりです。 2018-10-25T08:25:04.679Z |
file
|
file オブジェクトは、特定のカタログの以前にアップロードしたファイルを表します。 |
file.presignedDownloadUrl
|
以前にアップロードしたファイルをダウンロードできるURLです。 |
file.status
|
ファイルのステータスです。次のいずれかになります。 PENDING 、AVAILABLE 、UNAVAILABLE 、PURGED
|
ingestionSteps
|
新しいアップロードの取り込みプロセスの1ステップです。 |
ingestionSteps.name |
取り込みのどのステップかを表します。次のいずれかになります。 UPLOAD , SCHEMA_VALIDATION .
|
ingestionSteps.status |
アップロードの取り込みプロセス内で、特定のステップのステータスを表します。次のいずれかになります。 PENDING 、SUCCEEDED 、FAILED 、CANCELLED
|
ingestionSteps.logUrl
|
取り込みステップのログを含むファイルのURLを表します。 |
ingestionSteps.errors
|
ステップの実行中に発生したエラーを含みます。正常に実行されると、この配列は空になります。 |
応答コード
コード | 説明 |
---|---|
200 | 正常に完了しました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
独自ホスティングドメイン用のアップロードを作成する(v1)
カタログの新しいアップロードを作成し、アップロードを追跡するためのLocation
ヘッダーに相対URLを返します。
リクエスト
POST /v1/catalogs/{catalogId}/uploads
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
catalogId
| 一意のカタログIDです。 | パス | ◯ |
リクエスト本文
リクエスト本文には、独自ホスティングURLが含まれます。Alexa-hosted URLを使用する場合は、1つ以上のパートを参照する署名済みURLオブジェクトが含まれます。カタログが5GBより大きい場合は、マルチパートを使用してアップロードしてください。
独自ホスティングURLのリクエスト本文の例
{
"location": "string"
}
署名済みURLのリクエスト本文の例
{
"preSignedUrl": {
"urlId": "string",
"partETags": [
{
"eTag": "string",
"partNumber": 1
},
{
"eTag": "string",
"partNumber": 2
}
]
}
}
フィールド | 説明 | パラメーターの型 |
---|---|---|
location
|
一意のURL IDです。カタログを独自ホスティングURLにアップロードする場合に使用します。preSignedUrl を使用しない場合は必須です。
| パス |
preSignedUrl
|
マルチパートアップロードの情報を含むオブジェクトです。カタログをAlexa-hosted URLにアップロードする場合に使用します。location を使用しない場合は必須です。
| オブジェクト |
preSignedUrl.urlId
| 一意のURL IDです。preSignedUrl を使用する場合は必須です。
| パス |
preSignedUrl.partETags
|
ETag(文字列)とパート番号(整数)のペアのリストです。マルチパートアップロードでアップロードされたカタログのパートごとに1つあります。構造については、JSONの例を参照してください。カタログがマルチパートアップロードでアップロードされた場合は必須です。 | 本文 |
応答
正常に完了すると、コード202が返され、アップロードを追跡するためのLocation
ヘッダーに相対URLが設定されます。
応答コード
コード | 説明 |
---|---|
202 | 受け付けられました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
指定したアップロードについての情報を取得する(v1)
指定したカタログ用に作成されたアップロードに関する詳細情報を取得します。
リクエスト
GET /v1/catalogs/{catalogId}/uploads/{uploadId}
リクエスト本文はありません。
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
catalogId
|
一意のカタログIDです。 | パス | ◯ |
uploadId
|
一意のアップロードIDです。 | パス | ◯ |
応答
正常に完了すると、コード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"
}
]
}
]
}
パラメーター | 説明 |
---|---|
id
| アップロードの文字列識別子です。 |
catalogId
| カタログの文字列識別子です。 |
status
| アップロード全体のステータスです。次のいずれかになります。 PENDING 、IN_PROGRESS 、FAILED 、SUCCEEDED
|
file
| カタログファイルを表すオブジェクトです。 |
file.downloadUrl
| カタログファイルのダウンロード元URLです。 |
file.expiresAt
| file.downloadUrlの有効期限を示す日時です。 |
file.status
|
ファイルのステータスです。次のいずれかになります。 PENDING 、AVAILABLE 、PURGED 、UNAVAILABLE
|
ingestionSteps
| 取り込みステップを表すオブジェクトです。 |
ingestionSteps.name
| UPLOAD 、SCHEMA_VALIDATION のいずれかです。
|
ingestionSteps.status
| 取り込みステップのステータスです。次のいずれかになります。 PENDING 、IN_PROGRESS 、FAILED 、SUCCEEDED 、CANCELLED
|
ingestionSteps.logUrl
| 取り込みアクティビティのログが含まれるURLです。 |
ingestionSteps.violations
|
取り込みステップに関連するエラーメッセージを含むオブジェクトです。 |
ingestionSteps.violations.code
|
エラーメッセージの数値コードです。 |
ingestionSteps.violations.message
| エラーメッセージの説明です。 |
応答コード
コード | 説明 |
---|---|
200 | 正常に完了しました。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |
カタログコンテンツをアップロードするURLを生成する(v1)
カタログコンテンツをアップロードできるAlexa-hosted URLを生成します。カタログを作成し、独自ホスティングドメインまたはAlexa-hostedドメインにアップロードするの説明に従って、生成されたURLと付随するパート番号を使用し、マルチパートアップロードを実行できます。
リクエスト
POST /v1/catalogs/{catalogId}/urls
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
catalogId
| 一意のカタログIDです。 | パス | ◯ |
リクエスト本文の例
{
"numberOfUploadParts": 2
}
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
numberOfUploadParts
|
カタログを分割して作られたアップロードのパート数です。 | 整数 | ◯ |
応答
作成が正常に完了すると、成功したことを表すコード201とURL情報が本文に返されます。
応答本文
{
"urlId": "string",
"preSignedUploadParts": [
...
{
"url": "string",
"partNumber": integer,
"expiresAt": "string"
}, ...
]
}
フィールド | 説明 |
---|---|
urlId
|
一意のURL IDです。 |
preSignedUploadParts
|
マルチパートアップロードのパートについての情報を含むオブジェクトです。各パートはリスト内の項目で表されます。 |
preSignedUploadParts.url
| 一意のURL IDです。必須です。 |
preSignedUploadParts.expiresAt
|
URLの有効期限を示す日時です。 |
preSignedUploadParts.partNumber
|
アップロードのパート番号を表します。パート番号は1から始まります。 |
応答コード
コード | 説明 |
---|---|
201 | 作成されました。 |
400 | クライアントエラーにより、サーバーがリクエストを処理できません。 |
401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 | リクエストされた操作は許可されていません。 |
404 | リクエストされたリソースが見つかりません。 |
429 | 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。 |
500 | 内部サーバーエラーです。 |
503 | サービスを利用できません。 |