更新ジョブの管理

Note: Sign in to the developer console to build or publish your skill.

更新ジョブの管理

このドキュメントに記載しているAPIを使うと、参照ベースのカタログを自動更新するジョブの作成と管理ができます。参照ベースのカタログの詳細については、参照ベースのカタログ管理を参照してください。

このドキュメントでは、定義可能な2種類のジョブについて説明します。 CatalogAutoRefreshはカタログの更新、ReferencedResourceVersionUpdateはスロットタイプと対話モデルの更新に使用します。

実行とは、ジョブの実行時間とステータスを持つリソースの種類です。たとえば、CatalogAutoRefreshジョブの実行には、ジョブの開始時刻を示すタイムスタンプと実行状態を示すステータスが含まれます。実行は、ジョブの作成時および前回の実行終了時に自動でスケジュールされます。ジョブのすべての実行について、詳細を確認できます。また、ジョブの次回の実行をキャンセルすることもできます。

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

ジョブ定義を作成する
ジョブ定義を読み取る
ベンダーIDのジョブ一覧を取得する
ジョブを削除する
実行履歴のリストを取得する
次回の実行をキャンセルする
ジョブを有効／無効にする

ジョブ定義を作成する

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