Using APIs (TMS)

Obsah je strojově přeložen z angličtiny s použitím Phrase Language AI.

Toto je jednoduchý scénář API s ukázkovými voláními API a pokyny, jak je propojit dohromady a dokončit jednoduchou akci pouze pomocí API. Možnosti, které lze nastavit prostřednictvím API, jsou rozsáhlé. Nahlédněte do příslušných částí REST API dokumentace, abyste získali podrobnější informace o všech dostupných možnostech.

API platforma Postman byla použita k vytvoření scénáře.

V těchto příkladech standardní URL požadavku začíná na https://cloud.memsource.com. Pokud API používá organizace v datovém centru v USA, měla by URL požadavku začínat na https://us.cloud.memsource.com.

Scénář

Ověřování

Uživatel je ověřen (API ekvivalent přihlášení).
Vytvoření

Vytvoření jednoduchého projektu, nahraných zakázek a přiřazení překladatele s e-mailovým oznámením.
Překlad

Zakázka na překlad prováděná mimo scénář API (v jakémkoli z editorů).
API Funkce

Jakmile je zakázka dokončena (označena jako Dokončeno překladatelem), stav projektu je nastaven na Dokončeno a hotový dokument je stažen z projektu.

Metodologie

Každé jednotlivé volání REST API má uvedenou příslušnou metodu. Použití nesprávné metody (např. GET místo POST při volání pro vytvoření projektu) vede k neúspěšnému volání API.

Krok 1: Ověřování

Existují dvě metody ověřování:

API volání pro ověřování:

Generuje ověřovací token platný po dobu 24 hodin. Token je třeba vložit do všech následujících API. Token ověřuje uživatele a umožňuje jim provádět jakékoli další funkce v rámci profilu.
oAuth 2.0

Umožňuje ověření aplikace. Ověřená aplikace je v neustálé komunikaci a nevyžaduje další ověření.

Pro tento scénář se používá volání API pro ověřování. Vygenerovaný token je vyžadován pro všechna následující API volání a není uveden v příkladových parametrech.

Použijte API Login pro ověření s požadovanými parametry. V tomto případě jsou vyžadovány uživatelské jméno a heslo.

Metoda

POST
URL požadavku

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

Tělo požadavku:

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

Odpověď

Ověřovací token.

Členové více TMS organizací mají stejné uživatelské jméno a heslo pro více uživatelských účtů. V tomto případě musí být userUid přidán do těla požadavku, aby bylo určeno, do které organizace se uživatel chce přihlásit. Pokud není specifikováno, uživatel je přihlášen k výchozímu uživatelskému účtu spojenému s daným uživatelským jménem a heslem.

Krok 2: Vytvoření projektu, import a přiřazení

Vytvoření projektu

Použij API Projects k vytvoření projektu s povinnými parametry name, zdrojový jazyk a cílové jazyky.

Metoda

POST
URL požadavku

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

Tělo požadavku

{ "name":"Můj projekt", "sourceLang":"en", "targetLangs":[ "de","fr" ]}

Odpověď

UID projektu (např. KmtNyVlz1skQd2aMVEipp7)

Je možné vytvořit šablonu projektu pomocí API volání Vytvořit šablonu projektu s UID projektu z posledního volání.

Metoda

POST
URL požadavku

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

Tělo požadavku

{
  "project": {
    "uid": "řetězec"
  },
  "name": "řetězec",
  "importSettings": {
    "uid": "řetězec"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "řetězec"
}

Odpověď

UID šablony projektu (např. AmtNyVlz1skQd2aMVEipp8)

Nejefektivnější způsob, jak vytvářet projekty, je použít šablonu projektu. Použijte Vytvořit projekt ze šablony s UID šablony projektu z posledního volání k vytvoření nového projektu na základě nastavení šablony projektu.

Výraz {templateUid} slouží jako zástupný znak v URL požadavku, kam je vložen získaný UID šablony projektu.

Metoda

POST
URL požadavku

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

Tělo požadavku

{
  "name": "řetězec",
  "sourceLang": "řetězec",
  "targetLangs": [
    "řetězec"
  ],
  "pracovní postupy": [
    {
      "id": "řetězec"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "řetězec",
  "klient": {
    "id": "řetězec"
  },
  "businessUnit": {
    "id": "string"
  },
  "doména": {
    "id": "řetězec"
  },
  "subdoména": {
    "id": "řetězec"
  },
  "costCenter": {
    "id": "řetězec"
  }
}{
  "project": {
    "uid": "řetězec"
  },
  "name": "řetězec",
  "importSettings": {
    "uid": "řetězec"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "řetězec"
}

Odpověď

UID projektu (např. BmtNyVlz1skQd2aMVEipp9)

Vytvoření zakázky

S UID projektu z posledního volání mohou být nové zakázky přidány přímo do nově vytvořeného projektu pomocí Vytvořit zakázku.

Výraz {projectUid} slouží jako zástupný znak v URL požadavku, kam se vloží získané UID projektu. Při volání API Vytvořit zakázku musí být Headers požadavku změněny tak, aby odpovídaly těm, které vyžaduje Phrase (v ostatních voláních Postman automaticky přidává vhodné headers do požadavku).

Všechny parametry importu musí být vloženy do vlastní Memsource hlavičky.

Záhlaví Content-Disposition musí obsahovat název souboru v předem definovaném formátu, aby bylo možné správně zpracovat požadavek na import.

Pro import zdrojového souboru přejdi do těla, vyber binární a zobrazí se možnost Vybrat soubor.

Metoda

POST
URL požadavku

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

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

{"targetLangs":["de","fr"]}
(Hlavička) Content-Type

application/octet-stream
Odpověď

UID zakázky (např. dOYgeXzAdAbj4xFjuEVZP2)

UID asynchronního požadavku

Použijte Získat asynchronní požadavek s UID asynchronního požadavku z volání Vytvořit zakázku, abyste zkontrolovali, že zakázka byla úspěšně vytvořena a že je funkční.

Vrácený UID zakázky je jedinečný v každé fázi pracovního postupu projektu. Proto, pokud je zakázka vytvořena v projektu s pracovním postupem, odpověď vrací jedinečný UID zakázky pro každou fázi pracovního postupu.

Nastavení importu, která lze znovu použít, můžeš nakonfigurovat pomocí volání Vytvořit import settings. V odpovědi obdržíš UID nastavení importu, které můžeš použít ve volání vytvoření zakázky.

Chcete-li přiřadit poskytovatele k zakázce (pokud není přiřazen přímo ve volání Vytvořit zakázku), použij Edit job.

ID poskytovatele, který je vložen do volání, lze získat dvěma způsoby:

Chceš-li získat ID z aplikace Phrase, postupuj podle těchto kroků:
1. Na stránce Nastavení posuň se dolů na sekci Administrace a klikni na Uživatelé nebo klikni na Uživatelé v postranním panelu.
  
  Otevře se stránka Uživatelé.
2. Klikni na příjmení uživatele a zkopíruj poslední část URL z prohlížeče.
3. Použijte tuto část jako ID pro tohoto uživatele.
Použij Seznam uživatelů API volání.

Toto API volání nevyžaduje žádné specifické parametry a vrátí seznam všech uživatelů v účtu. Odpověď obsahuje jak uživatelská jména, tak ID.

Volitelný parametr, userName, můžeš přidat do dotazu, což ti umožní vypsat pouze uživatele se specifickými uživatelskými jmény.

Oznámit přiřazeným uživatelům

UID zakázky pak můžeš použít jako volitelný parametr ve volání Oznámit přiřazeným uživatelům spolu s parametrem emailTemplate, který představuje ID šablony e-mailu, jež má být použitá. To dosáhneš pomocí volání Seznam šablon e-mailů.

URL požadavku

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
Odpověď

Prázdný (Stav 204: Žádný obsah)

Tady by překladatel začal pracovat ve svém profilu, stejně jako kdyby používal rozhraní Phrase. Po dokončení zakázky dostane PM zodpovědný za ni oznámení a spustí se další část scénáře. Můžeš zachytit zpětné volání prostřednictvím webhooks, čímž se automaticky spustí další část scénáře, ale v tomto příkladu to neřešíme.

Fáze 3: Stáhnout přeložený (dokončený) soubor, nastavit projekt jako dokončený

Stáhnout přeložený soubor

Tento scénář funguje za předpokladu, že překladatel dokončí svou zakázku (označí ji jako Dokončeno), ale dokončený soubor můžeš stáhnout kdykoli, zakázka nemusí mít stav Dokončeno.

K stažení přeloženého souboru potřebuješ dvě API volání: Stáhnout cílový soubor (asynchronně) a Stáhnout cílový soubor na základě asynchronního požadavku volání.

Zavolej Stáhnout cílový soubor (asynchronně) s parametry projectUid a jobUid. Pokud stahuješ dokončený soubor z projektu s více fázemi pracovního postupu, ujisti se, že používáš jobUid z té konkrétní fáze pracovního postupu, ze které chceš stáhnout dokončený soubor, např. fáze revize.

Chceš-li získat jobUID pro konkrétní fázi pracovního postupu z aplikace Phrase, postupuj podle těchto kroků:
1. Otevři projekt.
2. V tabulce zakázek přepni na fázi pracovního postupu, ze které chceš stáhnout dokončený soubor.
3. Zkopíruj unikátní část URL po /job z prohlížeče.
Použij Seznam zakázek API volání.

Tento koncový bod vrací seznam zakázek v rámci zadaného projektu. Použij volání s parametrem dotazu workflowLevel. Tento parametr není založen na nule a označuje fázi pracovního postupu, ke které patří vrácené zakázky. Pokud není specifikováno, jeho hodnota je ve výchozím nastavení nastavena na 1 (= první fáze pracovního postupu). Například, pokud potřebuješ získat zakázky z fáze revize, specifikuj číslo této fáze v parametru dotazu, tj. 2.

Volání Stáhnout cílový soubor (asynchronně) spustí asynchronní požadavek na vygenerování a stažení cílového souboru obsahujícího překlady. Neposkytuje přímo cílový soubor v odpovědi, ale vrátí asyncRequestId, který je potřeba pro další volání.

Metoda

PUT
URL požadavku

https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
Odpověď

AsyncRequest ID

Použij Získat asynchronní požadavek s asyncRequestID z odpovědi a ověř, že byl požadavek dokončen. Jakmile je asynchronní požadavek dokončen, můžeš stáhnout cílový soubor pomocí volání Stáhnout cílový soubor na základě asynchronního požadavku. asyncRequestId se dá použít jen jednou. Jakmile stahování začne, asyncRequestId už nebude platný pro další použití.

Metoda

GET
URL požadavku

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

Binární odpověď s dokončeným souborem

Nastav projekt na dokončeno

Aby byl projekt dokončen, jakmile je zakázka v projektu dokončena, použij Upravit stav projektu s povinnými parametry projectUid a status, abys změnil stav celého projektu na Dokončeno. Tato změna je manuální, ale pokud použiješ Project Status Automation, stav se změní automaticky. Můžeš počkat na webhook a spustit další akce podle obdrženého zpětného volání.

Metoda

POST
URL požadavku

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Tělo požadavku
```
{ "stav": "COMPLETED"}
```
Odpověď

Prázdný (Stav 204: Žádný obsah)