Template を編集する
ID または名前を指定して、既存の Template を更新します。
https://api2.transloadit.com/ templates/ {templateIdOrName}TEMPLATE_ID_OR_NAME で指定される Template を更新します。省略されたトップレベルの設定は通常変更されないため、以下のリクエスト例では Instructions を変更せずに Template の名前を変更します。
template を指定すると、保存されている Instructions 全体が置き換えられます。個々の Steps をマージしたり、パッチを適用したりすることはありません。そのオブジェクトには、保持したいすべての Steps と Instructions を含めてください。
Cron スケジューリングは、アクセス制御されたプレビュー機能です。参加する各 Workspace で 1 つの Template を有効にでき、UTC の 1 日あたりに受け付けられるティックは最大 10,000 回です。cron_enabled を true に設定する前に、cron_region、6 フィールドの cron_schedule_with_seconds、cron_auth_key_id を指定してください。選択した Auth Key は、この Workspace に属し、Assembly の作成を許可している必要があります。また、有効なスケジュールを有効化または編集する場合、呼び出し元にも Assembly の作成権限が必要です。スケジューリングの無効化には Assembly の作成権限は必要ありません。スケジューリングが利用できなくなった場合、または Workspace がプレビューへのアクセス権を失った場合、通常の Template 編集によってスケジューリングは自動的に無効になりますが、リージョン、スケジュール、Auth Key ID、既存の実行は保持されます。Template を無効にするか、その Workspace、リージョン、またはスケジューラーを一時停止すると、以後のティックの受け付けが停止します。すでに永続的に受け付けられたティックは、その後も完了する可能性があります。
スケジュールは UTC で実行され、連続するすべてのティックの間隔を 10 秒以上に保つ必要があります。Instructions では自己完結した HTTP または S3 のインポートを使用する必要があり、:original または /upload/handle を通じてアップロードされたファイルに依存することはできません。スケジュール実行される Assemblies は、最大 1,000 個の入力ファイルをインポートし、max_number_of_files にそれより低い上限が記述されている場合は、その上限に従います。実行に関する変更は、次に到来するティックで有効になります。実行されなかったティックはスキップされます。cron_max_concurrent_runs のデフォルトは 1 です。スケジュールによる同時実行を許可するには、最大 10 まで増やしてください。保留中の開始と未解決の実行は、Template の編集や無効化と再有効化のサイクルをまたいで、この上限に算入されます。上限に達すると、ティックは結果と理由がともに overlap としてスキップされます。後で実行するためにキューに入れられることはありません。上限を引き下げても、既存の実行はキャンセルされません。手動の Assemblies はこの上限に算入されず、通常の Workspace の制限は引き続き適用されます。この設定は、インポートされたファイルの重複を排除しません。Assembly チェックポイントのない消費済みの開始は、設定可能なタイムアウトに達するまでスロットを保持します。このタイムアウトのデフォルトは 10 分です。その後、理由 start_checkpoint_missing で lost とマークされ、以後のティックを実行できるようになります。そのティックが再試行されることはありません。クラッシュしたスケジュール実行の Assembly は再試行されません。その実行は理由 crashed_not_retried で failed とマークされ、重複実行枠を直ちに解放します。Assembly はクラッシュ状態のままで、通常のエラー Notification を送信します。次のスケジュール実行は通常どおり進みます。中止または失敗した Assemblies は、それらの Jobs が終了するまで重複実行枠を保持します。最終チェックポイントが届かない場合は、Workspace の Assembly の最大存続時間にチェックポイントの猶予期間を加えた時間が経過すると期限切れになり、クラッシュとしてマークされ、中止または失敗した処理を再試行せずに重複実行枠を解放します。遅れて届いた Assembly チェックポイントは、保持されている結果を理由 start_checkpoint_late で修正します。lost になった実行は、スロットを恒久的に解放します。そのため、遅延した Assembly によって、デフォルトの 1 を含め、設定された上限を一時的に超える可能性があります。これは厳密な実行ミューテックスではありません。
リクエスト例
TEMPLATE_ID_OR_NAME を、パーセントエンコードせずにリソースの値に設定してください。
curl が利用でき、TRANSLOADIT_TOKEN に適切な Bearer トークン が設定されているサーバー側のシェルで、このリクエストを実行してください。トークンが必要な場合は、以下のセットアップを展開してください。
Bearer トークンが必要ですか?
curl と jq が利用できる信頼できるサーバー側のシェルで、TRANSLOADIT_KEY と TRANSLOADIT_SECRET に、それぞれ Auth Key と Auth Secret を設定してください。両方の認証情報と生成されたトークンは秘密にしてください。このセットアップをブラウザーのコードで実行しないでください。
まず、このエンドポイントで必要なスコープを持つトークンを作成します。Auth Key には、すでにそれらのスコープが付与されている必要があります。
if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
--request POST \
--url 'https://api2.transloadit.com/token' \
--user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'aud=api2' \
--data-urlencode 'scope=templates:write')"; then
printf '%s\n' "$TOKEN_RESPONSE" >&2
exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
jq -er '.access_token | strings | select(length > 0)')" || exit 1
このシェルを開いたまま、以下のリクエストを実行してください。トークンが有効な間は、再利用してください。
curl --fail-with-body -sS --request PUT \
--url "https://api2.transloadit.com/templates/${TEMPLATE_ID_OR_NAME:?Set TEMPLATE_ID_OR_NAME}" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"name":"resized-images"}'
認証
このエンドポイントは、署名付きの params または Bearer トークンを受け付けます。設定手順については、認証を参照してください。
Auth Key または Bearer トークンに必要なスコープ: templates:write。
Signature 付きリクエストには、signature と、将来の時刻を示す params.auth.expires タイムスタンプの両方が必要です。Bearer トークンには、どちらも必要ありません。
パスパラメーター
templateIdOrName(パスセグメント)、必須。パターン:^[a-z0-9-]+$, 最小長: 1
フォームフィールド
コンテンツタイプ: application/x-www-form-urlencoded
params(JSON 文字列)、必須。JSON エンコードされたオブジェクトで、サポートされるキーは以下のとおりです。signature(文字列)。署名付きリクエストでは必須です。Bearer トークンを使用する場合は、このフィールドを省略してください。
params フィールド内でサポートされるキー
この一覧の認証フィールドは、署名付きリクエストに適用されます。Bearer トークンを使用する場合は、params.auth と、それとは別の signature フィールドを省略できます。以下の認証方式ごとのリクエストパラメーターを比較してください。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
| フィールド | 型と説明 | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params. | "1day" | "30days" | "7days" | "90days" | "NoSave"この Template から作成された Assemblies の Assembly Status を保持する期間を制御します。 | ||||||||||||||||||||||||||||||||||||
params.署名付きリクエストでは必須。Bearer トークンを使用する場合は任意 | Template リクエスト用の Transloadit API キーと Signature Authentication のメタデータを含みます。
| ||||||||||||||||||||||||||||||||||||
params.必須 | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 | ||||||||||||||||||||||||||||||||||||
params.必須 | stringリクエストの認証に使用する Transloadit API キー | ||||||||||||||||||||||||||||||||||||
params. | string | nullこの Workspace に属し、Assemblies の作成権限を持つ、アクティブで有効期限内の Auth Key の ID。Cron Template のプレビューを有効にする場合に必須です。このキーは署名を許可している必要があり、内部キーであってはなりません。 検証パターン(正規表現)^[a-f0-9]{32}$ | ||||||||||||||||||||||||||||||||||||
params. | booleanCron Template のプレビューを有効または無効にします。有効化、または有効なスケジュールの編集には、呼び出し元に Assembly の作成権限が必要です。省略した場合、スケジューリングが引き続き利用可能であれば現在の設定が維持されますが、プレビューへのアクセスが取り消されている場合は、通常の編集によってスケジューリングが自動的に無効になります。利用条件を満たす各 Workspace では、Cron Template を 1 つ有効にできます。Instructions は自己完結している必要があり、 | ||||||||||||||||||||||||||||||||||||
params. | integer (最小値: 1, 最大値: 10)この Template のスケジュール実行の最大同時実行数。作成時のデフォルトは 1 です。更新時に省略すると、保存済みの上限が維持されます。上限に達している場合、定期実行のトリガーはキューに入れられず、スキップされます。開始待ちの実行と未解決の実行は、完了するかチェックポイント喪失のタイムアウトに達するまでカウントされます。失われた実行のスロットは恒久的に解放されるため、遅延した Assembly によって一時的にこの上限を超えることがあります。インポートされたファイルの重複排除や、手動の Assemblies の制限は行いません。通常の Workspace の制限は引き続き適用されます。 | ||||||||||||||||||||||||||||||||||||
params. | "ap-southeast-1" | "eu-west-1" | "us-east-1" | nullスケジュールされた Assemblies に使用するリージョン API。Cron Template のプレビューを有効にする場合に必須です。 | ||||||||||||||||||||||||||||||||||||
params. | string | null (最小長: 1, 最大長: 255)UTC で評価される、6 フィールドの数値形式の cron 式です。各フィールドは、秒、分、時、日、月、曜日を表します。ワイルドカード、カンマ区切りの値、範囲、ステップに対応しています。スケジュール上の実行タイミングは、10 秒以上離れている必要があります。cron による Template のスケジューリングは、アクセス制御されたプレビュー機能です。 | ||||||||||||||||||||||||||||||||||||
params. | string (最小長: 3, 最大長: 200)この Template の名前。小文字のラテン文字、数字、またはハイフンを 3–200 文字使用してください。 検証パターン(正規表現)^(?:[a-su-z0-9-][a-z0-9-]{2,199}|t[a-ln-z0-9-][a-z0-9-]{1,198}|tm[a-oq-z0-9-][a-z0-9-]{0,197}|tmp[a-z0-9-]{1,197})$ | ||||||||||||||||||||||||||||||||||||
params. | string | integer各 Signature を一意にし、Signature の意図しない再利用を防ぐために、署名付きリクエストのパラメーターに含める一意のランダムな値。 | ||||||||||||||||||||||||||||||||||||
params. | 0 | 1Auth Key を使用してこの Template から Assemblies を作成する際に、有効な Signature を必須にするには、 | ||||||||||||||||||||||||||||||||||||
params. | object | stringこの Template に保存されている Assembly Instructions。構造化された JSON オブジェクトを優先して使用してください。互換性のため、JSON エンコードされた文字列も引き続き受け付けます。 次のいずれかのスキーマが適用される場合があります: objectこの Template に保存されている構造化された Assembly Instructions。
stringstringクライアントとの互換性のために保持されている、JSON エンコードされた Assembly Instructions。 検証パターン(正規表現)^[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*\{(?:[^\x00]|\x00)*\}[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*$ | ||||||||||||||||||||||||||||||||||||
params. | "1day" | "NoSave"この Template から作成される Assemblies のトランスコード結果を保持する期間を制御します。 |
認証方式別のリクエストパラメーター
署名付き params
Auth Key を params.auth.key として含めてください。リクエストに署名する場合は、将来の時刻を示す params.auth.expires タイムスタンプを含め、Signature を別の signature フィールドで送信してください。以下のフィールド定義では、params 内のパスを使用しています。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.assembly_status_expiry, params.auth, params.cron_auth_key_id, params.cron_enabled, params.cron_max_concurrent_runs, params.cron_region, params.cron_schedule_with_seconds, params.name, params.nonce, params.require_signature_auth, params.template, params.transcoding_result_expiry
Bearer トークンを使用する場合
Bearer トークンを Authorization ヘッダーで送信してください。params.auth と、それとは別の signature フィールドは省略できます。他の必須パラメーターの要件は引き続き適用されます。以下のフィールド定義では、params 内のパスを使用します。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.assembly_status_expiry, params.cron_auth_key_id, params.cron_enabled, params.cron_max_concurrent_runs, params.cron_region, params.cron_schedule_with_seconds, params.name, params.nonce, params.require_signature_auth, params.template, params.transcoding_result_expiry
| フィールド | 型と説明 |
|---|---|
params. | Template リクエスト用の Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params. | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params. | stringリクエストの認証に使用する Transloadit API キー |
レスポンス
レスポンスボディの例を以下に示します:
{
"assembly_status_expiry": null,
"content": {
"steps": {
"resize": {
"robot": "/image/resize",
"use": ":original",
"width": 320
}
}
},
"id": "8fc3b9166c784afd824acf24269ebd11",
"message": "Your Template was successfully updated.",
"name": "resized-images",
"ok": "TEMPLATE_UPDATED",
"require_signature_auth": 0,
"transcoding_result_expiry": null
}2xx 成功
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには、このオブジェクトについて記載されているフィールドのみが含まれます。
| フィールド | 型と説明 |
|---|---|
assembly_status_expiry必須 | null | string |
content必須 | object | Array<任意の値> | string | number | boolean | null次のいずれかのスキーマが適用される場合があります: objectobject追加プロパティのスキーマ任意の値Array<任意の値>Array<任意の値>配列要素のスキーマ任意の値stringnumberbooleannull |
cron_auth_key_id | string | null検証パターン(正規表現)^[a-f0-9]{32}$ |
cron_enabled | boolean |
cron_max_concurrent_runs | integer (最小値: 1, 最大値: 10) |
cron_region | "ap-southeast-1" | "eu-west-1" | "us-east-1" | null |
cron_schedule_with_seconds | string | null (最小長: 1, 最大長: 255) |
id必須 | string次のいずれかのスキーマが適用される場合があります: バリアント 1: string (最大長: 32)string検証パターン(正規表現)^[\x00-\x7F]*$バリアント 2: string (最大長: 32)string検証パターン(正規表現)^builtin\/[a-z0-9-]+(?:@[0-9a-z.-]+)?$ |
message必須 | string (最小長: 1) |
name必須 | string (最小長: 1, 最大長: 255) |
ok必須 | string (常に: "TEMPLATE_UPDATED") |
require_signature_auth必須 | 0 | 1 |
transcoding_result_expiry必須 | null | string |
エラーレスポンス
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
assembly_id | string |
error | string (最小長: 1) |
http_code | number | string
|
message | string人が読んで理解できる形式のエラー説明です。文言は変わる場合があるため、特定の失敗を処理する際は |
reason | null | string | number | boolean | Array<任意の値> | object次のいずれかのスキーマが適用される場合があります: nullstringnumberbooleanArray<任意の値>Array<任意の値>配列要素のスキーマ任意の値objectobject追加プロパティのスキーマ任意の値 |
HTTP 400
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "TEMPLATE_VALIDATION_ERROR"
Template が検証に合格しませんでした。
レスポンスには追加のフィールドが含まれる場合があります。