Using APIs (TMS)

El contenido se traduce automáticamente del inglés por Phrase Language AI.

Este es un escenario simple de API con llamadas de API de muestra e instrucciones sobre cómo encadenarlas para completar una acción simple utilizando solo APIs. Las opciones que se pueden establecer a través de las APIs son extensas. Consulta las secciones respectivas de documentación de la API REST para saber más sobre todas las opciones disponibles.

La plataforma API Postman se utilizó para crear el escenario.

En estos ejemplos, la URL de solicitud estándar comienza con https://cloud.memsource.com. En caso de que las APIs sean utilizadas por una organización en el centro de datos de EE. UU., la URL de solicitud debe comenzar con https://us.cloud.memsource.com.

Escenario

Autenticación

El usuario está autenticado (el equivalente en la API de iniciar sesión).
Creación

La creación de un proyecto simple, trabajos cargados y asignación de lingüista con notificación por correo electrónico.
Traducción

Trabajo de traducción realizado fuera del escenario de la API (en cualquiera de los editores).
Función de API

Una vez que la asignación esté terminada (marcada como Completed por el lingüista), el estado del proyecto se establece en Completed y se descarga el documento finalizado del proyecto.

Metodología

Cada llamada individual de la API REST tiene un método apropiado listado. Usar un método incorrecto (por ejemplo, GET en lugar de POST en la llamada de creación de proyecto) resulta en una llamada de API no exitosa.

Paso 1: Autenticación

Hay dos métodos de autenticación:

Llamada a la API de autenticación:

Genera un identificador único (token) de autenticación válido por 24 horas. El identificador único (token) debe ser insertado en todas las siguientes API. El identificador único (token) valida a los usuarios y les permite realizar todas las demás funciones dentro del perfil.
oAuth 2.0

Permite la validación de una aplicación. Una aplicación validada está en comunicación continua y no necesita más autenticación.

Para este escenario, se usa la llamada a la API de autenticación. El identificador único (token) generado es requerido para todas las siguientes llamadas a la API y no está listado en los parámetros de ejemplo.

Usa la API Login para autenticación con los parámetros requeridos. En este caso, nombre de usuario y contraseña son requeridos.

Método

POST
URL de solicitud

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

Cuerpo de la solicitud:

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

Respuesta

Token de autenticación.

Los miembros de varias organizaciones TMS tienen el mismo nombre de usuario y contraseña para varias cuentas. En este caso, tienes que agregar el userUid al cuerpo de la solicitud para especificar a qué organización quieres iniciar sesión. Si no se especifica, el usuario inicia sesión en la cuenta predeterminada asociada con el nombre de usuario y la contraseña dados.

Paso 2: Creación, importación y asignación de proyectos

Creación de Proyectos

Utiliza la llamada a la API Projects para crear un proyecto con los parámetros obligatorios name, sourceLang y targetLangs.

Método

POST
URL de solicitud

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

Cuerpo de la solicitud

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

Respuesta

UID del proyecto (por ejemplo, KmtNyVlz1skQd2aMVEipp7)

Es posible crear una plantilla de proyecto utilizando la llamada a la API Crear plantilla de proyecto con el UID del proyecto de la última llamada.

Método

POST
URL de solicitud

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

Cuerpo de la solicitud

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

Respuesta

UID de la plantilla de proyecto (por ejemplo, AmtNyVlz1skQd2aMVEipp8)

La forma más eficiente de crear proyectos es utilizar una plantilla de proyecto. Usa Crear proyecto desde plantilla con el UID de la plantilla de proyecto de la última llamada para crear un nuevo proyecto basado en la configuración de la plantilla de proyecto.

La expresión {templateUid} sirve como marcador de posición en la URL de la solicitud donde se inserta el UID de la plantilla de proyecto obtenida.

Método

POST
URL de solicitud

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

Cuerpo de la solicitud

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

Respuesta

UID del proyecto (por ejemplo, BmtNyVlz1skQd2aMVEipp9)

Creación de trabajo

Con el UID del proyecto de la última llamada, se pueden agregar nuevos trabajos directamente al proyecto recién creado usando Crear trabajo.

La expresión {projectUid} sirve como un marcador de posición en la URL de la solicitud donde se inserta el UID del proyecto obtenido. Con la llamada a la API Crear trabajo, los Headers de la solicitud deben cambiarse para que coincidan con los requeridos por Phrase (en otras llamadas, Postman agrega automáticamente los headers apropiados a la solicitud).

Todos los parámetros de importación deben insertarse en un encabezado personalizado Memsource.

El encabezado Content-Disposition debe incluir el nombre de archivo en un formato predefinido para procesar correctamente la solicitud de importación.

Para importar un archivo fuente, ve al cuerpo, selecciona binary y aparece la opción Seleccionar archivo<2>.

Método

POST
URL de solicitud

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
Response

Job UID (e.g. dOYgeXzAdAbj4xFjuEVZP2)

UID de AsyncRequest

Usa Get asynchronous request con el UID de AsyncRequest de la llamada Crear trabajo para verificar que el trabajo se creó correctamente y que es funcional.

El UID del trabajo devuelto es único en cada paso del flujo de trabajo del proyecto. Por lo tanto, si el trabajo se crea en un proyecto con flujo de trabajo, la respuesta devuelve un UID de trabajo único para cada paso del flujo de trabajo.

Se pueden configurar ajustes de importación reutilizables con la llamada Crear configuración de importación. Se recibe un UID de configuración de importación que puedes usar en la llamada crear trabajo en la respuesta.

Para asignar proveedores al trabajo (a menos que se asignen directamente en la llamada Crear trabajo), usa la llamada Editar trabajo.

El ID del proveedor que se inserta en la llamada se puede obtener de dos maneras:

Para recuperar el ID de la aplicación Phrase, sigue estos pasos:
1. Desde la página de Configuración , desplázate hacia abajo hasta la sección Administración y haz clic en Usuarios o haz clic en Usuarios en la barra lateral.
  
  Se abre la página Usuarios.
2. Haz clic en el apellido del usuario y copia la última parte de la URL del navegador.
3. Usa esta parte como el ID para ese usuario.
Usa la lista de usuarios llamada a la API.

Esta llamada a la API no requiere parámetros específicos y devolverá una lista de todos los usuarios en la cuenta. La respuesta contiene tanto nombres de usuario como ID.

Un parámetro opcional, userName, se puede agregar a la consulta, lo que te permite listar solo usuarios con nombres de usuario específicos.

Notificar a los usuarios asignados

El UID del trabajo se puede usar como un parámetro opcional en la llamada Notificar a los usuarios asignados junto con el parámetro emailTemplate, que representa el ID de la plantilla de correo electrónico que se va a usar. Esto se puede obtener usando la llamada Lista de plantillas de correo electrónico.

URL de solicitud

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

Vacío (Estado 204: Sin contenido)

Aquí es donde el traductor comenzaría a trabajar en su perfil como si se estuviera utilizando la interfaz de usuario de Phrase. Después de que se termine el trabajo, el PM a cargo recibe una notificación y se inicia la siguiente parte del escenario. Se puede interceptar un callback a través de webhooks para iniciar automáticamente la siguiente parte del escenario, pero esto no se abordará en este ejemplo.

Paso 3: Descargar archivo traducido (Completar), establecer proyecto como Completar

Descargar archivo traducido

Este escenario funciona con la suposición de que un traductor termina su tarea (marca el trabajo como Completado), pero el archivo completado se puede descargar en cualquier momento, el trabajo no necesita tener el estado Completado.

Para descargar un archivo traducido, se necesitan dos llamadas a la API: Descargar archivo de destino (asíncrono) y Descargar archivo de destino basado en solicitud asíncrona llamadas.

El primer paso es llamar a Descargar archivo de destino (asíncrono) con los parámetros projectUid y jobUid. Si estás descargando el archivo completado de un proyecto con varios pasos del flujo de trabajo, asegúrate de usar el jobUid del paso del flujo de trabajo específico desde el que te gustaría descargar el archivo completado, por ejemplo, el paso del flujo de trabajo de revisión.

Para recuperar el jobUID para un paso de flujo de trabajo específico de la aplicación Phrase, sigue estos pasos:
1. Abre el proyecto.
2. En la tabla de trabajos, cambia al paso del flujo de trabajo desde el cual te gustaría descargar el archivo completado.
3. Copia la parte única de la URL después de /job desde el navegador.
Usa la lista de trabajos llamada a la API.

Este endpoint devuelve una lista de trabajos dentro del proyecto especificado. Usa la llamada con el parámetro de consulta workflowLevel. Este parámetro no empieza en cero y señala el paso del flujo de trabajo al que pertenecen los trabajos devueltos. Si se deja sin especificar, su valor se establece en 1 (= primer paso de flujo de trabajo) por defecto. Por ejemplo, si necesitas obtener los trabajos del paso de revisión, especifica el número de ese paso en el parámetro de consulta, es decir, 2.

La llamada Descargar archivo de destino (asíncrono) inicia una solicitud asíncrona para generar y descargar el archivo de destino que contiene traducciones. No te proporciona directamente el archivo de destino dentro de la respuesta, sino un asyncRequestId que necesitas para la siguiente llamada.

Método

PUT
URL de solicitud

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

ID de AsyncRequest

Usa Obtener solicitud asíncrona con el asyncRequestID de la respuesta para verificar que la solicitud se ha completado. Una vez que la solicitud asíncrona se ha completado, puedes descargar el archivo de destino usando la llamada Descargar archivo de destino basado en solicitud asíncrona. El asyncRequestId solo se puede usar una vez. Una vez que se inicia la descarga, el asyncRequestId se vuelve inválido para un uso posterior.

Método

GET
URL de solicitud

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

Respuesta binaria con el archivo completado en sí.

Establecer proyecto como completado

Para finalizar el proyecto una vez que el trabajo en el proyecto esté completo, usa la llamada Editar estado del proyecto con los parámetros obligatorios projectUid y estado para cambiar el estado de todo el proyecto a Completado. Este cambio es manual, pero si se usa Automatización del Estado del Proyecto, el estado se cambiará automáticamente. También es posible esperar un webhook e iniciar otras acciones basadas en el callback recibido.

Método

POST
URL de solicitud

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
Cuerpo de la solicitud
```
{ "estado": "COMPLETADO"}
```
Respuesta

vacío (estado 204: No contenido)