Modifier un Template
Met à jour un Template existant à partir de son ID ou de son nom.
https://api2.transloadit.com/Met à jour le Template représenté par TEMPLATE_ID_OR_NAME. Les paramètres de premier niveau omis restent normalement
inchangés. L’exemple de requête ci-dessous renomme donc le Template sans modifier ses Instructions.
Fournir template remplace intégralement les Instructions enregistrées, sans fusionner ni modifier
les Steps individuellement. Incluez dans cet objet chaque Step et chaque Instruction que vous souhaitez conserver.
La planification cron est une fonctionnalité en préversion dont l’accès est contrôlé. Chaque Workspace participant peut activer un seul
Template, avec au maximum 10 000 déclenchements admis par jour UTC. Fournissez cron_region, un paramètre
cron_schedule_with_seconds à six champs et cron_auth_key_id avant de définir cron_enabled sur true.
L’Auth Key sélectionnée doit appartenir à ce Workspace et autoriser la création d’Assemblies.
L’appelant doit également disposer de l’autorisation de créer des Assemblies lorsqu’il active une planification ou modifie une planification déjà active.
La désactivation de la planification ne nécessite pas l’autorisation de créer des Assemblies. Si la planification devient
indisponible ou si le Workspace perd l’accès à la préversion, une modification ordinaire du Template
désactive automatiquement la planification tout en conservant sa région, son calendrier, son identifiant d’Auth Key et son exécution existante.
La désactivation d’un Template ou la mise en pause de son Workspace, de sa région ou du planificateur empêche les admissions
futures. Un déclenchement dont l’admission a déjà été enregistrée durablement peut encore se terminer.
Les planifications s’exécutent en UTC et doivent maintenir un intervalle d’au moins 10 secondes entre chaque paire de déclenchements
consécutifs. Les Instructions doivent utiliser des importations HTTP ou S3 autonomes et ne peuvent pas dépendre, via :original ou /upload/handle, de fichiers téléversés.
Les Assemblies planifiées importent au maximum 1 000 fichiers d’entrée
et respectent une limite max_number_of_files plus basse si elle est définie dans les Instructions. Les modifications d’exécution prennent effet
au prochain déclenchement futur. Les déclenchements manqués sont ignorés. Le paramètre cron_max_concurrent_runs vaut 1 par défaut ;
augmentez-le jusqu’à 10 pour autoriser des exécutions planifiées simultanées. Les démarrages en attente et les exécutions non résolues
comptent dans cette limite, y compris après des modifications du Template et des cycles de désactivation et de réactivation. Lorsque la limite est atteinte,
les déclenchements sont ignorés avec le résultat et le motif overlap ; ils ne sont pas mis en file d’attente pour plus tard.
Abaisser la limite n’annule pas les exécutions existantes. Les Assemblies manuelles ne sont pas comptabilisées dans cette limite,
et les limites ordinaires du Workspace continuent de s’appliquer. Ce paramètre ne déduplique pas les fichiers importés.
Un démarrage consommé sans point de contrôle d’Assembly conserve son emplacement jusqu’à l’expiration de son
délai configurable, fixé par défaut à 10 minutes. Il est alors marqué lost avec le motif
start_checkpoint_missing, ce qui permet aux déclenchements suivants de se poursuivre. Ce déclenchement ne fait jamais l’objet d’une nouvelle tentative.
Une Assembly planifiée qui a planté ne fait pas l’objet d’une nouvelle tentative. Son exécution est marquée failed avec le motif
crashed_not_retried et libère immédiatement son emplacement de chevauchement. L’Assembly reste dans son état de plantage
et envoie la notification d’erreur habituelle. L’exécution planifiée suivante se déroule normalement.
Les Assemblies interrompues ou en échec conservent leur emplacement de chevauchement jusqu’à la fin de leurs Jobs. Si aucun point de contrôle final
n’arrive, elles expirent après la durée de vie maximale des Assemblies du Workspace, augmentée du délai de grâce du point de contrôle,
puis sont marquées comme ayant planté et libèrent leur emplacement de chevauchement sans nouvelle tentative du traitement interrompu ou en échec.
Un point de contrôle d’Assembly tardif corrige le résultat conservé avec le motif start_checkpoint_late.
Les exécutions lost libèrent définitivement leurs emplacements. Une Assembly tardive peut donc temporairement dépasser
la limite configurée, y compris la valeur par défaut de 1 ; ce mécanisme n’est pas un mutex d’exécution strict.
Exemple de requête
Définissez TEMPLATE_ID_OR_NAME sur la valeur de votre ressource sans lui appliquer d’encodage pour cent.
Exécutez cette requête dans un shell côté serveur avec curl et un jeton porteur approprié dans TRANSLOADIT_TOKEN. Si vous avez besoin d’un jeton, développez les instructions de configuration ci-dessous.
Besoin d’un jeton porteur ?
Dans un shell de confiance côté serveur disposant de curl et de jq, définissez TRANSLOADIT_KEY et TRANSLOADIT_SECRET sur votre Auth Key et votre Auth Secret. Gardez ces deux informations d’identification et le jeton obtenu secrets ; n’exécutez jamais cette configuration dans du code de navigateur.
Commencez par créer un jeton avec les portées requises par ce point de terminaison. Votre Auth Key doit déjà accorder ces portées.
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
Gardez ce shell ouvert et exécutez la requête ci-dessous. Réutilisez le jeton tant qu’il reste valide.
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"}'
Authentification
Ce point de terminaison accepte des params signés ou un jeton porteur. Consultez la section Authentification pour les instructions de configuration.
Portée requise pour l’Auth Key ou le jeton porteur : templates:write.
Les requêtes signées nécessitent à la fois une signature et un horodatage params.auth.expires situé dans le futur. Les jetons porteurs ne nécessitent ni l’un ni l’autre.
Paramètres de chemin
templateIdOrName(segment de chemin), obligatoire. motif :^[a-z0-9-]+$, longueur minimale : 1
Champs de formulaire
Type de contenu : application/x-www-form-urlencoded
params(Chaîne JSON), obligatoire. Un objet encodé en JSON dont les clés prises en charge sont répertoriées ci-dessous.signature(chaîne de caractères). Obligatoire pour les requêtes signées. Omettez ce champ lorsque vous utilisez un jeton porteur.
Clés prises en charge dans le champ params
Les champs d’authentification de cette liste s’appliquent aux requêtes signées. Avec un jeton porteur, vous pouvez omettre params.auth et le champ distinct signature. Comparez les paramètres de requête spécifiques à l’authentification ci-dessous.
Schéma JSON complet
params: Seuls les champs répertoriés pour cet objet sont acceptés.
| Champ | Type et description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params. | "1day" | "30days" | "7days" | "90days" | "NoSave"Définit la durée de conservation de l’Assembly Status pour les Assemblies créées à partir de ce Template. | ||||||||||||||||||||||||||||||||||||
params.obligatoire pour les requêtes signées ; facultatif avec un jeton porteur | Contient la clé API Transloadit et les métadonnées de Signature Authentication pour une requête de Template.
| ||||||||||||||||||||||||||||||||||||
params.obligatoire | stringHorodatage d’expiration au format ISO 8601 situé dans le futur. Obligatoire lorsqu’une requête est signée ou nécessite Signature Authentication ; les requêtes authentifiées par jeton porteur peuvent l’omettre. | ||||||||||||||||||||||||||||||||||||
params.obligatoire | stringClé API Transloadit utilisée pour authentifier les requêtes | ||||||||||||||||||||||||||||||||||||
params. | string | nullID d’une Auth Key active et non expirée appartenant à ce Workspace, avec l’autorisation de créer des Assemblies. Obligatoire lors de l’activation de l’aperçu du Template Cron. La clé doit autoriser la signature et ne peut pas être une clé interne. Motif de validation (expression régulière)^[a-f0-9]{32}$ | ||||||||||||||||||||||||||||||||||||
params. | booleanActive ou désactive la préversion des Templates Cron. L’activation ou la modification d’une planification active exige que l’appelant dispose de l’autorisation de créer des Assemblies. L’omission conserve le réglage actuel tant que la planification reste disponible ; une modification ordinaire désactive automatiquement la planification si l’accès à la préversion est retiré. Chaque Workspace éligible peut activer un Template Cron. Les Instructions doivent être autonomes et utiliser des importations HTTP ou S3, sans | ||||||||||||||||||||||||||||||||||||
params. | integer (minimum : 1, maximum : 10)Nombre maximal d’exécutions planifiées simultanées de ce Template. Vaut 1 par défaut à la création ; lors d’une mise à jour, omettre ce paramètre conserve la limite enregistrée. Les déclenchements qui surviennent lorsque la limite est atteinte sont ignorés, et non mis en file d’attente. Les démarrages en attente et les exécutions non résolues sont comptabilisés jusqu’à leur achèvement ou jusqu’à l’expiration du délai de perte de point de contrôle. Les exécutions perdues libèrent définitivement leur emplacement ; une Assembly tardive peut donc dépasser temporairement cette limite. Ce paramètre ne dédoublonne pas les fichiers importés et ne limite pas les Assemblies manuelles. Les limites habituelles du Workspace continuent de s’appliquer. | ||||||||||||||||||||||||||||||||||||
params. | "ap-southeast-1" | "eu-west-1" | "us-east-1" | nullAPI régionale utilisée pour les Assemblies planifiées. Requise lors de l’activation de l’aperçu des Templates Cron. | ||||||||||||||||||||||||||||||||||||
params. | string | null (longueur minimale : 1, longueur maximale : 255)Expression cron numérique à six champs, évaluée en UTC : seconde, minute, heure, jour du mois, mois et jour de la semaine. Prend en charge les caractères génériques, les valeurs séparées par des virgules, les plages et les pas. Les déclenchements planifiés doivent être espacés d’au moins 10 secondes. La planification des Templates par cron est une fonctionnalité en préversion dont l’accès est contrôlé. | ||||||||||||||||||||||||||||||||||||
params. | string (longueur minimale : 3, longueur maximale : 200)Nom de ce Template. Utilisez 3–200 lettres latines minuscules, chiffres ou tirets. Le nom Motif de validation (expression régulière)^(?:[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 | integerValeur unique et aléatoire incluse dans les paramètres de la requête signée pour rendre chaque signature unique et empêcher la réutilisation accidentelle d’une signature. | ||||||||||||||||||||||||||||||||||||
params. | 0 | 1Utilisez | ||||||||||||||||||||||||||||||||||||
params. | object | stringAssembly Instructions stockées dans ce Template. Privilégiez l’objet JSON structuré ; une chaîne encodée en JSON reste acceptée pour des raisons de compatibilité. N’importe lequel des schémas suivants peut s’appliquer : objectAssembly Instructions structurées stockées dans ce Template.
stringstringAssembly Instructions encodées en JSON, conservées pour la compatibilité avec les clients. Motif de validation (expression régulière)^[\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"Définit la durée de conservation des résultats du transcodage pour les Assemblies créées à partir de ce Template. |
Paramètres de requête par méthode d’authentification
Avec des paramètres signés
Incluez votre Auth Key dans params.auth.key. Lors de la signature de la requête, incluez un horodatage futur dans params.auth.expires et envoyez la signature dans le champ distinct signature. Les définitions des champs ci-dessous utilisent des chemins à l’intérieur de params.
Schéma JSON complet
params: Seuls les champs répertoriés pour cet objet sont acceptés.
Utilise les définitions des champs ci-dessus : 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
Avec un jeton porteur
Envoyez le jeton porteur dans l’en-tête Authorization. Vous pouvez omettre params.auth et le champ distinct signature. Les autres paramètres obligatoires restent requis. Les définitions des champs ci-dessous utilisent des chemins à l’intérieur de params.
Schéma JSON complet
params: Seuls les champs répertoriés pour cet objet sont acceptés.
Utilise les définitions des champs ci-dessus : 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
| Champ | Type et description |
|---|---|
params. | Contient la clé API Transloadit et les métadonnées de Signature Authentication pour une requête de Template.
|
params. | stringHorodatage d’expiration au format ISO 8601 situé dans le futur. Obligatoire lorsqu’une requête est signée ou nécessite Signature Authentication ; les requêtes authentifiées par jeton porteur peuvent l’omettre. |
params. | stringClé API Transloadit utilisée pour authentifier les requêtes |
Réponse
Voici un exemple de corps de réponse :
{
"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
}Succès 2xx
Corps de la réponse JSON. application/json text/plain; charset=utf-8
Schéma du corps de la réponse
Schéma JSON complet
La réponse contient uniquement les champs répertoriés pour cet objet.
| Champ | Type et description |
|---|---|
assembly_status_expiryobligatoire | null | string |
contentobligatoire | object | Array<n’importe quelle valeur> | string | number | boolean | nullN’importe lequel des schémas suivants peut s’appliquer : objectobjectSchéma de la propriété supplémentairen’importe quelle valeurArray<n’importe quelle valeur>Array<n’importe quelle valeur>Schéma d’un élément de tableaun’importe quelle valeurstringnumberbooleannull |
cron_auth_key_id | string | nullMotif de validation (expression régulière)^[a-f0-9]{32}$ |
cron_enabled | boolean |
cron_max_concurrent_runs | integer (minimum : 1, maximum : 10) |
cron_region | "ap-southeast-1" | "eu-west-1" | "us-east-1" | null |
cron_schedule_with_seconds | string | null (longueur minimale : 1, longueur maximale : 255) |
idobligatoire | stringN’importe lequel des schémas suivants peut s’appliquer : Variante 1: string (longueur maximale : 32)stringMotif de validation (expression régulière)^[\x00-\x7F]*$Variante 2: string (longueur maximale : 32)stringMotif de validation (expression régulière)^builtin\/[a-z0-9-]+(?:@[0-9a-z.-]+)?$ |
messageobligatoire | string (longueur minimale : 1) |
nameobligatoire | string (longueur minimale : 1, longueur maximale : 255) |
okobligatoire | string (toujours : "TEMPLATE_UPDATED") |
require_signature_authobligatoire | 0 | 1 |
transcoding_result_expiryobligatoire | null | string |
Réponse d’erreur
Corps de la réponse JSON. application/json text/plain; charset=utf-8
Schéma du corps de la réponse
Schéma JSON complet
La réponse peut contenir des champs supplémentaires.
| Champ | Type et description |
|---|---|
assembly_id | string |
error | string (longueur minimale : 1) |
http_code | number | string
|
message | stringExplication de l’erreur destinée à être lue par un humain. Sa formulation peut varier ; utilisez le code |
reason | null | string | number | boolean | Array<n’importe quelle valeur> | objectN’importe lequel des schémas suivants peut s’appliquer : nullstringnumberbooleanArray<n’importe quelle valeur>Array<n’importe quelle valeur>Schéma d’un élément de tableaun’importe quelle valeurobjectobjectSchéma de la propriété supplémentairen’importe quelle valeur |
HTTP 400
Corps de la réponse JSON. application/json text/plain; charset=utf-8
Schéma du corps de la réponse
Schéma JSON complet
Erreurs nommées et format général des erreurs
error: "TEMPLATE_VALIDATION_ERROR"
La validation de votre Template a échoué.
La réponse peut contenir des champs supplémentaires.