Translator v3.0

Novedades

La versión 3.0 de Translator proporciona una API web moderna basada en JSON. Mejora la facilidad de uso y rendimiento mediante la consolidación de las características existentes en menos operaciones y proporciona nuevas características.

• Transliteración para convertir texto en un idioma de un script a otro.
• Traducción a varios idiomas en una sola solicitud.
• Detección de idioma, traducción y transliteración en una sola solicitud.
• Diccionario para buscar traducciones alternativas de un término, traducciones inversas y ejemplos que muestren los términos usados en contexto.
• Resultados de detección de idioma más informativos.

Direcciones URL base

En la mayoría de los casos, las solicitudes dirigidas a Translator se administran en el centro de datos que está más próximo a la ubicación donde se ha originado la solicitud. Si se produce un error en el centro de datos al usar el punto de conexión global, la solicitud se puede enrutar fuera de la geografía.

Para forzar el control de la solicitud dentro de una geografía específica, use el punto de conexión geográfico deseado. Todas las solicitudes se procesan entre los centros de datos dentro de la geografía.

✔️ Característica: Translator Text

Punto de conexión de servicio	Solicitud del centro de datos de procesamiento
Global (recomendado): api.cognitive.microsofttranslator.com	Centro de datos más cercano disponible.
Américas: api-nam.cognitive.microsofttranslator.com	Este de EE. UU. 2 • Oeste de EE. UU. 2
Asia Pacífico: api-apc.cognitive.microsofttranslator.com	Este de Japón • Sudeste asiático
Europa (excepto Suiza): api-eur.cognitive.microsofttranslator.com	Centro de Francia • Oeste de Europa
Suiza: para obtener más información, consulte Puntos de conexión de servicio de Suiza.	Norte de Suiza • Oeste de Suiza

Puntos de conexión de servicio de Suiza

Los clientes con un recurso ubicado en las regiones Norte de Suiza u Oeste de Suiza pueden estar seguro de que sus solicitudes de Text API se atienden en Suiza. Para asegurarse de que las solicitudes se controlan en Suiza, cree el recurso de Traductor en la Resource regionSwitzerland North u Switzerland West y, a continuación, use el punto de conexión personalizado del recurso en las solicitudes de API.

Por ejemplo, si crea un recurso de Translator en Azure Portal con una Resource region como Switzerland North y el nombre de recurso es my-swiss-n, después el punto de conexión personalizado será https​://my-swiss-n.cognitiveservices.azure.com. Y una solicitud de ejemplo para traducir sería:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

El servicio Traductor personalizado no está disponible actualmente en Suiza.

Autenticación

Suscríbase a Translator o a los diferentes servicios de servicios de Azure AI y use la clave (disponible en Azure Portal) para autenticarse.

Hay tres encabezados que puede usar para autenticar su suscripción. En esta tabla, se explica cómo se utiliza cada uno de ellos:

encabezados	Descripción
Ocp-Apim-Subscription-Key	Úselo con la suscripción a servicios de Azure AI si pasa su clave secreta. El valor es la clave secreta de Azure para su suscripción a Translator.
Autorización	Úselo con la suscripción a servicios de Azure AI si pasa un token de autenticación. El valor es el token de portador: Bearer <token>.
Ocp-Apim-Subscription-Region	Úselo con el recurso de traductor regional y de varios servicios. El valor es la región del recurso de traductor de varios servicios o regional. Este valor es opcional cuando se usa un recurso de traductor global.

Clave secreta

La primera opción consiste en realizar la autenticación con el encabezado Ocp-Apim-Subscription-Key. Agregue el encabezado Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> a la solicitud.

Autenticación con un recurso global

Cuando se usa un recurso de traductor global, es necesario incluir un encabezado para llamar a Translator.

encabezados	Descripción
Ocp-Apim-Subscription-Key	El valor es la clave secreta de Azure para su suscripción a Translator.

A continuación se muestra una solicitud de ejemplo para llamar a Translator mediante el recurso de traductor global.

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Autenticación con un recurso regional

Cuando se usa un recurso de traductor regional, hay dos encabezados que debe llamar a Translator.

encabezados	Descripción
Ocp-Apim-Subscription-Key	El valor es la clave secreta de Azure para su suscripción a Translator.
Ocp-Apim-Subscription-Region	El valor es la región del recurso de traductor.

A continuación se muestra una solicitud de ejemplo para llamar a Translator mediante el recurso de traductor regional.

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Autenticación con un recurso de varios servicios

Un recurso de varios servicios le permite usar una clave de API única para autenticar las solicitudes de varios servicios.

Si usa una clave secreta para varios servicios, debe incluir dos encabezados de autenticación con la solicitud. Hay dos encabezados que necesita para llamar a Translator.

encabezados	Descripción
Ocp-Apim-Subscription-Key	El valor es la clave secreta de Azure para el recurso de varios servicios.
Ocp-Apim-Subscription-Region	El valor es la región del recurso de varios servicios.

La región es obligatoria en la suscripción de varios servicios de Text API. La región que selecciona es la única región que puede usar para la traducción de texto al usar la clave de varios servicios. Debe ser la misma región que seleccionó al registrarse en la suscripción a varios servicios a través de Azure Portal.

Si decide pasar la clave secreta en la cadena de consulta con el parámetro Subscription-Key, tendrá que especificar la región con el parámetro de consulta Subscription-Region.

Autenticación con token de acceso

Si lo desea, también puede cambiar la clave secreta por un token de acceso. Este token se incluirá en cada solicitud como un encabezado Authorization. Para obtener un token de autorización, realice una solicitud POST a la dirección URL siguiente:

Tipo de recurso	URL del servicio de autenticación
Global	https://api.cognitive.microsoft.com/sts/v1.0/issueToken
Regional o de varios servicios	https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Estas son algunas solicitudes de ejemplo para obtener un token una vez proporcionada una clave secreta para un recurso global:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Estas son algunas solicitudes de ejemplo para obtener un token una vez proporcionada una clave secreta para un recurso regional ubicado en Centro de EE. UU.:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Una solicitud correcta devuelve el token de acceso codificado como texto sin formato en el cuerpo de respuesta. El token válido se pasa al servicio Translator como un token de portador en la autorización.

Authorization: Bearer <Base64-access_token>

Un token de autenticación tiene una validez de 10 minutos. El token debe volver a usarse al realizar varias llamadas a Translator. Sin embargo, si el programa realiza las solicitudes a Translator durante un período de tiempo prolongado, el programa debe solicitar un nuevo token de acceso a intervalos regulares (por ejemplo, cada 8 minutos).

Autenticación con Microsoft Entra ID

Translator v3.0 es compatible con la autenticación de Microsoft Entra, la solución de administración de identidades y acceso basada en la nube de Microsoft. Los encabezados de autorización permiten que el servicio Translator valide que el cliente solicitante está autorizado para usar el recurso y complete la solicitud.

Requisitos previos

• Conocimientos básicos de cómo autenticarse con Microsoft Entra ID.

• Conocimientos básicos de cómo autorizar el acceso a identidades administradas.

Encabezados

Encabezado	Valor
Authorization	El valor es un token de portador de acceso generado por Azure AD . El token de portador proporciona una prueba de autenticación y valida la autorización del cliente para usar el recurso. Un token de autenticación es válido durante 10 minutos y debe reutilizarse al realizar varias llamadas a Translator. Consulte Solicitud de ejemplo: 2. Obtención de un token
Ocp-Apim-Subscription-Region	El valor es la región del recurso de traductor. Este valor es opcional si el recurso es global.
Ocp-Apim-ResourceId	El valor es el identificador de recurso de la instancia del recurso de Translator. Encontrará el id. de recurso en Azure Portal, en Recurso de Translator → Propiedades. Formato de identificador de recurso: /subscriptions/<IdDeSuscripción>/resourceGroups/<NombredelGrupodeRecursos>/providers/Microsoft.CognitiveServices/accounts/<NombreDeRecurso>/

Página de propiedades de Translator: Azure Portal

Importante

Asigne el rol de usuario de Cognitive Services a la entidad de servicio. Al asignar este rol, va a conceder acceso a la entidad de servicio al recurso translator.

Ejemplos

Con el punto de conexión global

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Con el punto de conexión personalizado

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Ejemplos con las identidades administradas

Translator v3.0 también es compatible con la autorización del acceso a identidades administradas. Si una identidad administrada está habilitada para un recurso de traductor, puede pasar el token de portador generado por la identidad administrada en el encabezado de solicitud.

Con el punto de conexión global

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Con el punto de conexión personalizado

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Compatibilidad con redes virtuales

El servicio Traductor ahora está disponible con las funcionalidades de Virtual Network (VNET) en todas las regiones de la nube pública de Azure. Para habilitar Virtual Network, consulte Configuración de redes virtuales de servicios de Azure AI.

Una vez que se activa esta funcionalidad, se debe usar el punto de conexión personalizado para llamar a Translator. No se puede usar el punto de conexión de traductor global ("api.cognitive.microsofttranslator.com") y no se puede autenticar con un token de acceso.

Puede encontrar el punto de conexión personalizado después de crear un recurso de Translator y permitir el acceso desde redes seleccionadas y puntos de conexión privados.

1. Vaya hasta la página del recurso de Translator en Azure Portal.

2. Seleccione Redes en la sección Administración de recursos.

3. En la pestaña Firewalls y redes virtuales, seleccione Redes y puntos de conexión privados seleccionados.

   

4. Seleccione Guardar para aplicar los cambios.

5. En la sección Administración del recurso, seleccione Claves y puntos de conexión.

6. Seleccione la pestaña Virtual Network.

7. En la lista se muestran los puntos de conexión para la traducción de texto y la traducción de documentos.

   

encabezados	Descripción
Ocp-Apim-Subscription-Key	El valor es la clave secreta de Azure para su suscripción a Translator.
Ocp-Apim-Subscription-Region	El valor es la región del recurso de traductor. Este valor es opcional si el recurso es global.

A continuación se muestra una solicitud de ejemplo para llamar a Translator mediante el punto de conexión personalizado.

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Errors

Una respuesta de error estándar es un objeto JSON con el par de nombre/valor denominado error. El valor también es un objeto JSON con propiedades:

• code: código de error definido por el servidor.
• message: cadena que proporciona una representación legible del error.

Por ejemplo, un cliente con una suscripción de prueba gratuita recibiría el error siguiente una vez agotada la cuota gratuita:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

El código de error es un número de 6 dígitos que combina el código de estado HTTP de 3 dígitos y otro número de 3 dígitos que ayuda a categorizar aún más el error. Los códigos de error comunes son:

Código	Descripción
400000	Una de las entradas de la solicitud no es válida.
400001	El parámetro "scope" no es válido.
400002	El parámetro "category" no es válido.
400003	Falta un especificador de lenguaje o no es válido.
400004	Falta un especificador de script de destino ("To script") o no es válido.
400005	Falta un texto de entrada o no es válido.
400006	La combinación de lenguaje y script no es válida.
400018	Falta un especificador de script de origen ("From script") o no es válido.
400019	No se admite uno de los lenguajes especificados.
400020	Uno de los elementos de la matriz de texto de entrada no es válido.
400021	Falta un parámetro de la versión de API o no es válido.
400023	Uno de los pares de lenguaje especificados no es válido.
400035	El lenguaje fuente (campo "From") no es válido.
400036	Falta el lenguaje de destino (campo "To") o no es válido.
400042	Una de las opciones especificadas (campo "Options") no es válida.
400043	El identificador de seguimiento de cliente (campo ClientTraceId o encabezado X-ClientTraceId) falta o no es válido.
400050	El texto de entrada es demasiado largo. Consulte los límites de solicitud.
400064	Falta un parámetro "translation" o no es válido.
400070	El número de scripts de destino (parámetro ToScript) no coincide con el número de lenguajes de destino (parámetro To).
400071	Valor no válido para TextType.
400072	La matriz de texto de entrada tiene demasiados elementos.
400073	El parámetro de script no es válido.
400074	El cuerpo de la solicitud no es un JSON válido.
400075	La combinación de categoría y par de lenguaje no es válida.
400077	Se superó el tamaño máximo de solicitud. Consulte los límites de solicitud.
400079	El sistema personalizado solicitado para la traducción entre, desde y hacia el lenguaje no existe.
400080	La transliteración no se admite para el idioma o el script.
401000	La solicitud no está autorizada porque faltan las credenciales o no son válidas.
401015	"Las credenciales proporcionadas son para Speech API. Esta solicitud requiere credenciales para Text API. Use una suscripción a Translator".
403000	La operación no está permitida.
403001	No se permite la operación porque la suscripción superó su cuota disponible.
405000	No se admite el método de solicitud para el recurso solicitado.
408001	Se está preparando el sistema de traducción solicitado. Vuelva a intentarlo en unos minutos.
408002	La solicitud superó el tiempo de espera mientras se esperaba la secuencia entrante. El cliente no presentó una solicitud en el tiempo que el servidor estaba preparado para esperar. El cliente puede repetir la solicitud sin modificaciones en cualquier momento posterior.
415000	Falta el encabezado Content-Type o no es válido.
429000, 429001, 429002	El servidor rechazó la solicitud porque el cliente superó los límites de solicitudes.
500000	Se ha producido un error inesperado. Si el error continúa, notifíquelo con la fecha y hora del error, con el identificador de la solicitud del encabezado de respuesta X-RequestId y con el identificador de cliente del encabezado de solicitud X-ClientTraceId.
503000	El servicio no está disponible temporalmente. Reintentar. Si el error continúa, notifíquelo con la fecha y hora del error, con el identificador de la solicitud del encabezado de respuesta X-RequestId y con el identificador de cliente del encabezado de solicitud X-ClientTraceId.

Métricas

Las métricas le permiten ver la información de uso y disponibilidad del traductor en Azure Portal, en la sección de métricas, tal como se muestra en la captura de pantalla siguiente. Para obtener más información, vea Métricas de datos y plataforma.

En esta tabla se enumeran las métricas disponibles con la descripción de cómo se usan para supervisar las llamadas API de traducción.

Métricas	Descripción
TotalCalls	Número total de llamadas a API.
TotalTokenCalls	Número total de llamadas API a través del servicio de token mediante el token de autenticación.
SuccessfulCalls	Número de llamadas correctas.
TotalErrors	Número de llamadas con respuesta de error.
BlockedCalls	Número de llamadas que han superado la tasa o el límite de cuota.
ServerErrors	Número de llamadas con error interno del servidor (5XX).
ClientErrors	Número de llamadas con error en el cliente (4XX).
Latencia	Duración para completar la solicitud en milisegundos.
CharactersTranslated	Número total de caracteres de la solicitud entrante de texto.