新しい Template を作成する
Assembly Instructions から再利用可能な Template を作成します。
https://api2.transloadit.com/ templatesコピーを含む新しい Templates は、常に Cron スケジューリングが無効な状態で作成されます。対象となる Workspace では、Template の作成時に cron リージョン、UTC スケジュール、Auth Key ID を保存し、これらの設定を確認した後、別の更新でスケジューリングを明示的に有効にできます。
リクエスト例
TRANSLOADIT_TOKEN に適切な Bearer トークン を設定し、curl を使用してサーバー側のシェルでこのリクエストを実行してください。トークンが必要な場合は、以下のセットアップを展開してください。
Bearer トークンが必要ですか?
curl と jq を使用できる信頼できるサーバー側のシェルで、TRANSLOADIT_KEY に Auth Key を、TRANSLOADIT_SECRET に 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 POST \
--url "https://api2.transloadit.com/templates" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"name":"resize-images","template":{"steps":{"resize":{"robot":"/image/resize","use":":original","width":320}}}}'
認証
このエンドポイントは、署名付きの params または Bearer トークンを受け付けます。設定手順については、認証を参照してください。
Auth Key または Bearer トークンに必要なスコープ: templates:write。
Signature 付きリクエストには、signature と、将来の時刻を示す params.auth.expires タイムスタンプの両方が必要です。Bearer トークンには、どちらも必要ありません。
フォームフィールド
コンテンツタイプ: 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. | boolean (デフォルト: false)新しい Templates とコピーは、このフィールドが true の場合も含め、常にスケジューリングが無効な状態で作成されます。その Template のリージョン、スケジュール、Instructions、Auth Key を確認した後、別途 Template を更新してスケジューリングを有効にしてください。 | ||||||||||||||||||||||||||||||||||||
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 | 1 (デフォルト: 0)Auth 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 created.",
"name": "resize-images",
"ok": "TEMPLATE_CREATED",
"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_CREATED") |
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 が検証に合格しませんでした。
レスポンスには追加のフィールドが含まれる場合があります。