Utilisation des API (TMS)

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

Il s'agit d'un scénario API simple avec des exemples d'appels API et des instructions sur la façon de les enchaîner pour Terminer une action simple en utilisant uniquement des API. Les options pouvant ê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. Si 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 API de la connexion).
Création

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

Travail de traduction effectué en dehors du scénario API (dans l'un des éditeurs).
Fonction API

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

Méthodologie

Chaque appel API REST individuel dispose d'une méthode appropriée répertoriée. L'utilisation d'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 toute autre fonction au sein du profil.
OAuth 2.0

Permet la validation d'une application. Une application validée est en communication continue et ne nécessite aucune authentification supplémentaire.

Pour ce 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.

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

Méthode

POST
URL de 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 rien n'est spécifié, l'utilisateur est connecté au compte par défaut associé au nom d'utilisateur et au mot de passe fournis.

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

Création de projet

Utiliser l'appel API Projets pour Créer un projet avec les paramètres obligatoires name, sourceLang et targetLangs.

Méthode

POST
URL de 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 ex. 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 du dernier appel.

Méthode

POST
URL de requête

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

Corps de la requête

{
  "project": {
    "uid": "string"
  },
  "name": "string",
  \"importSettings\": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Réponse

UID du modèle* de projet (par ex. AmtNyVlz1skQd2aMVEipp8)

Le moyen le plus efficace de créer des projets est d'utiliser un modèle* de projet. Utiliser Créer un projet à partir d'un modèle* de projet avec l'UID du modèle* de projet du dernier appel 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 requête

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

Corps de la requête

{
  "name": "string",
  "sourceLang": "string",
  \"targetLangs\": [
    "string"
  ],
  \"workflowSteps\": [
    {
      "id": "string"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "string",
  "client": {
    "id": "string"
  },
  "businessUnit": {
    "id": "string"
  },
  "domain": {
    "id": "string"
  },
  "subDomain": {
    "id": "string"
  },
  "costCenter": {
    "id": "string"
  }
}{
  "project": {
    "uid": "string"
  },
  "name": "string",
  \"importSettings\": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Réponse

Identifiant de projet (par ex. BmtNyVlz1skQd2aMVEipp9)

Création de tâche

Avec l'Identifiant de projet du dernier appel, 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'Identifiant de projet obtenu est inséré. Avec l'appel d'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 commande d'importation.

Pour importer un fichier source, allez dans le corps, sélectionnez binaire et l'option Sélectionner le fichier apparaît.

Méthode

POST
URL de 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

Identifiant de tâche (par ex. dOYgeXzAdAbj4xFjuEVZP2)

UID de requête asynchrone

Utilisez Obtenir une requête asynchrone avec l'Identifiant de requête 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'Identifiant 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 un flux de travaux, la réponse retourne un Identifiant de tâche unique pour chaque étape du flux de travail.

Des 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 de création de tâche est reçu dans la réponse.

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

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

Pour récupérer l'Identifiant depuis l'application Phrase, suivez ces étapes :
1. Depuis la page Paramètres , faites défiler 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 Identifiant pour cet utilisateur.
Utilisez l' liste des utilisateurs appel API.

Cet appel API ne nécessite aucun paramètres spécifiques, et il retournera une liste de tous les utilisateurs du compte. La réponse contient à la fois les noms d'utilisateur et les Identifiants.

Un paramètre optionnel, userName, 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'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. Ceci peut être obtenu en utilisant l'appel Liste des modèles d'e-mail.

URL de 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 exactement comme si l'interface 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 initiée. Un rappel peut être intercepté via webhooks pour démarrer automatiquement la partie suivante du scénario, mais cela ne sera pas abordé dans cet exemple.

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

Télécharger le fichier traduit

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

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 une requête 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é à partir d'un projet avec plusieurs étape du flux de travail, assurez-vous d'utiliser le jobUid de l'étape du flux de travail spécifique à partir de laquelle vous souhaitez télécharger le fichier terminé, par exemple l'étape du flux de travail de révision.

Pour récupérer le jobUID pour une étape du flux de travail spécifique depuis l'application Phrase, suivez ces étapes :
1. Ouvrez le projet.
2. Dans le tableau 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.
Utiliser le liste des tâches appel API.

Ce point de terminaison renvoie une liste de tâches au sein du projet spécifié. Utiliser 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 renvoyé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 de téléchargement de fichier cible (async) initie 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 requête

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

Identifiant de requête asynchrone

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

Méthode

Télécharger
URL de 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 Terminer

Pour finaliser le projet une fois que la tâche dans le projet est terminée, utiliser l'appel modifier le statut du projet avec les paramètres obligatoires projectUid et statut pour modifier le statut de l'ensemble du projet sur Terminer. Cette modification est manuelle, mais si Automatisation du statut du projet est utilisée, le statut sera modifié automatiquement. Il est également possible d'attendre un webhook et d'initier d'autres actions basées sur le rappel reçu.

Méthode

POST
URL de 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)