Používání API (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 zřetězit k dokončení jednoduché akce pouze pomocí API. Možnosti, které lze nastavit prostřednictvím API, jsou rozsáhlé. Další informace o všech dostupných možnostech naleznete v příslušných částech dokumentace REST API.

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

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

Scenario

Ověřování

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

Vytvoření jednoduchého projektu, nahrání zakázek a přiřazení překladatele s e-mailovým oznámením.
Translation

Překladatelská zakázka provedená mimo scénář API (v jakémkoli z editorů).
Funkce API

Jakmile je zakázka dokončena (označena překladatelem jako Dokončit), stav projektu se nastaví na Dokončit a hotový dokument se stáhne z projektu.

Metodika

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

Fáze 1: ověřování

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

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

Vygeneruje 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 nepřetržité komunikaci a nepotřebuje žádné další ověřování.

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í volání API a není uveden v příkladech parametrů.

Použijte API Login pro ověřování s požadovanými parametry. V tomto případě jsou vyžadovány username a password.

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 organizací TMS mají stejné uživatelské jméno a heslo pro více účtů. V tomto případě musí být do těla požadavku přidán userUid, aby bylo určeno, ke které organizaci se uživatel chce přihlásit. Pokud není určeno jinak, uživatel je přihlášen k výchozímu uživatelskému účtu přidruženému k danému uživatelskému jménu a heslu.

Fáze 2: Vytvoření, import a přiřazení projektu

Vytvoření projektu

Použijte volání API projekty k vytvoření projektu s povinnými parametry název, 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ěď

ID projektu (např. KmtNyVlz1skQd2aMVEipp7)

Je možné vytvořit šablonu projektu pomocí volání API Vytvořit šablonu projektu s ID 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": "string",
  "importSettings": {
    "uid": "řetězec"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Odpověď

ID šablony projektu (např. AmtNyVlz1skQd2aMVEipp8)

Nejefektivnějším způsobem vytváření projektů je použít šablonu projektu. Použijte Vytvořit projekt ze šablony s ID š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 se vkládá získané ID šablony projektu.

Metoda

POST
URL požadavku

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

Tělo požadavku

{
  "name": "string",
  "sourceLang": "string",
  "targetLangs": [
    "řetězec"
  ],
  "workflowSteps": [
    {
      "id": "ID"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "string",
  "client": {
    "id": "ID"
  },
  "businessUnit": {
    "id": "ID"
  },
  "domain": {
    "id": "ID"
  },
  "subDomain": {
    "id": "ID"
  },
  "costCenter": {
    "id": "ID"
  }
}{
  "project": {
    "uid": "řetězec"
  },
  "name": "string",
  "importSettings": {
    "uid": "řetězec"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Odpověď

Project UID (e.g. BmtNyVlz1skQd2aMVEipp9)

Vytvoření zakázky

S UID projektu z posledního volání lze nové zakázky přidat 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 vkládá získané UID projektu. U volání API Vytvořit zakázku musí být Záhlaví požadavku změněna tak, aby odpovídala těm, která vyžaduje Phrase (v ostatních voláních Postman automaticky přidává k požadavku příslušná záhlaví).

Všechny parametry importu je třeba vložit do vlastního záhlaví Memsource.

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řejděte do těla, vyberte binární a zobrazí se možnost Vybrat soubor.

Metoda

POST
URL požadavku

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
(Záhlaví) Content-Disposition

filename*=UTF-8''file.txt
(Záhlaví) Memsource

{"targetLangs":["de","fr"]}
(Záhlaví) 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 pro kontrolu, zda byla zakázka úspěšně vytvořena a zda je funkční.

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

Znovu použitelné nastavení importu lze nakonfigurovat pomocí volání Vytvořit nastavení importu. UID nastavení importu, které lze použít ve volání Vytvořit zakázku, je obsaženo v odpovědi.

Pro přiřazení poskytovatelů k zakázce (pokud nebyli přiřazeni přímo ve volání Vytvořit zakázku) použijte volání Upravit zakázku.

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

Chcete-li získat ID z aplikace Phrase, postupujte podle těchto kroků:
1. Na stránce nastavení přejděte dolů do sekce Správa a klikněte na Uživatelé nebo klikněte na Uživatelé v postranním panelu.
  
  Otevře se stránka Uživatelé.
2. Klikněte na příjmení uživatele a zkopírujte poslední část adresy URL z prohlížeče.
3. Tuto část použijte jako ID pro daného uživatele.
Použijte Seznam uživatelů volání API.

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

K dotazu lze přidat volitelný parametr userName, který vám umožní vypsat pouze uživatele se specifickými uživatelskými jmény.

Upozornit přiřazené uživatele

UID zakázky lze poté použít jako volitelný parametr ve volání Upozornit přiřazené uživatele spolu s parametrem emailTemplate, který představuje ID šablony e-mailu, jež má být použita. To lze získat 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)

Zde by překladatel začal pracovat ve svém profilu, stejně jako kdyby používal uživatelské rozhraní Phrase. Po dokončení zakázky obdrží odpovědný PM oznámení a spustí se další fáze scénáře. Zpětné volání lze zachytit prostřednictvím webhooks pro automatické spuštění další fáze scénáře, ale tím se v tomto příkladu nebudeme zabývat.

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

Stáhnout přeložený soubor

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

Ke stažení přeloženého souboru jsou potřeba dvě API volání: Stáhnout cíl (async) a Stáhnout cíl na základě asynchronního požadavku volání.

První fáze je zavolat Stáhnout cíl (async) s parametry projectUid a jobUid. Pokud stahujete dokončený soubor z projektu s více fázemi pracovního postupu, ujistěte se, že použijete jobUid z konkrétní fáze pracovního postupu, ze které chcete dokončený soubor stáhnout, např. fáze revize.

Chcete-li získat jobUID pro konkrétní fázi pracovního postupu z aplikace Phrase, postupujte podle těchto kroků:
1. Otevřete projekt.
2. V tabulce Zakázky přepněte na fázi pracovního postupu, ze které chcete stáhnout dokončený soubor.
3. Zkopírujte unikátní část URL za /job z prohlížeče.
Použijte seznam zakázek API volání.

Tento koncový bod vrací seznam zakázek v rámci zadaného projektu. Použijte volání s dotazem workflowLevel. Tento parametr není založen na nule a označuje fázi pracovního postupu, do které vrácené zakázky patří. Pokud není zadán, jeho hodnota je ve výchozím nastavení nastavena na 1 (= první fáze pracovního postupu). Pokud například potřebujete získat zakázky z fáze revize, zadejte číslo této fáze do dotazu, tj. 2.

Volání Stáhnout cíl (async) zahájí 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 rámci odpovědi, ale asyncRequestId vyžadované pro následující volání.

Metoda

PUT
URL požadavku

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

ID asynchronního požadavku

Použijte Get asynchronous request s asyncRequestID z odpovědi pro kontrolu, zda je požadavek Dokončit. Jakmile je asynchronní požadavek Dokončit, můžete Stáhnout cílový soubor pomocí volání Download target file based on async request. asyncRequestId lze použít pouze jednou. Jakmile je Stáhnout zahájeno, asyncRequestId se stane neplatným 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ěď se samotným dokončeným souborem

Nastavit projekt na stav Dokončit

Pro dokončení projekt, jakmile je zakázka v projekt Dokončit, použít volání Edit project status s povinnými parametry projectUid a status pro změnit stav celého projekt na Completed. Tato změna je manuální, ale pokud je použita Project Status Automation, stav bude změnit automaticky. Je také možné počkat na webhook a iniciovat další akce na základě přijaté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)