Using APIs (TMS)

Contenuti tradotti automaticamente dall'inglese con Phrase Language AI.

Questo è uno scenario API semplice con chiamate API di esempio e istruzioni su come concatenarle per completare un'azione semplice utilizzando solo API. Le opzioni che possono essere impostate tramite le API sono numerose. Consulta le sezioni della documentazione API REST per scoprire di più su tutte le opzioni disponibili.

La piattaforma API Postman è stata utilizzata per creare lo scenario.

In questi esempi, l'URL di richiesta standard inizia con https://cloud.memsource.com. Nel caso in cui le API siano utilizzate da un'organizzazione nel data center degli Stati Uniti, l'URL di richiesta dovrebbe iniziare con https://us.cloud.memsource.com.

Scenario

Autenticazione

L'utente è autenticato (l'equivalente API dell'accesso).
Creazione

La creazione di un progetto semplice, lavori caricati e assegnazione del traduttore con notifica via e-mail.
Traduzione

Lavoro di traduzione svolto al di fuori dello scenario API (in uno qualsiasi degli editor).
Funzione API

Una volta che l'assegnazione è finita (contrassegnata come Completa dal traduttore), lo stato del progetto viene impostato su Completa e il documento completato viene scaricato dal progetto.

Metodologia

Ogni singola chiamata API REST ha un metodo appropriato elencato. Utilizzare un metodo errato (ad es. GET invece di POST nella chiamata di creazione del progetto) comporta una chiamata API non riuscita.

Passaggio 1: Autenticazione

Ci sono due metodi di autenticazione:

Chiamata API di autenticazione:

Genera un token di autenticazione valido per 24 ore. Il token deve essere inserito in tutte le API seguenti. Il token convalida l'utente e gli permette di svolgere qualsiasi altra funzione all'interno del profilo.
oAuth 2.0

Consente la convalida di un'applicazione. Un'applicazione convalidata è in comunicazione continua e non richiede ulteriori autenticazioni.

Per questo scenario, si usa la chiamata API di autenticazione. Il token generato è richiesto per tutte le chiamate API successive e non è elencato tra i parametri di esempio.

Usa l'API Login per l'autenticazione con i parametri richiesti. In questo caso, username e password sono richiesti.

Metodo

POST
Request URL

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

Corpo della richiesta:

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

Risposta

Token di autenticazione.

I membri di più organizzazioni TMS hanno lo stesso username e password per più account. In questo caso, il userUid deve essere aggiunto al corpo della richiesta per specificare a quale organizzazione l'utente desidera accedere. Se non specificato, l'utente accede all'account predefinito associato al nome utente e alla password forniti.

Passaggio 2: Creazione, importazione e assegnazione del progetto

Creazione del Progetto

Usa la chiamata API Progetti per creare un progetto con i parametri obbligatori nome, linguaOrigine e lingueDestinazione.

Metodo

POST
URL della richiesta

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

Corpo della richiesta

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

Risposta

UID del progetto (ad es. KmtNyVlz1skQd2aMVEipp7)

È possibile creare un modello di progetto utilizzando la chiamata API Crea modello di progetto con l'UID del progetto dall'ultima chiamata.

Metodo

POST
URL della richiesta

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

Corpo della richiesta

{
  "project": {
    "uid": "string"
  },
  "nome": "string",
  "importSettings": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Risposta

UID del modello di progetto (es. AmtNyVlz1skQd2aMVEipp8)

Il modo più efficiente per creare progetti è utilizzare un modello di progetto. Usa Crea progetto da modello con l'UID del modello di progetto dall'ultima chiamata per creare un nuovo progetto basato sulle impostazioni del modello di progetto.

L'espressione {templateUid} funge da segnaposto nell'URL della richiesta dove viene inserito l'UID del Modello di Progetto ottenuto.

Metodo

POST
URL della richiesta

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

Corpo della richiesta

{
  "nome": "string",
  "sourceLang": "string",
  "targetLangs": [
    "string"
  ],
  "workflowSteps": [
    {
      "id": "string"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "nota": "string",
  "client": {
    "id": "string"
  },
  "businessUnit": {
    "id": "string"
  },
  "domain": {
    "id": "string"
  },
  "subdomain": {
    "id": "string"
  },
  "costCenter": {
    "id": "string"
  }
}{
  "progetto": {
    "uid": "string"
  },
  "nome": "string",
  "importSettings": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Risposta

Project UID (e.g. BmtNyVlz1skQd2aMVEipp9)

Creazione del Lavoro

Con l'UID del progetto dall'ultima chiamata, nuovi lavori possono essere aggiunti direttamente nel progetto appena creato utilizzando Crea Lavoro.

L'espressione {projectUid} funge da segnaposto nell'URL della richiesta dove viene inserito l'UID del progetto ottenuto. Con la chiamata API Crea Lavoro, il Intestazioni della richiesta deve essere modificato per corrispondere a quelli richiesti da Phrase (in altre chiamate, Postman aggiunge automaticamente intestazioni appropriate alla richiesta).

Tutti i parametri di importazione devono essere inseriti in un'intestazione personalizzata Memsource.

L'intestazione Content-Disposition deve includere il nome del file in un formato predefinito per elaborare correttamente la richiesta di importazione.

Per importare un file sorgente, vai nel corpo della richiesta, seleziona binario e apparirà l'opzione Seleziona File.

Metodo

POST
URL della richiesta

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
Risposta

UID del lavoro (ad es. dOYgeXzAdAbj4xFjuEVZP2)

AsyncRequest UID

Usa Ottieni richiesta asincrona con l'AsyncRequest UID dalla chiamata Create Job per verificare che il lavoro sia stato creato con successo e che funzioni correttamente.

L'UID del lavoro restituito è unico in ogni passaggio del flusso di lavoro del progetto. Pertanto, se il lavoro viene creato in un progetto con flusso di lavoro, la risposta restituisce un UID del lavoro unico per ogni passaggio del flusso di lavoro.

Le impostazioni di importazione riutilizzabili possono essere configurate con la chiamata Create import settings. Un UID di impostazione di importazione che può essere utilizzato nella chiamata Create Job viene ricevuto nella risposta.

Per assegnare fornitori al lavoro (a meno che non siano assegnati direttamente nella chiamata Crea lavoro) usa la chiamata Modifica lavoro.

L'ID del fornitore che viene inserito nella chiamata può essere ottenuto in due modi:

Per recuperare l'ID dall'applicazione Phrase, segui questi passaggi:
1. Dalla pagina impostazioni , scorri verso il basso fino alla sezione Administration e fai clic su Users oppure fai clic su Users nella barra laterale.
  
  Si apre la pagina Utenti.
2. Fai clic sul cognome dell'utente e copia l'ultima parte dell'URL dal browser.
3. Usa questa parte come ID per quell'utente.
Usa il Elenco utenti chiamata API.

Questa chiamata API non richiede parametri specifici e restituirà un elenco di tutti gli utenti nell'account. La risposta contiene sia i nomi utente che gli ID.

Un parametro facoltativo, userName, può essere aggiunto alla query per elencare solo gli utenti con nomi utente specifici.

Notifica agli utenti assegnati

L'UID del lavoro può quindi essere usato come parametro facoltativo nella chiamata Notifica agli utenti assegnati insieme al parametro emailTemplate che rappresenta l'ID del modello di e-mail da usare. Questo si può ottenere usando la chiamata Elenco modelli di e-mail.

URL della richiesta

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

Vuoto (Status 204: Nessun contenuto)

Qui il traduttore inizierebbe a lavorare nel proprio profilo, proprio come se stesse usando l'interfaccia di Phrase. Dopo che il lavoro è completato, il PM responsabile riceve una notifica e la parte successiva dello scenario viene avviata. Un callback può essere intercettato tramite webhooks per avviare automaticamente la parte successiva dello scenario, ma questo non sarà trattato in questo esempio.

Passaggio 3: Scarica il file tradotto (completo), imposta il progetto su completato

Scarica il file tradotto

Questo scenario funziona con l'assunzione che un traduttore termini il proprio incarico (contrassegna il lavoro come Completato), ma il file completato può essere scaricato in qualsiasi momento, il lavoro non deve avere lo stato Completato.

Per scaricare un file tradotto, sono necessarie due chiamate API: Scarica il file di destinazione (async) e Scarica il file di destinazione in base alla richiesta async.

Il primo passo è chiamare Scarica il file di destinazione (async) con i parametri projectUid e jobUid. Se stai scaricando il file completato da un progetto con più passaggi del flusso di lavoro, assicurati di utilizzare il jobUid dal passaggio specifico del flusso di lavoro da cui desideri scaricare il file completato, ad esempio il passaggio del flusso di lavoro di revisione.

Per recuperare il jobUID per un passaggio specifico del flusso di lavoro dall'app Phrase, segui questi passaggi:
1. Apri il progetto.
2. Nella tabella dei lavori, passa al passaggio del flusso di lavoro da cui vuoi scaricare il file completato.
3. Copia la parte unica dell'URL dopo /job dal browser.
Usa la Elenco lavori API call.

Questo endpoint restituisce un elenco di lavori all'interno del progetto specificato. Usa la chiamata con il parametro query workflowLevel. Questo parametro è un parametro non basato su zero che indica il passaggio del flusso di lavoro a cui appartengono i lavori restituiti. Se non specificato, il suo valore è impostato su 1 (= primo passaggio del flusso di lavoro) per impostazione predefinita. Ad esempio, se hai bisogno di ottenere i lavori dal passaggio di revisione, specifica il numero di quel passaggio nel parametro di query, cioè 2.

La chiamata Scarica file di destinazione (async) avvia una richiesta asincrona per generare e scaricare il file di destinazione contenente le traduzioni. Non fornisce direttamente il file di destinazione all'interno della risposta, ma un asyncRequestId necessario per la chiamata successiva.

Metodo

PUT
URL della richiesta

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

AsyncRequest ID

Usa Get asynchronous request con il asyncRequestID dalla risposta per verificare che la richiesta sia stata completata. Una volta completata la richiesta asincrona, puoi scaricare il file di destinazione usando la chiamata Download target file based on async request. Il asyncRequestId può essere utilizzato solo una volta. Una volta avviato il download, il asyncRequestId diventa non valido per ulteriori utilizzi.

Metodo

GET
URL della richiesta

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

Risposta binaria con il file completo stesso

Imposta il progetto su completato

Per finalizzare il progetto, una volta che il lavoro nel progetto è completo, usa la chiamata Modifica stato del progetto con i parametri obbligatori projectUid e stato per modificare lo stato dell'intero progetto in Completato. Questa modifica è manuale, ma se viene utilizzata Automazione dello stato del progetto, lo stato verrà modificato automaticamente. È anche possibile attendere un webhook e avviare altre azioni in base al callback ricevuto.

Metodo

POST
Request URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Request body<1>
```
{ "status": "COMPLETED"}
```
Risposta

Vuoto (Stato 204: Nessun contenuto)