Using APIs (TMS)

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

Dies ist ein einfaches API Szenario mit beispielhaften API Aufrufen und Anleitungen, wie diese zum Abschließen einer einfachen Aktion nur mit APIs verknüpft werden können. Die über die APIs einstellbaren Optionen sind umfangreich. Weitere Informationen zu allen verfügbaren Optionen findest du in den jeweiligen Abschnitten der REST API Dokumentation.

Das Szenario wurde über die Postman API Platform erstellt.

In diesen Beispielen beginnt die Standardanforderungs-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 ist authentifiziert (die API entspricht der Anmeldung).
Erstellung

Erstellung eines einfachen Projekts, Hochladen von Jobs und Zuweisung von Linguisten per E-Mail Benachrichtigung.
Übersetzung

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

Sobald die Zuweisung abgeschlossen ist (vom Linguisten als Abgeschlossen markiert) wird der Status des Projekts auf Abgeschlossen gesetzt und das fertiggestellte Dokument wird aus dem Projekt heruntergeladen.

Methode

Für jeden einzelnen REST API Aufruf wird eine geeignete Methode aufgelistet. Die Verwendung einer falschen Methode (z. B. GET statt POST im Projekt Erstellungsaufruf) führt zu einem erfolglosen API Aufruf.

Schritt 1: Authentifizierung

Es gibt zwei Authentifizierung:

Authentifizierung API Aufruf:

Erstellt ein 24 Stunden gültiges Token zur Authentifizierung. 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 mit und benötigt keine weitere Authentifizierung.

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

Zur Authentifizierung mit den erforderlichen Parametern die Login API verwenden. In diesem Fall sind Benutzername und Passwort erforderlich.

Methode

POST
URL anfordern

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

Stelle anfordern:

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

Antwort

Authentifizierung Token.

Mitglieder mehrerer TMS Organisationen haben denselben User-Namen und dasselbe Passwort für mehrere Accounts. In diesem Fall muss die userUid zum Anfragetext hinzugefügt werden, um anzugeben, bei welcher Organisation der User sich anmelden möchte. Wenn nicht angegeben, ist der User bei dem Standard-User-Konto angemeldet, das dem angegebenen User-Namen und Passwort zugeordnet ist.

Schritt 2: Projekt erstellen, importieren und zuweisen

Projekterstellung

Verwende den Projects API Aufruf, um ein Projekt mit den obligatorischen Parametern name, sourceLang und targetLangs zu erstellen.

Methode

POST
URL anfordern

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

Stelle anfordern

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

Antwort

Projekt (z. B. KmtNyVlz1skQd2aMVEipp7)

Es ist möglich, eine Vorlage für ein Projekt unter Verwendung des API-Aufrufs Projekt Vorlage erstellen mit der Projekt-UID des letzten Aufrufs zu erstellen.

Methode

POST
URL anfordern

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

Stelle anfordern

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

Antwort

Projekt Vorlage UID (z.B. AmtNyVlz1skQd2aMVEipp8)

Am effizientesten lassen sich Projekte erstellen, wenn eine Vorlage für Projekte verwendet wird. Verwende Projekt erstellen aus Vorlage mit der Projekt Vorlage UID 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, in die die erhaltene Projekt Vorlage UID eingefügt wird.

Methode

POST
URL anfordern

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

Stelle anfordern

{
  "name": "string",
  "sourceLang": "string",
  "targetLangs": [
    "Zeichenfolge"
  ],
  "workflowSteps": [
    {
      "ID": "Zeichenfolge"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "string",
  "client": {
    "ID": "Zeichenfolge"
  },
  "businessUnit": {
    "ID": "Zeichenfolge"
  },
  "Fachbereich": {
    "ID": "Zeichenfolge"
  },
  "subDomain": {
    "ID": "Zeichenfolge"
  },
  "costCenter": {
    "ID": "Zeichenfolge"
  }
}{
  "Projekt": {
    "uid": "Zeichenfolge"
  },
  "name": "string",
  "importSettings": {
    "uid": "Zeichenfolge"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Antwort

Projekt (z. B. BmtNyVlz1skQd2aMVEipp9)

Job erstellen

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

Der Ausdruck {projectUid} dient als Platzhalter in der Anfrage-URL, in die die erhaltene Projekt UID eingefügt wird. Beim Aufruf Job API erstellen müssen die Header der Anfrage zum Match mit den von phrase benötigten geändert werden (in anderen Aufrufen fügt Postman automatisch die entsprechenden Header zur Anfrage hinzu).

Alle Parameter, die importiert werden, müssen in einen benutzerdefinierten Memsource Header eingefügt werden.

Der Inhalte-Disposition-Header muss den Dateinamen in einem vordefinierten Format enthalten, in dessen Reihenfolge er korrekt importiert werden muss.

Um eine Ausgangssprache zu importieren, gehe zum Text, wähle binär aus und die Option Datei auswählen wird angezeigt.

Methode

POST
URL anfordern

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
(Header) Inhalt-Verfügung

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

{"targetLangs":["de","fr"]}
Inhalts-Typ (Header)

application/octet-stream
Antwort

Job UID (z.B. dOYgeXzAdAbj4xFjuEVZP2)

AsyncRequest UID

Verwende Asynchrone Anfrage erhalten mit der AsyncRequest UID vom Aufruf Job erstellen, um zu überprüfen, ob der Job erfolgreich erstellt wurde und ob er funktionsfähig ist.

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

Wiederverwendbare Einstellungen importieren können mit dem Aufruf Einstellungen erstellen konfiguriert werden. In der Antwort wird eine Einstellungs-UID importiert, die im Job erstellen verwendet werden kann.

Um Dienstleister*innen dem Job zuzuweisen (sofern diese nicht direkt im Aufruf Job erstellen zugewiesen werden), verwende den Aufruf Job bearbeiten.

Die im Aufruf eingefügte ID des Dienstleisters kann auf zwei Arten erhalten werden:

Um die ID aus der phrase Anwendung abzurufen, folge diesen Schritten:
1. Scrolle auf der Seite Einstellungen nach unten zum Bereich Administration und klicke in der Seitenleiste auf User oder klicke auf User.
  
  Die Seite User öffnet sich.
2. Klicke auf den Nachnamen des Users und kopiere den letzten Teil der URL aus dem Browser.
3. Diesen Teil als ID für diesen User verwenden.
Verwende den API Aufruf Liste User

Dieser API Aufruf benötigt 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, um nur User mit bestimmten Benutzernamen auf der Liste zu haben.

Zugewiesene User benachrichtigen

Der Job U ID kann dann als optionaler Parameter im Aufruf zugewiesene User benachrichtigen zusammen mit dem Parameter E-Mail Vorlage verwendet werden, der die ID der zu verwendenden E-Mail Vorlage repräsentiert. Dies kann durch Aufruf von Liste E-Mail Templates erreicht werden.

URL anfordern

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

empty (Status 204: Kein Inhalt)

Hier begannen die Übersetzer mit Jobs in ihrem Profil, als ob die Benutzeroberfläche von phrase verwendet würde. Nachdem der Job abgeschlossen ist, erhält der zuständige PM eine Benachrichtigung und der Weiter Teil des Szenarios wird eingeleitet. Ein Callback kann über Webhooks abgefangen werden, um automatisch den Weiteren Teil des Szenarios zu starten, was in diesem Beispiel aber nicht behandelt wird.

Schritt 3: Übersetzte Datei herunterladen (abschließen) und Projekt als abgeschlossen markieren

Übersetzte Datei herunterladen

Bei diesem Szenario wird davon ausgegangen, dass ein Übersetzer seine Zuweisung beendet (markiert den Job als Abgeschlossen), die abgeschlossene Datei aber jederzeit heruntergeladen werden kann, der Job muss nicht den Status Abgeschlossen haben.

Um eine übersetzte Datei herunterzuladen, sind zwei API Aufrufe erforderlich: Zielsprache herunterladen (asynchron) und Zielsprache auf der Grundlage asynchroner Anforderungsaufrufe herunterladen.

Im ersten Schritt wird die Zielsprache (asynchron) mit den Parametern projectUid und jobUid heruntergeladen. Wenn Sie die abgeschlossene Datei aus einem Projekt mit mehreren Arbeitsabläufen herunterladen, stellen Sie sicher, dass Sie die jobUid aus dem bestimmten Arbeitsschritt verwenden, aus dem Sie die abgeschlossene Datei herunterladen möchten, z. B. Arbeitsschritt Revision.

Um die jobUID für einen bestimmten Arbeitsschritt aus der phrase Anwendung abzurufen, folge diesen Schritten:
1. Öffne das Projekt.
2. Wechsle in der Jobs-Tabelle zu dem Arbeitsschritt, von dem du die abgeschlossene Datei herunterladen möchtest.
3. Kopiere den eindeutigen Teil der URL nach / Job aus dem Browser.
Verwende den API Aufruf Liste Jobs

Dieser Endpunkt gibt eine Liste der Jobs innerhalb des angegebenen Projekts zurück. Aufruf mit dem Parameter workflowLevel Query verwenden. Dieser Parameter ist ein von Null verschiedener Parameter, der angibt, zu welchem Arbeitsschritt 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 Schritt Revision abrufen müssen, geben Sie im Parameter Query die Nummer dieses Schritts an, d.h. 2.

Der Aufruf der Zielsprache herunterladen (asynchron) initiiert eine asynchrone Anfrage zum Erstellen und herunterladen der Zielsprache mit Übersetzungen. Sie liefert nicht direkt die Zielsprache in der Antwort, sondern eine asyncRequestId, die für den folgenden Aufruf erforderlich ist.

Methode

PUT
URL anfordern

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

AsyncRequest ID

Verwende Get 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 Zielsprache herunterladen, indem Sie die Zielsprache herunterladen. Die asyncRequestId kann nur einmal verwendet werden. Sobald heruntergeladen wird, wird die asyncRequestId ungültig und kann weiter verwendet werden.

Methode

HOLEN
URL anfordern

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, verwende den Aufruf Status Projekt bearbeiten mit den obligatorischen Parametern projectUid und Status, um den Status des gesamten Projekts auf Abgeschlossen zu ändern. Dies wird manuell geändert, aber wenn Projekt Status Automatisierung verwendet wird, wird der Status automatisch geändert. Es ist auch möglich, auf einen Webhook zu warten und auf der Grundlage des empfangenen Rückrufs andere Aktionen zu initiieren.

Methode

POST
URL anfordern

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Stelle anfordern
```
{"Status": „ABGESCHLOSSEN“}
```
Antwort

empty (Status 204: Kein Inhalt)