更新ジョブの管理



更新ジョブの管理

このドキュメントに記載している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