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 de l'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 des États-Unis, l'URL de requête doit commencer par https://us.cloud.memsource.com.

Scénario

Authentification

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

La création d'un projet simple, des travaux téléchargés et l'attribution d'un linguiste avec notification par e-mail.
Traduction

Travail de traduction effectué en dehors du scénario API (dans n'importe quel des éditeurs).
Fonction API

Une fois l'attribution terminée (marquée comme Terminée par le linguiste), le statut du projet est défini sur Terminée 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 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, nom d'utilisateur et mot de passe 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 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 attribution 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

Project UID (e.g. 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

{
  "project": {
    "uid": "chaîne"
  },
  "name": "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 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 de 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

{
  "name": "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"
  }
}{
  "project": {
    "uid": "chaîne"
  },
  "name": "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 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 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 personnalisé Memsource.

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, allez dans le corps, sélectionnez binaire et l'option Sélectionner un fichier apparaît.

Méthode

POST
URL de la requête

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

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

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

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 travail, la réponse renvoie un UID de tâche unique pour chaque étape du flux de travail.

Les paramètres d'importation réutilisables peuvent être configurés avec l'appel Créer des paramètres d'importation. Un UID de paramètre d'importation qui peut être utilisé dans l'appel de création de 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.
Utilisez le Liste des utilisateurs 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, nomUtilisateur, peut être ajouté à la requête vous permettant de lister uniquement les utilisateurs avec des noms d'utilisateur spécifiques.

Notifier les utilisateurs assignés

L'UID de la tâche peut ensuite être utilisé comme paramètre optionnel dans l'appel Notifier les utilisateurs assignés avec le paramètre modèleEmail représentant l'ID 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 : Aucun contenu)

C'est ici que le traducteur commencerait à travailler dans son profil comme si l'interface utilisateur de Phrase était utilisée. Après que la tâche soit terminée, le PM en charge reçoit une notification et la prochaine partie du scénario est initié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 (complet), définir le projet comme terminé

Télécharger le fichier traduit

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

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

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 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 le Liste des tâches appel API.

Ce point de terminaison renvoie une liste de tâches dans le 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 sur 1 (= première étape du flux de travail) par défaut. 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 de téléchargement du fichier cible (asynchrone) initie une demande asynchrone pour générer et télécharger le fichier cible contenant des 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

ID 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

Télécharger
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 comme terminé

Pour finaliser le projet une fois que la tâche dans le projet est terminée, utilisez l'appel Modifier le statut du projet avec les paramètres obligatoires projectUid et statut pour changer le statut de l'ensemble du projet en Terminé. 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)