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

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:

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.

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.

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.

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:

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

Página de propiedades de Translator: Azure Portal

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.

   

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:

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.