Using APIs (TMS)

Inhalte werden von Phrase Language AI maschinell aus dem Englischen übersetzt.

Dies ist ein einfaches API-Szenario mit Beispiel-API-Aufrufen und Anweisungen, wie man sie zusammenkettet, um eine einfache Aktion nur mit APIs abzuschließen. Die über die APIs einstellbaren Optionen sind umfangreich. Weitere Informationen zu allen verfügbaren Optionen finden sich in den jeweiligen Abschnitten der REST API Dokumentation.

Die Postman API-Plattform wurde verwendet, um das Szenario zu erstellen.

In diesen Beispielen beginnt die Standardanforderungs-URL mit https://cloud.memsource.com. Falls APIs von einer Organisation im US-Rechenzentrum verwendet werden, sollte die Anforderungs-URL mit https://us.cloud.memsource.com beginnen.

Szenario

Authentifizierung

Der User ist authentifiziert (das API-Äquivalent zum Einloggen).
Erstellung

Die Erstellung eines einfachen Projekts, das Hochladen von Jobs und die Zuweisung eines Linguisten mit E-Mail-Benachrichtigung.
Übersetzung

Übersetzungsarbeiten, die außerhalb des API-Szenarios (in einem der Editoren) durchgeführt werden.
API-Funktion

Sobald die Zuweisung fertiggestellt ist (als Abgeschlossen durch den Linguist markiert), wird der Status des Projekts auf Abgeschlossen gesetzt und das fertige Dokument wird aus dem Projekt heruntergeladen.

Methodologie

Jeder einzelne REST-API-Aufruf hat eine entsprechende Methode aufgeführt. Die Verwendung einer falschen Methode (z. B. GET anstelle von POST im Aufruf zur Projekterstellung) führt zu einem erfolglosen API-Aufruf.

Schritt 1: Authentifizierung

Es gibt zwei Authentifizierungsmethoden:

Authentifizierungs-API-Aufruf:

Generiert ein Authentifizierungstoken, das 24 Stunden gültig ist. Das Token muss in alle folgenden API eingefügt werden. Das Token validiert User und ermöglicht es ihnen, alle anderen Funktionen im Profil auszuführen.
oAuth 2.0

Ermöglicht die Validierung einer Anwendung. Eine validierte Anwendung steht in kontinuierlicher Kommunikation und benötigt keine weitere Authentifizierung.

Für das Szenario wird der Authentifizierungs-API-Aufruf verwendet. Das generierte Token ist für alle folgenden API-Aufrufe erforderlich und wird nicht in den Beispielparametern aufgeführt.

Die Login-API ist mit den erforderlichen Parametern zur Authentifizierung zu verwenden. In diesem Fall sind Benutzername und Passwort erforderlich.

Methode

POST
Anforderungs-URL

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

Anforderungsinhalt:

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

Antwort

Authentifizierungstoken.

Mitglieder mehrerer TMS-Organisationen haben denselben Benutzernamen und dasselbe Passwort für mehrere User-Konten. In diesem Fall muss die userUid zum Anforderungsinhalt hinzugefügt werden, um anzugeben, bei welcher Organisation das User-Konto angemeldet werden soll. Wenn nicht angegeben, erfolgt die Anmeldung beim Standard-User-Konto, das dem angegebenen Benutzernamen und Passwort zugeordnet ist.

Schritt 2: Projekterstellung, Import und Zuweisung

Projekterstellung

Den Projects API-Aufruf verwenden, um ein Projekt mit den erforderlichen Parametern name, sourceLang und targetLangs zu erstellen.

Methode

POST
Anforderungs-URL

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

Anforderungsinhalt

{ "name":"Mein Projekt", "sourceLang":"en", "targetLangs":[ "de","fr" ]}

Antwort

Projekt UID (z.B. KmtNyVlz1skQd2aMVEipp7)

Es ist möglich, eine Projektvorlage zu erstellen, indem der Create project template API-Aufruf mit der Projekt-UID aus dem letzten Aufruf verwendet wird.

Methode

POST
Anforderungs-URL

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

Anforderungsinhalt

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

Antwort

Vorlagen-UID (z.B. AmtNyVlz1skQd2aMVEipp8)

Der effizienteste Weg, Projekte zu erstellen, besteht darin, eine Projektvorlage zu verwenden. Mit Projekt aus Vorlage erstellen und der Projektvorlagen-UID aus dem letzten Aufruf lässt sich ein neues Projekt auf Basis der Einstellungen der Projektvorlage erstellen.

Der Ausdruck {templateUid} dient als Platzhalter in der Anforderungs-URL, in die die erhaltene Projektvorlagen-UID eingefügt wird.

Methode

POST
Anforderungs-URL

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

Anforderungsinhalt

{
  "name": "string",
  "sourceLang": "Zeichenfolge",
  "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"
}

Antwort

Projekt-UID (z.B. BmtNyVlz1skQd2aMVEipp9)

Job-Erstellung

Mit der Projekt-UID aus dem letzten Aufruf können neue Jobs direkt in das neu erstellte Projekt mit Job erstellen hinzugefügt werden.

Der Ausdruck {projectUid} dient als Platzhalter in der Anforderungs-URL, in die die erhaltene Projekt-UID eingefügt wird. Bei dem Create Job API-Aufruf müssen die Header der Anfrage geändert werden, um mit den von Phrase geforderten übereinzustimmen (in anderen Aufrufen fügt Postman automatisch die entsprechenden Header zur Anfrage hinzu).

Alle Importparameter müssen in einen benutzerdefinierten Memsource Header eingefügt werden.

Der Content-Disposition Header muss den Dateinamen in einem vordefinierten Format enthalten, um die Importanfrage korrekt zu verarbeiten.

Um eine Quelldatei zu importieren, wird im Body binär ausgewählt, woraufhin die Option Datei auswählen erscheint.

Methode

POST
Anforderungs-URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
(Header) Content-Disposition

filename*=UTF-8''file.txt
(Header) Memsource

{"targetLangs":["de","fr"]}
(Header) Content-Type

application/octet-stream
Antwort

Job UID (z.B. dOYgeXzAdAbj4xFjuEVZP2)

AsyncRequest UID

Asynchrone Anfrage abrufen mit der AsyncRequest UID aus dem Erstellen-Job-Aufruf verwenden, um zu prüfen, ob der Job erfolgreich erstellt wurde und funktionsfähig ist.

Die zurückgegebene Job UID ist in jedem Arbeitsschritt des Projekts einzigartig. Daher, wenn der Job in einem Projekt mit Workflow erstellt wird, gibt die Antwort eine einzigartige Job UID für jeden Arbeitsschritt zurück.

Wiederverwendbare Importeinstellungen können mit dem Importeinstellungen erstellen Aufruf konfiguriert werden. Eine Importeinstellungen-UID, die im Erstellen-Job-Aufruf verwendet werden kann, wird in der Antwort zurückgegeben.

Um Dienstleister dem Job zuzuweisen (es sei denn, sie werden direkt im Erstellen-Job-Aufruf zugewiesen), den Job bearbeiten Aufruf verwenden.

Die ID des Dienstleisters, die im Aufruf eingefügt wird, kann auf zwei Arten erhalten werden:

Um die ID aus der Phrase-Anwendung abzurufen, sind folgende Schritte zu befolgen:
1. Auf der Einstellungen Seite nach unten zum Bereich Administration scrollen und auf User klicken oder User in der Seitenleiste auswählen.
  
  Die User Seite wird geöffnet.
2. Der Nachname des Users wird ausgewählt, und der letzte Teil der URL aus dem Browser wird kopiert.
3. Dieser Teil dient als ID für den User.
Verwende die Benutzer auflisten API-Aufruf

Dieser API-Aufruf erfordert keine spezifischen Parameter und gibt eine Liste aller Benutzer im User-Konto zurück. Die Antwort enthält sowohl Benutzernamen als auch IDs.

Ein optionaler Parameter, Benutzername, kann zur Abfrage hinzugefügt werden, um nur Benutzer mit bestimmten Benutzernamen aufzulisten.

Benachrichtige zugewiesene User

Die Job-UID kann dann als optionaler Parameter im Benachrichtige zugewiesene User Aufruf zusammen mit dem E-Mail-Vorlage Parameter verwendet werden, der die ID der zu verwendenden E-Mail-Vorlage darstellt. Dies kann durch den Aufruf von E-Mail-Vorlagen auflisten erhalten werden.

Anforderungs-URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
Antwort

Leer (Status 204: Kein Content)

An dieser Stelle wird im Profil des Übersetzers mit der Arbeit begonnen, als ob die Phrase-Benutzeroberfläche genutzt würde. Nachdem der Job abgeschlossen ist, wird dem zuständigen PM eine Benachrichtigung zugestellt und der nächste Teil des Szenarios eingeleitet. Ein Callback kann über Webhook abgefangen werden, um automatisch den nächsten Teil des Szenarios zu starten, jedoch wird dies in diesem Beispiel nicht behandelt.

Schritt 3: Übersetzte (abgeschlossene) Datei herunterladen, Projekt auf abgeschlossen setzen

Herunterladen der übersetzten Datei

Dieses Szenario funktioniert unter der Annahme, dass ein Übersetzer seine Aufgabe abschließt (den Job als Abgeschlossen markiert), aber die abgeschlossene Datei kann jederzeit heruntergeladen werden, der Job muss nicht den Abgeschlossen Status haben.

Zum Herunterladen einer übersetzten Datei sind zwei API-Aufrufe erforderlich: Die Aufrufe Herunterladen Zielsprache-Datei (async) und Download target file based on async request werden benötigt.

Der erste Schritt ist, Herunterladen Zielsprache-Datei (async) mit den Parametern projectUid und jobUid aufzurufen. Beim Herunterladen der abgeschlossenen Datei aus einem Projekt mit mehreren Arbeitsschritten ist darauf zu achten, dass die jobUid aus dem spezifischen Arbeitsschritt verwendet wird, von dem die abgeschlossene Datei heruntergeladen werden soll, beispielsweise dem Arbeitsschritt zur Überarbeitung.

Um die JobUID für einen bestimmten Arbeitsschritt aus der Phrase-Anwendung abzurufen, sind folgende Schritte zu befolgen:
1. Das Projekt wird geöffnet.
2. In der Job-Tabelle ist zum gewünschten Arbeitsschritt zu wechseln, von dem die abgeschlossene Datei heruntergeladen werden soll.
3. Der einzigartige Teil der URL nach /job ist aus dem Browser zu kopieren.
Verwende den Job auflisten API-Aufruf

Dieser Endpunkt gibt eine Liste von Jobs innerhalb des angegebenen Projekts zurück. Es ist der Aufruf mit dem Query-Parameter workflowLevel zu verwenden. Dieser Parameter ist ein nicht nullbasierter Parameter, der den Arbeitsschritt angibt, zu dem die zurückgegebenen Jobs gehören. Wenn nicht angegeben, wird sein Wert standardmäßig auf 1 (= erster Arbeitsschritt) gesetzt. Falls die Jobs aus dem Überarbeitungsschritt abgerufen werden sollen, ist im Abfrageparameter die Nummer dieses Schrittes anzugeben, d.h. 2.

Der Aufruf Herunterladen Zielsprache-Datei (async) startet eine asynchrone Anfrage, um die Zielsprache-Datei mit Übersetzungen zu generieren und herunterzuladen. Er liefert die Zieldatei nicht direkt in der Antwort, sondern eine asyncRequestId, die für den folgenden Aufruf erforderlich ist.

Methode

PUT
Anforderungs-URL

https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
Antwort

AsyncRequest ID

Der Aufruf Get asynchronous request wird mit der asyncRequestID aus der Antwort verwendet, um zu überprüfen, ob die Anfrage abgeschlossen ist. Sobald die asynchrone Anfrage abgeschlossen ist, lässt sich die Zieldatei mit dem Aufruf Herunterladen Zielsprache-Datei basierend auf async request herunterladen. Die asyncRequestId lässt sich nur einmal verwenden. Sobald der Download gestartet wurde, ist die asyncRequestId für die weitere Verwendung ungültig.

Methode

GET
Anforderungs-URL

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

Binäre Antwort mit der abgeschlossenen Datei selbst

Projekt auf Abgeschlossen setzen

Sobald der Job im Projekt abgeschlossen ist, wird der Edit project status Aufruf mit den obligatorischen Parametern projectUid und status verwendet, um den Status des gesamten Projekts auf Abgeschlossen zu ändern. Diese Änderung erfolgt manuell, doch wenn Project Status Automation verwendet wird, ändert sich der Status automatisch. Es ist auch möglich, auf einen Webhook zu warten und andere Aktionen basierend auf dem erhaltenen Callback zu initiieren.

Methode

POST
Anforderungs-URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Anfragekörper
```
{ "status": "COMPLETED"}
```
Antwort

Leer (Status 204: Kein Content)