更新ジョブの管理
このドキュメントに記載しているAPIを使うと、参照ベースのカタログを自動更新するジョブの作成と管理ができます。参照ベースのカタログの詳細については、参照ベースのカタログ管理を参照してください。
このドキュメントでは、定義可能な2種類のジョブについて説明します。 CatalogAutoRefreshはカタログの更新、ReferencedResourceVersionUpdateはスロットタイプと対話モデルの更新に使用します。
実行とは、ジョブの実行時間とステータスを持つリソースの種類です。たとえば、CatalogAutoRefreshジョブの実行には、ジョブの開始時刻を示すタイムスタンプと実行状態を示すステータスが含まれます。実行は、ジョブの作成時および前回の実行終了時に自動でスケジュールされます。ジョブのすべての実行について、詳細を確認できます。また、ジョブの次回の実行をキャンセルすることもできます。
SMAPI操作のエンドポイントは、https://api.amazonalexa.comです。すべてのリクエストには、Authorization
ヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。
関連トピック: Alexa Skills KitコマンドラインインターフェースとAlexaスキル管理APIの概要
ジョブ定義を作成する
2種類のジョブ定義を作成できます。 CatalogAutoRefreshとReferencedResourceVersionUpdateです。たとえば、typeにCatalogAutoRefreshをセットしてこのAPIを使用すると、カタログIDとカタログの更新頻度を指定できます。スキルでは、カタログが更新されるたびに更新をトリガーする参照エンティティを指定できます。スキルは、typeにReferencedResourceVersionUpdateを設定してこのAPIを使うことで、カタログIDをスキルIDにリンクできます。
共有スロットを持つスキルの場合は、このAPIを2回呼び出します。2回とも、typeにはReferencedResourceVersionUpdateを設定します。1回目の呼び出しでは、カタログIDをスロットIDにリンクします。2回目で、スロットIDをスキルIDにリンクします。
リクエスト
POST /v1/skills/api/custom/interactionModel/jobs
CatalogAutoRefreshの本文
{
"vendorId": "String",
"jobDefinition": {
"type": "CatalogAutoRefresh",
"resource": {
"id": "String",
"type": "Catalog"
},
"trigger": {
"type": "Schedule",
"hour": Integer,
"dayOfWeek": Integer
},
"status": "Enum"
}
}
CatalogAutoRefreshリクエスト本文のパラメーター
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
vendorId |
ベンダーIDは、https://developer.amazon.com/mycid.htmlで確認できます。 | 文字列 | ◯ |
jobDefinition.type |
"CatalogAutoRefresh" | 文字列 | ◯ |
resource.id |
リソースのIDです。 | 文字列 | ◯ |
resource.type |
"Catalog"、"SlotType"、"InteractionModel"のいずれかです。 | 文字列 | ◯ |
trigger.type |
"Schedule" | 文字列 | ◯ |
trigger.hour |
実行の開始時間です。0、4、8、12、16、20のいずれかに設定します。 | 整数 | ◯ |
trigger.dayOfWeek |
曜日です。週次でジョブを実行する場合はこの値を指定します。指定しない場合、デフォルトではジョブが毎日実行されます。 | 整数 | 週次スケジュールの場合は必須です。 |
status |
"ENABLED"に設定するか、nullのままにします。 | 列挙 | ✕ |
ReferencedResourceVersionUpdateの本文
{
"vendorId": "String",
"jobDefinition": {
"type": "ReferenceVersionUpdate",
"resource": {
"type": Enum,
"id": "String",
"locales": ["String"]
},
"references": [
{
"type": Enum,
"id": "String"
}
],
"trigger": {
"type": "ReferencedResourceJobsComplete"
},
"publishToLive": Boolean,
"status": "Enum"
}
}
ReferencedResourceVersionUpdateリクエスト本文のパラメーター
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
vendorId |
ベンダーIDは、https://developer.amazon.com/mycid.htmlで確認できます。 | 文字列 | ◯ |
resource.id |
リソースのIDです。 | 文字列 | ◯ |
resource.type |
"Catalog"、"SlotType"、"InteractionModel"のいずれかです。 | 文字列 | ◯ |
resource.locales |
デフォルトは、指定のスキルを利用可能なすべてのロケールです。 | 文字列 | ✕ |
references |
"resource"フィールドが依存する参照リソースです。 | リソースの配列 | ✕ |
publishToLive |
更新した対話モデル(InteractionModel)を公開するかどうかを指定します。 | ブール値 | ◯ |
status |
"ENABLED"に設定するか、nullのままにします。 | 列挙 | ✕ |
応答
HTTP/1.1 200 OK
/v1/skills/api/custom/interactionModel/jobs/{jobId}
応答のjobIdは、"amzn1.ask.jobId.$(UUID)"の形式で記述されます。UUIDは16オクテット(128ビット)です。例:amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367
例外
HTTP/1.1 400 Validation Error
{
"errors": [
{
"code": "String",
"message": "String"
}
]
}
コード | メッセージ |
---|---|
INVALID_JOB_DEFINITION | ジョブ定義が有効ではありません。 |
INVALID_JOB_TYPE | 作成後にジョブの種類を変更できません。 |
INVALID_CATALOG_TYPE | カタログの種類はジョブ定義と互換性がありません。たとえば、カタログに自動的に情報を取得できるURLが含まれていません。 |
DUPLICATE_JOB_DEFINITION | 指定されたentityIdが関連付けられた同じ種類のジョブが既に存在します。 |
EXCEEDED_JOB_NUMBER_LIMIT | ジョブ数の上限(20件)を超えています。 |
INVALID_DEPENDENCY | 参照リストに、ジョブのメインリソースで参照されていないリソースが含まれています。 |
TIME_WINDOW_UNAVAILABLE | 指定した時間範囲はいっぱいです。別の時間範囲を指定してください。 |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
ジョブ定義を読み取る
リクエスト
GET /v1/skills/api/custom/interactionModel/jobs/{jobId}
リクエストパスのjobIdは、ジョブ定義の識別子です。必須です。
応答
CatalogAutoRefreshの応答
{
"type": "CatalogAutoRefresh",
"resource": {
"id": "String",
"type": Enum
},
"trigger": {
"type": "Schedule",
"hour": Integer,
"dayOfWeek": Integer
},
"status": Enum
}
ReferenceVersionUpdateの応答
{
"type": "ReferenceVersionUpdate",
"resource": {
"type": Enum,
"id": "String"
},
"references": [
{
"type": Enum,
"id": "String"
}
],
"trigger": {
"type": "ReferencedResourceJobsComplete"
},
"publishToLive": Boolean,
"status": Enum
}
例外
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
ベンダーIDのジョブ一覧を取得する
リクエスト
GET /v1/skills/api/custom/interactionModel/jobs?vendorId=vendorId&maxCount=maxCount&nextToken=nextToken
パスのパラメーター
パラメーター | 説明 | 必須 |
---|---|---|
maxCount | ページごとに返すジョブの最大数です。デフォルトは50です。 | ✕ |
nextToken | 次のページの取得に使用するトークンです。 | ✕ |
応答
応答本文
{
"jobs": [{
"jobId": "String",
"jobType": Enum,
"status": Enum
}
],
"paginationContext": {
"nextToken": "String"
},
"_links": {
"next": {
"href": "String"
},
"self": {
"href": "String"
}
}
}
ステータスは、SUCCESS、FAILURE、IN_PROGRESS、SCHEDULED、CANCELEDのいずれかです。
例外
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
ジョブを削除する
リクエスト
DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}
応答
HTTP/1.1 204 Success
The response to this operation doesn't have any content.
例外
コード | メッセージ |
---|---|
JOB_IN_USE | ほかのジョブがこのジョブに依存しています。依存するジョブを更新または削除してからやり直してください。 |
ON_GOING_EXECUTION | ジョブは現在実行中です。後でもう一度試してください。 |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
実行履歴のリストを取得する
この操作では、指定したジョブの実行履歴のリストを取得します。
リクエスト
GET /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions?maxCount=maxCount&sortDirection=asc&nextToken=nextToken
パスのパラメーター
パラメーター | 説明 | 必須 |
---|---|---|
jobId | ジョブ定義のIDです。 | ◯ |
maxCount | ページごとに返す結果の最大数です。デフォルトは50です。 | ✕ |
nextToken | 次のページの取得に使用するトークンです。 | ✕ |
sortDirection | 結果の並べ替え方法です。executionTimestampフィールドに基づいて並べ替えられます。昇順の場合は"asc"を、降順の場合は"desc"を指定します。 | ✕ |
応答
HTTP/1.1 20O OK
応答本文
{
"executions": [{
"executionId": "String",
"executionTimestamp": "String", //ISO-8601
"errorCode": "String",
"status": Enum,
"errorDetails": {
"executionMetadata": [{
"jobId": "String",
"errorCode": "String",
"status": Enum
},
{
"jobId": "String",
"errorCode": "String",
"status": Enum
}]
}
}
],
"paginationContext": {
"nextToken": "String"
},
"_links": {
"next": {
"href": "String"
},
"self": {
"href": "String"
}
}
}
応答本文のパラメーター
パラメーター | 説明 |
---|---|
executionTimestamp | 実行開始の予定時間です。過去の時間を指定することもできます。 |
status | 更新ジョブの現在のステータスです。有効な値は、 SUCCESS、FAILURE、IN_PROGRESS、SCHEDULEDです。 |
errorCode | ステータスがFAILUREの場合、このエラーコードにはその詳細が入ります。 |
executionMetadata | サブ実行の詳細です。 |
jobId | 実行ジョブのIDです。 |
例外
HTTP/1.1 400
コード | メッセージ | リソースの状態 |
---|---|---|
ON_GOING_BUILD | エンティティが構築中でリトライ期間を過ぎたため、実行に失敗しました。 | 開発中のモデルは更新されませんでした。 |
INTERNAL_ERROR | システムエラーのため、ジョブが失敗しました。 | 公開中スキルのモデルは更新されませんでした。開発中のモデルが更新されたかどうかを確認するには、開発中ステージの最新バージョンの説明を探してください。 |
INVALID_REQUEST | 400エラー"_error_code_from_service"のため、更新リクエストが却下されました。 | 開発中のモデルは更新されませんでした。 |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
次回の実行をキャンセルする
指定されたジョブの次回の実行をキャンセルします。
リクエスト
DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions/{executionId}
パスのパラメーター
パラメーター | 説明 |
---|---|
jobId | ジョブ定義のIDです。 |
executionId | 最新の実行のIDである必要があります。最新でない場合は例外が発生します。 |
応答
HTTP/1.1 204 Accepted
例外
HTTP/1.1 400
{
"errors": [
{
"code": "String",
"message": "String"
}
]
}
コード | 説明 |
---|---|
INVALID_JOB_TYPE | キャンセルが可能なジョブの種類は、CatalogAutoRefresh のみです。 |
INVALID_EXECUTION | ジョブが無効か、実行が既にキャンセルまたは削除されているため、この実行をキャンセルできません。 |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
ジョブを有効/無効にする
リクエスト
PUT /v1/skills/api/custom/interactionModel/jobs/{jobId}/status
リクエスト本文
{
"status": Enum
}
パスのパラメーター
パラメーター | 説明 | 必須 |
---|---|---|
jobId | ジョブ定義のIDです。 | ◯ |
status | ENABLED、DISABLEDのいずれかです。 | ◯ |
応答
HTTP/1.1 204 Accepted
例外
HTTP/1.1 400
{
"errors": [
{
"code": "String",
"message": "String"
}
]
}
コード | 説明 |
---|---|
INVALID_JOB_STATUS | ジョブのステータスが定義されていません。ENABLED、DISABLEDのいずれかのみを指定します。 |
INVALID_EXECUTION | ジョブが無効か、実行が既にキャンセルまたは削除されているため、この実行をキャンセルできません。 |
HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.
HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
Request limit exceeded.Throttling criteria include total requests per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Last updated: Sep 23, 2020