Utiliser Postman pour communiquer avec l’API Transloadit

Joseph Grabski

Responsable du contenu · Rochester, Royaume-Uni · Afficher la bio

Postman⁠ est un service entièrement consacré aux API, que vous cherchiez à en créer une ou à en utiliser une. Nous allons nous intéresser aujourd’hui au second cas, pour voir comment configurer Postman afin d’utiliser l’API Transloadit pour renvoyer la liste de toutes vos Assemblies récentes, et aussi comment créer de nouvelles Assemblies. C’est particulièrement utile si vous utilisez directement l’API REST de Transloadit plutôt qu’un SDK, car vous pouvez ainsi déboguer vos requêtes bien plus rapidement qu’autrement.

Pour cela, nous ferons aussi un bref rappel sur l’utilisation de la Signature Authentication avec Transloadit.

Créer une Assembly

Dans un espace de travail, cliquez sur New en haut à gauche, puis choisissez HTTP Request. Ensuite, changez le type de requête de GET à POST.

Vous pouvez maintenant définir l’URL de la requête sur https://api2.transloadit.com/assemblies.

Dans l’onglet Body, vous devez définir le type sur form-data et ajouter deux clés : params et signature. Pour les valeurs, indiquez respectivement {{params}} et {{signature}}.

Les valeurs sont mises en évidence, car les variables n’existent pas encore. Le script de pré-requête ci-dessous les définira pour chaque requête : vous n’avez donc pas besoin d’enregistrer les signatures générées dans votre environnement.

Signature Authentication

Une fois le corps de la requête configuré, nous pouvons passer à l’onglet Pre-request Script. Il vous permet d’exécuter du JavaScript avant votre requête, afin de la modifier. Nous allons nous en servir pour générer une signature avec notre requête.

Définissez TRANSLOADIT_AUTH_KEY et TRANSLOADIT_TEMPLATE_ID dans l’environnement Postman sélectionné. Stockez TRANSLOADIT_AUTH_SECRET dans votre Postman Local Vault⁠, activez l’accès aux scripts et accordez l’autorisation à cette collection lorsque cela vous est demandé. Ne placez pas votre Auth Secret dans un environnement partagé ni dans un script de collection. Les scripts qui s’appuient sur le coffre-fort s’exécutent localement, et non dans les moniteurs cloud ni lors des exécutions planifiées.

Voici le script que nous allons utiliser. Il signe la chaîne JSON exacte avec HMAC-SHA384, comme décrit dans notre documentation sur l’authentification.

const utcDateString = (ms) => {
  return new Date(ms)
    .toISOString()
    .replaceAll('-', '/')
    .replace('T', ' ')
    .replace(/\.\d+Z$/, '+00:00')
}

const expires = utcDateString(+new Date() + 2 * 60 * 60 * 1000)
const authKey = pm.environment.get('TRANSLOADIT_AUTH_KEY')
const authSecret = await pm.vault.get('TRANSLOADIT_AUTH_SECRET')
const templateId = pm.environment.get('TRANSLOADIT_TEMPLATE_ID')

if (!authKey || !authSecret || !templateId) {
  throw new Error('Configure the Auth Key, Template ID, and Local Vault Auth Secret first.')
}

const params = JSON.stringify({
  auth: {
    key: authKey,
    expires,
  },
  template_id: templateId,
})

const secret = CryptoJS.enc.Utf8.parse(authSecret)
const paramsEncoded = CryptoJS.enc.Utf8.parse(params)
const hmac = CryptoJS.HmacSHA384(paramsEncoded, secret)
const signature = `sha384:${CryptoJS.enc.Hex.stringify(hmac)}`

pm.variables.set('params', params)
pm.variables.set('signature', signature)

Utilisez l’identifiant d’un Template de votre Workspace. Si vous souhaitez envoyer un fichier avec votre requête, retournez dans l’onglet Body, ajoutez une clé files et changez son type en File. Il vous suffit ensuite de choisir sur votre système un fichier à envoyer avec votre Assembly.

Si vous cliquez maintenant sur Send, vous devriez recevoir une réponse en bas de votre espace de travail. Si la valeur « ok » est « ASSEMBLY_EXECUTING », vous devriez pouvoir voir l’Assembly s’exécuter depuis votre console Transloadit.

Récupérer les Assemblies récentes

La procédure pour récupérer les Assemblies récentes est très similaire.

Créez une nouvelle requête HTTP, mais cette fois, conservez le type de requête GET.

L’URL de la requête est https://api2.transloadit.com/assemblies?signature={{signature}}&params={{params}}, car nous allons envoyer params et signature sous forme de paramètres encodés dans l’URL plutôt que dans le corps de la requête.

Ajoutez maintenant le même script que précédemment dans l’onglet Pre-request Script, mais ajoutez la ligne suivante, de sorte que la fin du script ressemble à ceci.

const uriEncoded = encodeURIComponent(params)

pm.variables.set('params', uriEncoded)
pm.variables.set('signature', signature)

Pour conclure

C’est tout pour ce bref aperçu de l’utilisation de Postman avec l’API Transloadit. J’espère que cela vous a permis de mieux comprendre le fonctionnement de notre API. Si ce n’est pas le cas, n’hésitez pas à contacter notre support : nous pourrons vous faire une visite guidée de l’API 📭