Using APIs (TMS)

Le contenu est traduit de l’anglais par Phrase Language AI.

Ceci est un scénario API simple avec des appels API d'exemple et des instructions sur la façon de les enchaîner pour terminer une action simple en utilisant uniquement des API. Les options qui peuvent être définies via les API sont étendues. Consultez les sections respectives de la documentation API REST pour en savoir plus sur toutes les options disponibles.

La plateforme API Postman a été utilisée pour créer le scénario.

Dans ces exemples, l'URL de requête standard commence par https://cloud.memsource.com. Dans le cas où des API sont utilisées par une organisation dans le centre de données américain, l'URL de requête doit commencer par https://us.cloud.memsource.com.

Scénario

Authentification

L'utilisateur est authentifié (l'équivalent de la connexion via l'API).
Création

La création d'un projet simple, des tâches chargées et l'assignation d'un linguiste avec notification par e-mail.
Traduction

Le travail de traduction est effectué en dehors du scénario API (dans n'importe lequel des éditeurs).
Fonction API

Une fois l'assignation terminée (marquée comme Terminé par le linguiste), le statut du projet est défini sur Terminé et le document terminé est téléchargé depuis le projet.

Méthodologie

Chaque appel API REST individuel a une méthode appropriée répertoriée. Utiliser une méthode incorrecte (par exemple, GET au lieu de POST dans l'appel de création de projet) entraîne un appel API infructueux.

Étape 1 : Authentification

Il existe deux méthodes d'authentification :

Appel d'API d'authentification :

Génère un jeton d'authentification valide pendant 24 heures. Le jeton doit être inséré dans toutes les API suivantes. Le jeton valide les utilisateurs et leur permet d'effectuer d'autres fonctions au sein du profil.
oAuth 2.0

Permet la validation d'une application. Une application validée est en communication continue et n'a pas besoin d'authentification supplémentaire.

Pour le scénario, l'appel API d'authentification est utilisé. Le jeton généré est requis pour tous les appels API suivants et n'est pas listé dans les paramètres d'exemple.

Utilisez l'API Login pour l'authentification avec les paramètres requis. Dans ce cas, username et password sont requis.

Méthode

POST
URL de la requête

https://cloud.memsource.com/web/api2/v3/auth/login

Corps de la requête :

{ "userName":"username", "password":"password"}

Réponse

Jeton d'authentification.

Les membres de plusieurs organisations TMS ont le même nom d'utilisateur et le même mot de passe pour plusieurs comptes. Dans ce cas, le userUid doit être ajouté au corps de la requête pour spécifier à quelle organisation l'utilisateur souhaite se connecter. Si non spécifié, l'utilisateur est connecté au compte par défaut associé au nom d'utilisateur et au mot de passe donnés.

Étape 2 : Création, importation et assignation de projet

Création de projet

Utilisez l'appel API Projets pour créer un projet avec les paramètres obligatoires nom, langueSource et languesCibles.

Méthode

POST
URL de la requête

https://cloud.memsource.com/web/api2/v3/projects

Corps de la requête

{ "name":"My project", "sourceLang":"en", "targetLangs":[ "de","fr" ]}

Réponse

UID du projet (par exemple KmtNyVlz1skQd2aMVEipp7)

Il est possible de créer un modèle* de projet en utilisant l'appel API Créer un modèle* de projet avec l'UID du projet de l'appel précédent.

Méthode

POST
URL de la requête

https://cloud.memsource.com/web/api2/v1/projectTemplates

Corps de la requête

{
  "projet": {
    "uid": "chaîne"
  },
  "nom": "chaîne",
  "importSettings": {
    "uid": "chaîne"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Réponse

UID du modèle de projet (par exemple AmtNyVlz1skQd2aMVEipp8)

La manière la plus efficace de créer des projets est d'utiliser un modèle de projet. Utilisez Créer un projet à partir du modèle de projet avec l'UID du modèle de projet de l'appel précédent pour créer un nouveau projet basé sur les paramètres du modèle de projet.

L'expression {templateUid} sert d'espace réservé dans l'URL de la requête où l'UID du modèle de projet obtenu est inséré.

Méthode

POST
URL de la requête

https://cloud.memsource.com/web/api2/v2/projects/applyTemplate/oNQiljwTGHpd2l1nnQRiu4

Corps de la requête

{
  "nom": "chaîne"
  "sourceLang": "chaîne",
  "targetLangs": [
    "string"
  ],
  "workflowSteps": [
    {
      "id": "chaîne"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "string",
  "client": {
    "id": "chaîne"
  },
  "businessUnit": {
    "id": "chaîne"
  },
  "domaine": {
    "id": "chaîne"
  },
  "sous-domaine": {
    "id": "chaîne"
  },
  "costCenter": {
    "id": "chaîne"
  }
}{
  "projet": {
    "uid": "chaîne"
  },
  "nom": "chaîne",
  "importSettings": {
    "uid": "chaîne"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Réponse

UID du projet (par exemple, BmtNyVlz1skQd2aMVEipp9)

Création de tâche

Avec l'UID du projet de l'appel précédent, de nouvelles tâches peuvent être ajoutées directement dans le projet nouvellement créé en utilisant Créer une tâche.

L'expression {projectUid} sert d'espace réservé dans l'URL de la requête où l'UID du projet obtenu est inséré. Avec l'appel API Créer une tâche, les En-têtes de la requête doivent être modifiés pour correspondre à ceux requis par Phrase (dans d'autres appels, Postman ajoute automatiquement les en-têtes appropriés à la requête).

Tous les paramètres d'importation doivent être insérés dans un en-tête Memsource personnalisé.

L'en-tête Content-Disposition doit inclure le nom de fichier dans un format prédéfini afin de traiter correctement la demande d'importation.

Pour importer un fichier source, accédez au corps, sélectionnez binaire et l’option Sélectionner le fichier apparaît.

Méthode

POST
URL de la requête

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
(En-tête) Content-Disposition

filename*=UTF-8''file.txt
(En-tête) Memsource

{"targetLangs":["de","fr"]}
(En-tête) Content-Type

application/octet-stream
Réponse

UID de tâche (par exemple, dOYgeXzAdAbj4xFjuEVZP2)

UID de demande asynchrone

Utilisez Obtenir la demande asynchrone avec l'UID de demande asynchrone de l'appel Créer une tâche pour vérifier que la tâche a été créée avec succès et qu'elle est fonctionnelle.

L'UID de tâche retourné est unique dans chaque étape du flux de travail du projet. Par conséquent, si la tâche est créée dans un projet avec flux de travaux, la réponse renvoie un UID de tâche unique pour chaque étape du flux de travaux.

Les paramètres d'importation réutilisables peuvent être configurés avec l'appel Créer des paramètres d'importation. Un identifiant de paramètre d'importation qui peut être utilisé dans l'appel créer une tâche est reçu dans la réponse.

Pour assigner des fournisseurs à la tâche (sauf s'ils sont assignés directement dans l'appel Créer une tâche), utilisez l'appel Modifier la tâche.

L'ID du fournisseur qui est inséré dans l'appel peut être obtenu de deux manières :

Pour récupérer l'ID de l'application Phrase, suivez ces étapes :
1. Depuis la page des paramètres , faites défiler vers le bas jusqu'à la section Administration et cliquez sur Utilisateurs ou cliquez sur Utilisateurs dans la barre latérale.
  
  La page Utilisateurs s'ouvre.
2. Cliquez sur le nom de famille de l'utilisateur et copiez la dernière partie de l'URL depuis le navigateur.
3. Utilisez cette partie comme l'ID pour cet utilisateur.
Utiliser l’<1> liste des utilisateurs<3> appel API.

Cet appel API ne nécessite aucun paramètre spécifique et renverra une liste de tous les utilisateurs du compte. La réponse contient à la fois des noms d'utilisateur et des identifiants.

Un paramètre optionnel, userName, peut être ajouté à la requête, ce qui vous permet de lister uniquement les utilisateurs avec des noms d'utilisateur spécifiques.

Notifier les utilisateurs assignés

L'Identifiant de la tâche peut ensuite être utilisé comme paramètre optionnel dans l'appel Notifier les utilisateurs assignés, avec le paramètre emailTemplate représentant l'Identifiant du modèle d'e-mail à utiliser. Cela peut être obtenu en utilisant l'appel Liste des modèles d’e-mail.

URL de la requête

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
Réponse

Vide (Statut 204 : Pas de contenu)

C'est ici que le traducteur commencerait à travailler dans son profil comme si l'interface utilisateur de Phrase était utilisée. Une fois la tâche terminée, le PM en charge reçoit une notification et la partie suivante du scénario est lancée. Un rappel peut être intercepté via webhooks pour démarrer automatiquement la prochaine partie du scénario, mais cela ne sera pas abordé dans cet exemple.

Étape 3 : Télécharger le fichier traduit (Terminé), définir le projet sur Terminé

Télécharger le fichier traduit

Ce scénario fonctionne sur l'hypothèse qu'un traducteur termine sa mission (marquant la tâche comme Completed), mais le fichier terminé peut être téléchargé à tout moment, la tâche n'a pas besoin d'avoir le statut Completed.

Pour télécharger un fichier traduit, deux appels API sont nécessaires : Les appels Télécharger le fichier cible (async) et Télécharger le fichier cible basé sur la demande async.

La première étape consiste à appeler Télécharger le fichier cible (async) avec les paramètres projectUid et jobUid. Si vous téléchargez le fichier terminé d'un projet avec plusieurs étapes de flux de travail, assurez-vous d'utiliser le jobUid de l'étape de flux de travail spécifique à partir de laquelle vous souhaitez télécharger le fichier terminé, par exemple l'étape de flux de travail de révision.

Pour récupérer le jobUID pour une étape de flux de travail spécifique à partir de l'application Phrase, suivez ces étapes :
1. Ouvrez le projet.
2. Dans la table des tâches, passez à l'étape du flux de travail à partir de laquelle vous souhaitez télécharger le fichier terminé.
3. Copiez la partie unique de l'URL après /job depuis le navigateur.
Utilisez l’<1> Liste des tâches<3> appel API.

Ce point de terminaison renvoie une liste de tâches au sein du projet spécifié. Utilisez l'appel avec le paramètre de requête workflowLevel. Ce paramètre est un paramètre non basé sur zéro qui indique l'étape du flux de travail à laquelle appartiennent les tâches retournées. S'il n'est pas spécifié, sa valeur est définie par défaut sur 1 (= première étape du flux de travail). Par exemple, si vous devez obtenir les tâches de l'étape de révision, spécifiez le numéro de cette étape dans le paramètre de requête, c'est-à-dire 2.

L'appel Télécharger le fichier cible (async) lance une requête asynchrone pour générer et télécharger le fichier cible contenant les traductions. Il ne fournit pas directement le fichier cible dans la réponse mais un asyncRequestId requis pour l'appel suivant.

Méthode

PUT
URL de la requête

https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
Réponse

Identifiant de demande asynchrone

Utilisez Obtenir la demande asynchrone avec le asyncRequestID de la réponse pour vérifier que la demande est terminée. Une fois la demande asynchrone terminée, vous pouvez télécharger le fichier cible en utilisant l'appel Télécharger le fichier cible basé sur la demande asynchrone. Le asyncRequestId ne peut être utilisé qu'une seule fois. Une fois le téléchargement initié, le asyncRequestId devient invalide pour une utilisation ultérieure.

Méthode

GET
URL de la requête

https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/downloadTargetFile/1291716982
Réponse

Réponse binaire avec le fichier terminé lui-même.

Définir le projet sur Terminé

Pour finaliser le projet une fois la tâche dans le projet terminée, utilisez l'appel Modifier le statut du projet avec les paramètres obligatoires projectUid et statut pour modifier le statut de l'ensemble du projet en Terminer. Ce changement est manuel, mais si Automatisation du statut du projet est utilisé, le statut sera changé automatiquement. Il est également possible d'attendre un webhook et d'initier d'autres actions en fonction du rappel reçu.

Méthode

POST
URL de la requête

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Corps de la requête
```
{ "status": "COMPLETED"}
```
Réponse

Vide (Statut 204 : Aucun contenu)