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, nahrané zakázky a přiřazení překladatele s e-mailovým oznámením.
Translation

Překlad 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 je nastaven na Dokončit a hotový dokument je stažen 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 nevyžaduje žá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í projektu, import a přiřazení

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 projektovou šablonu pomocí volání API Vytvořit projektovou šablonu 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 projektové šablony (např. AmtNyVlz1skQd2aMVEipp8)

Nejefektivnějším způsobem vytváření projektů je použít projektovou šablonu. Použijte Vytvořit projekt ze šablony s ID projektové šablony z posledního volání pro vytvoření nového projektu na základě nastavení projektové šablony.

Výraz {templateUid} slouží jako zástupný znak v URL požadavku, kam se vkládá získané ID projektové šablony.

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 nejsou 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 Administrace 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.<6

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.

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

UID zakázky lze poté 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ž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 bylo použito uživatelské rozhraní Phrase. Po dokončení zakázky obdrží odpovědný PM oznámení a je zahájena Další část scénáře. Zpětné volání lze zachytit prostřednictvím webhooks pro automatické spuštění Další části 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čený

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.

Pro stáhnout přeložený soubor jsou potřeba dvě API volání: Stáhnout cíl soubor (async) a Stáhnout cíl soubor na základě async požadavku volání.

První fáze je zavolat Stáhnout cíl soubor (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žít jobUid z konkrétní fáze pracovního postupu, ze které chcete stáhnout dokončený soubor, např. fáze pracovního postupu revize.

Pro získání 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žít Seznam zakázek API volání.

Tento koncový bod vrací seznam zakázek v rámci zadaného projektu. Použít volání s parametrem dotazu workflowLevel. Tento parametr je parametr, který 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 v parametru dotazu, tj. 2.

Volání Stáhnout cíl soubor (async) zahájí asynchronní požadavek na vygenerování a stáhnout cílový soubor obsahující 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 AsyncRequest

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íl soubor pomocí volání Download target file based on async request. asyncRequestId lze použít pouze jednou. Jakmile je stáhnout iniciováno, asyncRequestId se stane neplatným pro další použít.

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čit souborem

Nastavit projekt na stav Dokončit

Pro finalizaci 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ěnit je manuální, ale pokud je použít 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)