Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Alexa Catalog Management

Certain voice model APIs support uploading your catalog content to Alexa. This allows the Alexa voice model to dynamically resolve customer utterances according to the catalog data as part of your Alexa skill. Therefore, you can improve the customer experience for your skill by using the Alexa Catalog API to upload your content catalog to Alexa.

API endpoint and header

The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

Process to create a catalog

Use the following process to create a catalog, associate it with a skill, and then add content to it:

  1. Create a catalog.
  2. Associate the catalog with a skill. A catalog can be associated with zero, one, or multiple skills. You must associate the catalog with a skill before beginning uploads to the catalog.
  3. Create an upload to get the uploadId and one or more presigned URLs to use for uploading the catalog.
  4. Upload the catalog to Amazon S3 using the presigned URL or URLs that you got in the previous step. To upload the catalog, send a PUT request to the presigned URL (or URLs when using multipart upload), with the catalog (or catalog part) in the body of the request. The response to each PUT request contains an ETag value in the ETag header. You need this ETag value to complete the upload in the following step.

    You can optionally use multipart upload to upload a large catalog.

    • Single upload – For a catalog that is 5 GB or less, you can send one PUT request to the presigned URL to upload the entire catalog.
    • Multipart upload – Multipart upload can help improve the upload experience for large catalogs, because you can upload the catalog in parts instead of all at once. For a catalog that is 5 MB or more, you can optionally use multipart upload. For a catalog that is more than 5 GB, you must use multipart upload. The total size of the catalog must be less than 5 TB.

      To use multipart upload, split your catalog into parts, each of which is at least 5 MB but no more than 5 GB. The last part can be less than 5 MB. Send a PUT request to the presigned URLs from the previous step, with a different catalog part in the body of each request. You can send these PUT requests independently, in any order, and in parallel.

      Save the ETag values that you receive in the response to each PUT request, then provide them in the following step to complete the upload. After you complete the upload, the parts are assembled back into a single catalog.

  5. Complete the upload by providing the ETags from each of the Amazon S3 uploads completed in the previous step.

Create a catalog

This creates a new catalog based on the basic information provided in the request. When a catalog is created, it does not have any records. The records are uploaded in a separate operation. The catalog is associated with the vendorId that calls the API.

Request

POST /v0/catalogs

Request body

{
  "title": "string",
  "type": "string",
  "usage": "string",
  "vendorId": "string"
}
ParameterDescriptionRequired
titleTitle of the catalog. Yes
typeType of catalog.Yes
usageHow the catalog will be used. Yes
vendorIdUnique identifier of a vendor.Yes

Response

A successful response returns a 201 code and the title of the catalog as a string.

Response codes

CodeDescription
201Created
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Associate a catalog with a skill

This API associates the specified catalog with the specified skill.

Request

PUT /v0/skills/{skillId}/catalogs/{catalogId}
FieldDescriptionParameter TypeRequired
skillIdUnique identifier of the skill.PathYes
catalogIdUnique identifier of the catalog.PathYes

Request body

None.

Response

A successful response returns a 201 code.

Response codes

CodeDescription
201Successfully associated
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get the list of catalogs

Lists all the catalogs associated with a vendorId. The optional maxResults and nextToken values provide paging for the results.

Request

Get catalogs by vendorId

GET /v0/catalogs?vendorId={vendorId}&maxResults={num}&nextToken={token}
FieldDescriptionParameter TypeRequired
vendorIdUnique identifier of the vendor.Query parameterYes
maxResultsMaximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextTokenContinuation token returned in response object of last list skills response. If this is parameter is null, the response will include skills from first set.Query parameterNo

Response

A successful response returns a 200 code and a links object, which provides a link for each returned catalogId, and a catalogs object, which is an array of catalogs, each of which is specified by a unique identifier.

{
  "_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"
      ]
    }
  ]
}
ParameterDescription
_linksHypertext Application Language links to navigate through resources.
isTruncatedValue is true if there is more than one page of results.
nextToken When the response to this API call is truncated (that is, if the isTruncated value is true), the response also includes the nextToken element. The value of nextToken can be used in the next request as the continuation token to list the next set of objects.
catalogsArray that contains catalog objects.

Parameters of links object

ParameterDescription
selfObject containing the URL for the upload.
self.hrefString of the URL for the upload.

Parameters of catalog object

The catalogs object is an array of catalog objects.

ParameterDescription
idUnique identifier for the uploads object.
titleTitle of the catalog.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part was last updated.
associatedSkillIdsArray of skillIds associated with this catalog.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get a particular catalog

Returns the catalog specified by the catalogId.

Request

GET /v0/catalogs/{catalogId}
FieldDescriptionParameter TypeRequired
catalogIdUnique identifier of the catalog. If not included, the entire set of catalogs is returned. PathYes

Response

A successful response returns a 200 code and a catalog object.

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

Parameters for catalog object

ParameterDescription
idUnique identifier for the uploads object.
titleTitle of the catalog.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part was last updated.
associatedSkillIdsArray of skillIds associated with this catalog.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Create an upload

Creates a new upload for a catalog, returning the uploadId and one or more presigned URLs for uploading the catalog.

After calling this API, upload the catalog to Amazon S3 using the presigned URL or URLs that you received in the response. For more information about how to upload a catalog, see Process to create a catalog.

When you finish uploading the catalog, complete the upload by providing the ETag values from each of the Amazon S3 upload requests.

Request

POST /catalogs/{catalogId}/uploads
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes
numberOfUploadPartsSpecifies the number of upload parts, when using multipart upload. For the structure, see the following JSON.BodyRequired when using multipart upload. When this is not included, it defaults to 1.

Request body

{
  "numberOfUploadParts": 2
}

Response

A successful response returns a 201 code to indicate creation was successful.

Response body

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

Response codes

CodeDescription
201Created
400 Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403 The operation being requested is not allowed.
404The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Complete an upload

Completes an upload. Send this request after you upload the catalog to Amazon S3 using presigned URLs. For more information about how to upload a catalog, see Process to create a catalog.

Request

POST /v0/catalogs/{catalogId}/uploads/{uploadId}
FieldDescriptionParameter TypeRequired
catalogId Unique identifier of the catalog.PathYes
uploadId Unique identifier of the upload.PathYes
partETagsA list of ETag (string) and part number (integer) pairs, one for each part of the catalog that was uploaded with multipart upload. For the structure, see the following JSON.BodyRequired when the catalog was uploaded with multipart upload.

Request body

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

Response

A successful response returns a 202 code to indicate the upload was accepted.

Response codes

CodeDescription
202Accepted
400 Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403 The operation being requested is not allowed.
404The resource being requested is not found.
409The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get the list of uploads

Lists the uploads for a particular catalog. An upload is a file that contributes to a catalog, after validation. The optional maxResults and nextToken values provide paging for the results.

Request

GET /v0/catalogs/{catalogId}/uploads?maxResults={num}&nextToken={token}
FieldDescriptionParameter TypeRequired
catalogIdUnique identifier of the catalog.PathYes
maxResultsMaximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextTokenContinuation token returned in response object of last list skills response. If this is parameter is null, the response will include skills from first set.Query parameterNo

Request body

None.

Response

Successful response returns a 200 code and an object that includes links to the upload parts, and a list of the uploads.

{
  "_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"
    }
  ]
}
ParameterDescription
_linksHypertext Application Language links to navigate through resources.
isTruncatedValue is true if there is more than one page of results.
nextToken When the response to this API call is truncated (that is, if the isTruncated value is true), the response also includes the nextToken element. The value of nextToken can be used in the next request as the continuation token to list the next set of objects.
uploadsObject array that lists the details for each upload.

Parameters of links object

ParameterDescription
selfObject containing the URL for the upload.
self.hrefString for the URL for the upload.

Parameters of uploads object

ParameterDescription
idUnique identifier for the uploads object.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, SUCCEEDED.
createdDateDate upload part was created.
lastUpdatedDateDate that the upload part was last updated.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable

Get a particular upload

Gets information about a specific upload for a specific catalog.

The catalogId identifies the catalog, and the uploadId identifies the upload.

Request

GET /v0/catalogs/{catalogId}/uploads/{uploadId}
FieldDescriptionParameter TypeRequired
catalogIdUnique identifier for the catalog.Path parameterYes
uploadIdUnique identifier for the upload.Path parameterYes

Request body

None.

Response

Returns a 200 code and an upload object.

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

Parameters for upload object

ParameterDescription
idUnique identifier for the upload object.
catalogIdUnique identifier for the catalog.
statusStatus of the entire upload. One of: PENDING, PROCESSING, FAILED, or SUCCEEDED.
createdDateDate and time that the upload part was created, in the following format: 2018-10-25T08:25:04.679Z.
lastUpdatedDateDate and time that the upload part was last updated, in the following format: 2018-10-25T08:25:04.679Z.
fileA file object represents a previously uploaded file for a specific catalog.
ingestionStepsAn ingestion step represents a single step in the ingestion process of a new upload.

Parameters for file object

Parameter Description
presignedDownloadUrl A URL where you can download the previously uploaded file.
status The status of the file. One of: PENDING, AVAILABLE, UNAVAILABLE, or PURGED.

Parameters for ingestionSteps object

ParameterDescription
nameIndicates which ingestion step. One of: UPLOAD, SCHEMA_VALIDATION.
statusRepresents the status of the given step in the ingestion process of the upload. One of: PENDING, SUCCEEDED, FAILED, or CANCELLED.
logUrlRepresents the url for the file containing logs of ingestion step.
errorsContains the errors occurred during the execution of step. If execution succeeded, this array is empty.

Response codes

CodeDescription
200Successful operation
400Server cannot process the request due to a client error.
401The auth token is invalid/expired or doesn't have access to the resource.
403The operation being requested is not allowed.
404The resource being requested is not found.
429Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500Internal Server Error
503Service Unavailable