Autenticación y autorización

Cada solicitud a una herramienta Foundry debe incluir un encabezado de autenticación. Este encabezado pasa una clave de suscripción o token de autenticación, que se utiliza para validar su suscripción a un servicio o grupo de servicios. En este artículo, puede explorar formas de autenticar una solicitud y los requisitos de cada uno.

• Autentíquese con una clave de recurso regional de servicio único, global o de varios servicios .
• Autentíquese con un token de portador.
• La autenticación con microsoft Entra ID es una solución de identidad basada en la nube diseñada para administrar el acceso y los permisos de usuario para los servicios, recursos y aplicaciones de Microsoft. Microsoft Entra ID permite autenticar solicitudes en los recursos de Azure sin necesidad de contraseñas ni claves.

encabezados

Suscríbase a Translator o a varios servicios en Foundry Tools y use la clave (disponible en Azure Portal) para autenticarse.

Hay tres encabezados que puede usar para autenticar la suscripción. En esta tabla se describe cómo se usa cada una:

Clave secreta

La primera opción es autenticarse mediante el Ocp-Apim-Subscription-Key encabezado . Agregue el Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> encabezado a la solicitud.

Autenticación con un recurso global

Al usar un recurso de traductor global, debe incluir un encabezado para llamar a Translator.

Esta es 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.

Esta es 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 permite usar una sola clave de API para autenticar solicitudes para varios servicios.

Al usar una clave secreta de varios servicios, debe incluir dos encabezados de autenticación con la solicitud. Hay dos encabezados que debe llamar a Translator.

La región es necesaria para la suscripción de Text API de varios servicios. La región que seleccione 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 suscribirse a la suscripción de varios servicios a través de Azure Portal.

Si pasa la clave secreta en la cadena de consulta con el parámetro Subscription-Key, debe especificar la región con el parámetro Subscription-Regionde consulta .

Autenticación con token de acceso

Como alternativa, puede intercambiar la clave secreta para un token de acceso. Este token se incluye con cada solicitud como Authorization encabezado. Para obtener un token de autorización, realice una POST solicitud a la siguiente dirección URL:

Estas son las solicitudes de ejemplo para obtener un token dado 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>'

Y estas son solicitudes de ejemplo para obtener un token dado 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 la respuesta. El token válido se pasa al Traductor como token de portador en la autorización.

Authorization: Bearer <Base64-access_token>

Un token de autenticación es válido durante 10 minutos. El token se debe reutilizar al realizar varias llamadas a Translator. Sin embargo, si el programa realiza 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 admite 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 a Translator validar que el cliente solicitante está autorizado para usar el recurso y para completar la solicitud.

Requisitos previos

• Una breve comprensión de cómo autenticarse con microsoft Entra ID.

• Una breve comprensión de cómo autorizar el acceso a identidades administradas.

Encabezados de Id. de Microsoft Entra

Página de propiedades de Translator: Azure Portal

Ejemplos

Uso del 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.'}]"

Uso del 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 de uso de identidades administradas

Translator v3.0 también admite 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

Translator ya está disponible con funcionalidades de Virtual Network (VNET) en todas las regiones de la nube pública de Azure. Para habilitar Virtual Network, consulteConfiguración de redes virtuales de Foundry Tools.

Una vez activada esta funcionalidad, debe usar el punto de conexión personalizado para llamar a Translator. No 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 traductor 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. Seleccione Claves y punto de conexión en la sección Administración de recursos .

6. Seleccione la pestaña Red virtual .

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

   

Esta es 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?'}]"