Using APIs (TMS)

O conteúdo de toda a Central de Ajuda é traduzido automaticamente de inglês pelo Phrase Language AI.

Este é um cenário simples de API com chamadas de API de exemplo e instruções sobre como encadeá-las para concluir uma ação simples usando apenas APIs. As opções que podem ser definidas via APIs são extensas. Consulte as seções respectivas da documentação da API REST para saber mais sobre todas as opções disponíveis.

A plataforma de API Postman foi usada para criar o cenário.

Nestes exemplos, a URL de solicitação padrão começa com https://cloud.memsource.com. Caso as APIs sejam usadas por uma organização no centro de dados dos EUA, a URL de solicitação deve começar com https://us.cloud.memsource.com.

Cenário

Autenticação

O usuário está autenticado (o equivalente da API ao login).
Criação

A criação de um projeto simples, trabalhos enviados e atribuição de Linguista com notificação por e-mail.
Tradução

Trabalho de tradução realizado fora do cenário da API (em qualquer um dos Editores).
Função da API

Uma vez que a atribuição é concluída (marcada como Concluído pelo Linguista), o status do projeto é definido como Concluído e o documento finalizado é baixado do projeto.

Metodologia

Cada chamada individual da API REST tem um método apropriado listado. Usar um método incorreto (por exemplo, GET em vez de POST na chamada de criação do projeto) resulta em uma chamada de API malsucedida.

Etapa 1: Autenticação

Existem dois métodos de autenticação:

Chamada da API de Autenticação:

Gera um token de autenticação válido por 24 horas. O token precisa ser inserido em todas as APIs seguintes. O token valida os usuários e permite que eles realizem outras funções dentro do perfil.
oAuth 2.0

Permite a validação de um aplicativo. Um aplicativo validado está em comunicação contínua e não precisa de mais autenticação.

Para o cenário, a chamada da API de Autenticação é usada. O token gerado é necessário para todas as chamadas de API seguintes e não está listado nos parâmetros de exemplo.

Use a API Login para autenticação com os parâmetros necessários. Neste caso, nome de usuário e senha são obrigatórios.

Método

POST
URL da Solicitação

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

Corpo da Solicitação:

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

Resposta

Token de autenticação.

Membros de várias organizações TMS têm o mesmo nome de usuário e senha para várias contas. Neste caso, o userUid deve ser adicionado ao corpo da solicitação para especificar a qual organização o usuário deseja fazer login. Se não especificado, o usuário está logado na conta padrão associada ao nome de usuário e senha fornecidos.

Etapa 2: Criação, Importação e Atribuição de Projeto

Criação de Projeto

Use a chamada da API Projetos para criar um projeto com os parâmetros obrigatórios nome, sourceLang e targetLangs.

Método

POST
URL da Solicitação

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

Corpo da solicitação

{ "name":"Meu projeto", "sourceLang":"en", "targetLangs":[ "de","fr" ]}

Resposta

UID do Projeto (ex: KmtNyVlz1skQd2aMVEipp7)

É possível criar um modelo de projeto usando a chamada da API Criar modelo de projeto com o UID do projeto da última chamada.

Método

POST
URL da Solicitação

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

Corpo da solicitação

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

Resposta

UID do Modelo de Projeto (ex: AmtNyVlz1skQd2aMVEipp8)

A maneira mais eficiente de criar projetos é usar um modelo de projeto. Use Criar projeto a partir do modelo com o UID do Modelo de Projeto da última chamada para criar um novo projeto com base nas configurações do modelo de projeto.

A expressão {templateUid} serve como um marcador de posição na URL da solicitação onde o UID do Modelo de Projeto obtido é inserido.

Método

POST
URL da Solicitação

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

Corpo da solicitação

{
  "name": "string",
  "sourceLang": "string",
  "targetLangs": [
    "string"
  ],
  "workflowSteps": [
    {
      "id": "string"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "nota": "string",
  "cliente": {
    "id": "string"
  },
  "businessUnit": {
    "id": "string"
  },
  "domínio": {
    "id": "string"
  },
  "subDomain": {
    "id": "string"
  },
  "costCenter": {
    "id": "string"
  }
}{
  "project": {
    "uid": "string"
  },
  "name": "string",
  "importSettings": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

Resposta

UID do Projeto (ex: BmtNyVlz1skQd2aMVEipp9)

Criação de Trabalho

Com o UID do projeto da última chamada, novos trabalhos podem ser adicionados diretamente ao projeto recém-criado usando Criar Trabalho.

A expressão {projectUid} serve como um marcador de posição na URL da solicitação onde o UID do Projeto obtido é inserido. Com a chamada da API Criar Trabalho, o Headers da solicitação deve ser alterado para corresponder aos que são exigidos pela Phrase (em outras chamadas, o Postman adiciona automaticamente os cabeçalhos apropriados à solicitação).

Todos os parâmetros de importação precisam ser inseridos em um cabeçalho personalizado Memsource.

O cabeçalho Content-Disposition deve incluir o nome do arquivo em um formato predefinido para processar corretamente a solicitação de importação.

Para importar um arquivo de origem, vá para o corpo, selecione binário e a opção Selecionar Arquivo aparece.

Método

POST
URL da Solicitação

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
(Cabeçalho) Content-Disposition

filename*=UTF-8''file.txt
(Cabeçalho) Memsource

{"targetLangs":["de","fr"]}
(Cabeçalho) Content-Type

application/octet-stream
Resposta

Job UID (e.g. dOYgeXzAdAbj4xFjuEVZP2)

AsyncRequest UID

Use Obter solicitação assíncrona com o UID da Solicitação Assíncrona da chamada Criar Trabalho para verificar se o trabalho foi criado com sucesso e se está funcional.

O UID do Trabalho retornado é único em cada etapa do fluxo de trabalho do projeto. Portanto, se o trabalho for criado em um projeto com fluxo de trabalho, a resposta retorna um UID de Trabalho único para cada etapa do fluxo de trabalho.

As configurações de importação reutilizáveis podem ser configuradas com a chamada Criar configurações de importação. Um UID de configuração de importação que pode ser usado na chamada de criação de trabalho é recebido na resposta.

Para atribuir provedores ao trabalho (a menos que atribuídos diretamente na chamada Criar trabalho), use a chamada Editar trabalho.

O ID do Provedor que é inserido na chamada pode ser obtido de duas maneiras:

Para recuperar o ID do aplicativo Phrase, siga estas etapas:
1. Na página de Configurações , role para baixo até a seção Administração e clique em Usuários ou clique em Usuários na barra lateral.
  
  A página Usuários é aberta.
2. Clique no sobrenome do usuário e copie a última parte da URL do navegador.
3. Use esta parte como o ID para esse usuário.
Use o Listar usuários chamada da API.

Esta chamada da API não requer parâmetros específicos e retornará uma lista de todos os usuários na conta. A resposta contém tanto nomes de usuário quanto IDs.

Um parâmetro opcional, nomeDeUsuário, pode ser adicionado à consulta permitindo que você liste apenas usuários com nomes de usuário específicos.

Notificar Usuários Atribuídos

O UID do trabalho pode então ser usado como um parâmetro opcional na chamada Notificar usuários atribuídos junto com o parâmetro modeloDeEmail representando o ID do modelo de e-mail a ser usado. Isso pode ser obtido usando a chamada Listar modelos de e-mail.

URL da Solicitação

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

Vazio (Status 204: Sem conteúdo)

É aqui que o tradutor começaria a trabalhar em seu perfil, assim como se a interface do usuário do Phrase estivesse sendo usada. Após a conclusão do trabalho, o GP responsável recebe uma notificação, e a próxima parte do cenário é iniciada. Um callback pode ser interceptado via webhooks para iniciar automaticamente a próxima parte do cenário, mas isso não será abordado neste exemplo.

Etapa 3: Baixar arquivo traduzido (Completo), definir projeto como Concluído

Baixar arquivo traduzido

Este cenário funciona com a suposição de que um tradutor conclui sua tarefa (marca o trabalho como Concluído), mas o arquivo concluído pode ser baixado a qualquer momento, o trabalho não precisa ter o status Concluído.

Para baixar um arquivo traduzido, são necessárias duas chamadas de API: Baixar arquivo de destino (assíncrono) e Baixar arquivo de destino com base na solicitação assíncrona chamadas.

A primeira etapa é chamar Baixar arquivo de destino (assíncrono) com os parâmetros projectUid e jobUid. Se você estiver baixando o arquivo concluído de um projeto com várias etapas de fluxo de trabalho, certifique-se de usar o jobUid da etapa de fluxo de trabalho específica da qual você gostaria de baixar o arquivo concluído, por exemplo, etapa de revisão do fluxo de trabalho.

Para recuperar o jobUID para uma etapa de fluxo de trabalho específica do aplicativo Phrase, siga estas etapas:
1. Abra o projeto.
2. Na tabela de Trabalhos, mude para a etapa de fluxo de trabalho da qual você gostaria de baixar o arquivo concluído.
3. Copie a parte única da URL após /job do navegador.
Use o Lista de trabalhos chamada de API.

Este endpoint retorna uma lista de trabalhos dentro do projeto especificado. Use a chamada com o parâmetro de consulta workflowLevel. Este parâmetro é um parâmetro não baseado em zero que indica a etapa de fluxo de trabalho à qual os trabalhos retornados pertencem. Se não especificado, seu valor é definido como 1 (= primeira etapa de fluxo de trabalho) por padrão. Por exemplo, se você precisar obter os trabalhos da etapa de revisão, especifique o número dessa etapa no parâmetro de consulta, ou seja, 2.

A chamada do arquivo de destino para download (assíncrona) inicia uma solicitação assíncrona para gerar e baixar o arquivo de destino contendo traduções. Não fornece diretamente o arquivo de destino na resposta, mas um asyncRequestId necessário para a chamada seguinte.

Método

PUT
URL da Solicitação

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

AsyncRequest ID

Use Obter solicitação assíncrona com o asyncRequestID da resposta para verificar se a solicitação foi concluída. Uma vez que a solicitação assíncrona é concluída, você pode baixar o arquivo de destino usando a chamada Baixar arquivo de destino com base na solicitação assíncrona. O asyncRequestId pode ser usado apenas uma vez. Uma vez que o download é iniciado, o asyncRequestId se torna inválido para uso posterior.

Método

INSTALAR
URL da Solicitação

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

Resposta binária com o arquivo concluído em si

Definir Projeto como Concluído

Para finalizar o projeto uma vez que o trabalho no projeto esteja completo, use a chamada Editar status do projeto com os parâmetros obrigatórios projectUid e status para alterar o status de todo o projeto para Concluído. Essa mudança é manual, mas se Automação de Status do Projeto for usada, o status será alterado automaticamente. Também é possível aguardar um webhook e iniciar outras ações com base no callback recebido.

Método

POST
URL da Solicitação

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Corpo da solicitação
```
{ "status": "CONCLUÍDO"}
```
Resposta

Vazio (Status 204: Sem conteúdo)