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 diese miteinander verknüpft werden, um eine einfache Aktion nur mithilfe von APIs zu Abschließen. Die Optionen, die über die APIs eingestellt werden können, 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 Standard-Anfrage-URL mit https://cloud.memsource.com. Falls APIs von einer Organisation im US-Rechenzentrum verwendet werden, sollte die Anfrage-URL mit https://us.cloud.memsource.com beginnen.

Szenario

Authentifizierung

Der User wird authentifiziert (das API-Äquivalent zur Anmeldung).
Erstellen

Das Erstellen eines einfachen Projekts, hochgeladene Jobs und Linguist-Zuweisung mit E-Mail-Benachrichtigung.
Translation

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

Sobald der Job abgeschlossen ist (vom Linguist als Abschließen markiert), wird der Status des Projekts auf Abschließen gesetzt und das fertige Dokument aus dem Projekt heruntergeladen.

Methodik

Jeder einzelne REST-API-Aufruf hat eine entsprechende Methode aufgelistet. Die Verwendung einer falschen Methode (z. B. GET statt POST beim Aufruf zum Erstellen eines Projekts) führt zu einem nicht erfolgreichen API-Aufruf.

Schritt 1: Authentifizierung

Es gibt zwei Authentifizierungsmethoden:

Authentifizierungs-API-Aufruf:

Generiert ein Authentifizierungs-Token, das 24 Stunden lang gültig ist. Das Token muss in alle folgenden APIs eingefügt werden. Das Token validiert User und ermöglicht es ihnen, alle anderen Funktionen innerhalb des Profils 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 dieses 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 username und password erforderlich.

Method

POST
Request URL

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

Request body:

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

Antwort

Authentifizierungs-Token.

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

Schritt 2: Projekt-Erstellung, importieren und Zuweisung

Projekt-Erstellung

Verwenden Sie den Projekte API-Aufruf, um ein Projekt mit den obligatorischen Parametern name, sourceLang und targetLangs zu erstellen.

Method

POST
Request URL

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

Anfrage-Body

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

Antwort

Projekt-ID (z. B. KmtNyVlz1skQd2aMVEipp7)

Es ist möglich, eine Projekt-Vorlage mithilfe des Erstellen Projekt-Vorlage API-Aufrufs mit der Projekt-ID aus dem letzten Aufruf zu erstellen.

Method

POST
Request URL

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

Anfrage-Body

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

Antwort

Projekt-Vorlage-ID (z. B. AmtNyVlz1skQd2aMVEipp8)

Der effizienteste Weg zum Erstellen von Projekten ist die Verwendung einer Projekt-Vorlage. Verwenden Sie Erstellen Projekt aus Vorlage mit der Projekt-Vorlage-ID aus dem letzten Aufruf, um ein neues Projekt basierend auf den Einstellungen der Projekt-Vorlage zu erstellen.

Der Ausdruck {templateUid} dient als Platzhalter in der Anfrage-URL, an der die erhaltene Projekt-Vorlage-ID eingefügt wird.

Method

POST
Request URL

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

Anfrage-Body

{
  "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\"
  }
}{
  "project": {
    \"uid\": \"Zeichenfolge\"
  },
  "name": "string",
  "importSettings": {
    \"uid\": \"Zeichenfolge\"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Antwort

Projekt-ID (z. B. BmtNyVlz1skQd2aMVEipp9)

Job-Erstellung

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

Der Ausdruck {projectUid} dient als Platzhalter in der Request-URL, an der die erhaltene Projekt UID eingefügt wird. Mit dem Job erstellen API Aufruf müssen die Header des Requests geändert werden, um mit den von Phrase geforderten übereinzustimmen (bei anderen Aufrufen fügt Postman automatisch geeignete Header zum Request hinzu).

Alle importieren Parameter müssen in einen Individuell Memsource Header eingefügt werden.

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

Um eine Ausgangssprache Datei zu importieren, gehen Sie zum Body, auswählen Sie binary und die Datei auswählen Option erscheint.

Method

POST
Request 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 ID (z. B. dOYgeXzAdAbj4xFjuEVZP2)

AsyncRequest ID

Verwenden Sie Asynchronen Request abrufen mit der AsyncRequest ID aus dem Job erstellen Aufruf, um zu prüfen, ob der Job erfolgreich erstellt wurde und funktionsfähig ist.

Die zurückgegebene Job ID ist in jedem Arbeitsschritt des Projekt eindeutig. Wenn der Job daher in einem Projekt mit Workflow erstellt wird, gibt die Antwort eine eindeutige Job ID für jeden Arbeitsschritt zurück.

Wiederverwendbare importieren Einstellungen können mit dem importieren Einstellungen erstellen Aufruf konfiguriert werden. Eine importieren Einstellung ID, die im Job erstellen Aufruf verwendet werden kann, wird in der Antwort empfangen.

Um dem Job Dienstleister zuzuweisen (sofern nicht direkt im Job erstellen Aufruf zugewiesen), verwenden Sie den Job bearbeiten Aufruf.

Die ID des Dienstleister, die in den Aufruf eingefügt wird, kann auf zwei Arten ermittelt werden:

Um die ID aus der Phrase-Anwendung abzurufen, folgen Sie diesen Schritten:
1. Scrollen Sie auf der Seite Einstellungen nach unten zum Bereich Administration und klicken Sie auf User oder klicken Sie in der Seitenleiste auf User.
  
  Die Seite User öffnet sich.
2. Klicken Sie auf den Nachnamen des Users und kopieren Sie den letzten Teil der URL aus dem Browser.
3. Verwenden Sie diesen Teil als ID für diesen User.
Verwenden Sie den Liste User API-Aufruf.

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

Ein optionaler Parameter, userName, kann zur Query hinzugefügt werden, wodurch Sie nur User mit bestimmten Benutzernamen auflisten können.

Zugewiesene User benachrichtigen

Die Job-UID kann dann als optionaler Parameter im Zugewiesene User benachrichtigen-Aufruf verwendet werden, zusammen mit dem emailTemplate-Parameter, der die ID der zu verwendenden E-Mail-Vorlage darstellt. Dies kann durch die Verwendung des Liste E-Mail-Vorlagen-Aufrufs erreicht werden.

Request URL

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

leer (Status 204: Kein Content)

Hier würde der Übersetzer in seinem Profil mit der Arbeit beginnen, genau so, 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 Schritt des Szenarios wird eingeleitet. Ein Callback kann über webhooks abgefangen werden, um den nächsten Teil des Szenarios automatisch zu starten, aber dies wird in diesem Beispiel nicht behandelt.

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

Übersetzte Datei herunterladen

Dieses Szenario geht davon aus, dass ein Übersetzer seinen Job abschließt (den Job als abschließen markiert), aber die abgeschlossene Datei kann jederzeit heruntergeladen werden; der Job muss nicht den Status abschließen haben.

Um eine übersetzte Datei herunterzuladen, sind zwei API-Aufrufe erforderlich: Zielsprache-Datei herunterladen (async) und Zielsprache-Datei basierend auf asynchroner Anfrage herunterladen-Aufrufe.

Der erste Schritt ist der Aufruf von Download target file (async) mit den Parametern projectUid und jobUid. Wenn Sie die fertige Datei aus einem Projekt mit mehreren Arbeitsschritten herunterladen, stellen Sie sicher, dass Sie die jobUid aus dem spezifischen Arbeitsschritt verwenden, aus 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, folgen Sie diesen Schritten:
1. Öffnen Sie das Projekt.
2. Wechseln Sie in der Job-Liste zu dem Arbeitsschritt, aus dem Sie die fertige Datei herunterladen möchten.
3. Kopieren Sie den eindeutigen Teil der URL nach /job aus dem Browser.
Verwenden Sie den List jobs API-Aufruf.

Dieser Endpunkt gibt eine Liste von Jobs innerhalb des angegebenen Projekts zurück. Verwenden Sie den Aufruf mit dem Query-Parameter workflowLevel. Dieser Parameter ist ein nicht nullbasierter Parameter, der den Arbeitsschritt angibt, zu dem die zurückgegebenen Jobs gehören. Wenn er nicht angegeben wird, ist sein Wert standardmäßig auf 1 (= erster Arbeitsschritt) gesetzt. Wenn Sie beispielsweise die Jobs aus dem Arbeitsschritt Revision abrufen müssen, geben Sie die Nummer dieses Arbeitsschritts im Query-Parameter an, d. h. 2.

Der Aufruf Download target file (async) initiiert eine asynchrone Anfrage zum Generieren und Herunterladen der Zielsprache-Datei, die Übersetzungen enthält. Er stellt die Zielsprache-Datei nicht direkt in der Antwort bereit, sondern eine asyncRequestId, die für den folgenden Aufruf erforderlich ist.

Method

PUT
Request URL

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

AsyncRequest ID

Verwenden Sie Get asynchronous request 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 Zielsprache-Datei mithilfe des Aufrufs Download target file based on async request herunterladen. Die asyncRequestId kann nur einmal verwendet werden. Sobald der Download gestartet wurde, wird die asyncRequestId für die weitere Verwendung ungültig.

Method

HOLEN
Request 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 Abschließen setzen

Um das Projekt abzuschließen, sobald der Job im Projekt den Status Abschließen erreicht hat, verwenden Sie den Aufruf Projekt Status bearbeiten mit den obligatorischen Parametern projectUid und Status, um den Status des gesamten Projekts auf Abschließen zu ändern. Diese Änderung erfolgt manuell, aber wenn Projekt Status Automatisierung verwendet wird, wird der Status automatisch geändert. Es ist auch möglich, auf einen Webhook<9> zu warten und basierend auf dem empfangenen Callback andere Aktionen einzuleiten.

Method

POST
Request URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Anfrage-Body
```
{ "status": "COMPLETED"}
```
Antwort

leer (Status 204: Kein Content)