Verwendung von 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. Konsultieren Sie die jeweiligen Abschnitte der REST-API-Dokumentation, um mehr über alle verfügbaren Optionen zu erfahren.

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 Benutzer ist authentifiziert (das API-Äquivalent zum Einloggen).
Erstellung

Die Erstellung eines einfachen Projekts, hochgeladene Jobs und die Zuordnung eines Linguisten mit E-Mail-Benachrichtigung.
Translation

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

Sobald die Zuordnung abgeschlossen ist (als Abgeschlossen durch den Linguisten 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 APIs eingefügt werden. Das Token validiert Benutzer 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.

Verwenden Sie die Login API zur Authentifizierung mit den erforderlichen Parametern. In diesem Fall sind Benutzername und Passwort erforderlich.

Methode

POST
Anforderungs-URL

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

Anforderungstext:

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

Antwort

Authentifizierungstoken.

Mitglieder mehrerer TMS-Organisationen haben denselben Benutzernamen und dasselbe Passwort für mehrere Konten. In diesem Fall muss die userUid zum Anforderungstext hinzugefügt werden, um anzugeben, bei welcher Organisation sich der Benutzer anmelden möchte. Wenn nicht anders angegeben, ist der Benutzer mit dem Standardkonto angemeldet, das mit dem angegebenen Benutzernamen und Passwort verknüpft ist.

Schritt 2: Projekterstellung, Import und Zuweisung

Projekterstellung

Verwenden Sie den Projects API-Aufruf, 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":"My project", "sourceLang":"en", "targetLangs":[ "de","fr" ]}

Antwort

Projekt-UID (z.B. KmtNyVlz1skQd2aMVEipp7)

Es ist möglich, eine Projektvorlage mit dem Projektvorlage erstellen API-Aufruf unter Verwendung der Projekt-UID aus dem letzten Aufruf zu erstellen.

Methode

POST
Anforderungs-URL

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

Anforderungsinhalt

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

Antwort

Projektvorlagen-UID (z.B. AmtNyVlz1skQd2aMVEipp8)

Der effizienteste Weg zur Erstellung von Projekten besteht darin, eine Projektvorlage zu verwenden. Verwenden Sie Projekt aus Vorlage erstellen mit der Projektvorlagen-UID aus dem letzten Aufruf, um ein neues Projekt basierend auf den Einstellungen der Projektvorlage zu erstellen.

Der Ausdruck {templateUid} dient als Platzhalter in der Anforderungs-URL, wo 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": "string",
  "targetLangs": [
    "Zeichenfolge"
  ],
  "workflowSteps": [
    {
      "id": "Zeichenfolge"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "string",
  "client": {
    "id": "Zeichenfolge"
  },
  "businessUnit": {
    "id": "Zeichenfolge"
  },
  "domain": {
    "id": "Zeichenfolge"
  },
  "subDomain": {
    "id": "Zeichenfolge"
  },
  "costCenter": {
    "id": "Zeichenfolge"
  }
}{
  "projekt": {
    "uid": "Zeichenfolge"
  },
  "name": "string",
  "importSettings": {
    "uid": "Zeichenfolge"
  },
  "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 Create Job hinzugefügt werden.

Der Ausdruck {projectUid} dient als Platzhalter in der Anfrage-URL, wo 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, gehen Sie zum Body, wählen Sie binary und die Option Select File 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

Verwenden Sie Get asynchronous request mit der AsyncRequest UID aus dem Create Job Aufruf, um zu überprü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 Import-Einstellungen können mit dem Create import settings Aufruf konfiguriert werden. Eine Import-Einstellungs-UID, die im Create Job Aufruf verwendet werden kann, wird in der Antwort empfangen.

Um Anbieter dem Job zuzuweisen (es sei denn, sie werden direkt im Create Job Aufruf zugewiesen), verwenden Sie den Edit job Aufruf.

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

Um die ID aus der Phrase-Anwendung abzurufen, befolgen Sie diese Schritte:
1. Auf der Seite Einstellungen nach unten scrollen zur Administration-Sektion und auf Benutzer klicken oder Benutzer in der Seitenleiste klicken.
  
  Die Benutzer-Seite öffnet sich.
2. Klicken Sie auf den Nachnamen des Benutzers und kopieren Sie den letzten Teil der URL aus dem Browser.
3. Verwenden Sie diesen Teil als die ID für diesen Benutzer.
Verwenden Sie die Benutzer auflisten API-Abfrage.

Dieser API-Aufruf erfordert keine spezifischen Parameter und gibt eine Liste aller Benutzer im 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 Benutzer

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

Anforderungs-URL

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

Leer (Status 204: Kein Inhalt)

Hier würde der Übersetzer in seinem Profil zu arbeiten beginnen, als ob die Phrase-Benutzeroberfläche verwendet würde. Nachdem der Job abgeschlossen ist, erhält der zuständige PM eine Benachrichtigung, und der nächste Teil des Szenarios wird eingeleitet. Ein Callback kann über Webhooks abgefangen werden, um automatisch den nächsten Teil des Szenarios zu starten, aber dies wird in diesem Beispiel nicht behandelt.

Schritt 3: Herunterladen der übersetzten (abgeschlossenen) Datei, Projekt auf abgeschlossen setzen

Herunterladen der übersetzten Datei

Dieses Szenario geht davon aus, dass ein Übersetzer seine Aufgabe beendet (den Job als Abgeschlossen markiert), aber die abgeschlossene Datei kann jederzeit heruntergeladen werden, der Job muss nicht den Status Abgeschlossen haben.

Um eine übersetzte Datei herunterzuladen, sind zwei API-Aufrufe erforderlich: Herunterladen der Zieldatei (asynchron) und Herunterladen der Zieldatei basierend auf der asynchronen Anfrage Aufrufe.

Der erste Schritt besteht darin, Herunterladen der Zieldatei (asynchron) mit den Parametern projectUid und jobUid aufzurufen. Wenn Sie die fertige Datei von einem Projekt mit mehreren Arbeitsschritten herunterladen, stellen Sie sicher, dass Sie die jobUid aus dem spezifischen Arbeitsschritt verwenden, von dem Sie die fertige Datei herunterladen möchten, z.B. Arbeitsschritt Revision.

Um die jobUID für einen bestimmten Arbeitsschritt aus der Phrase-Anwendung abzurufen, befolgen Sie diese Schritte:
1. Öffnen Sie das Projekt.
2. Wechseln Sie in der Jobtabelle zu dem Arbeitsschritt, von dem Sie die fertige Datei herunterladen möchten.
3. Kopieren Sie den einzigartigen Teil der URL nach /job aus dem Browser.
Verwenden Sie die Liste der Jobs API-Anfrage.

Dieser Endpunkt gibt eine Liste von Jobs innerhalb des angegebenen Projekts zurück. Verwenden Sie den Aufruf mit dem workflowLevel Abfrageparameter. 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. Wenn Sie beispielsweise die Jobs aus dem Revision-Schritt abrufen müssen, geben Sie die Nummer dieses Schrittes im Abfrageparameter an, d.h. 2.

Der Aufruf zum Herunterladen der Zieldatei (asynchron) initiiert eine asynchrone Anfrage, um die Zieldatei mit den Ü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

Verwenden Sie Holen Sie sich die asynchrone Anfrage mit der asyncRequestID aus der Antwort, um zu überprüfen, ob die Anfrage abgeschlossen ist. Sobald die asynchrone Anfrage abgeschlossen ist, können Sie die Zieldatei mit dem Herunterladen der Zieldatei basierend auf der asynchronen Anfrage Aufruf herunterladen. Die asyncRequestId kann nur einmal verwendet werden. Sobald der Download gestartet ist, wird die asyncRequestId für weitere Verwendungen 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

Um das Projekt abzuschließen, sobald der Job im Projekt abgeschlossen ist, verwenden Sie den Edit project status Aufruf mit den erforderlichen Parametern projectUid und status, um den Status des gesamten Projekts auf Abgeschlossen zu ändern. Diese Änderung ist manuell, aber wenn Projektstatusautomatisierung verwendet wird, wird der Status automatisch geändert. 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
Anforderungsinhalt
```
{ "status": "COMPLETED"}
```
Antwort

Leer (Status 204: Kein Inhalt)