Authentification et autorisation

Chaque demande adressée à un outil Foundry doit inclure un en-tête d’authentification. Cet en-tête passe une clé de ressource ou un jeton d’authentification qui sert à valider votre abonnement à un service ou à un groupe de services. Dans cet article, vous pouvez explorer les méthodes d’authentification d’une demande et des exigences pour chacun d’eux.

Authentifiez-vous avec une clé de ressource à service unique, à service unique ou multiservices .
Authentifiez-vous avec un jeton du porteur.
L’authentification auprès de Microsoft Entra ID est une solution d’identité basée sur le cloud conçue pour gérer l’accès et les autorisations des utilisateurs pour les services, ressources et applications Microsoft. Microsoft Entra ID vous permet d’authentifier les demandes auprès de vos ressources Azure sans avoir besoin de mots de passe ou de clés.

headers

Abonnez-vous à Translator ou multiservices dans Foundry Tools et utilisez votre clé (disponible dans le portail Azure) pour vous authentifier.

Il existe trois en-têtes que vous pouvez utiliser pour authentifier votre abonnement. Ce tableau décrit comment chacun est utilisé :

headers	Descriptif
Ocp-Apim -Subscription-Key	Utilisez l’abonnement Foundry Tools si vous transmettez votre clé secrète. La valeur est la clé secrète Azure pour votre abonnement à Translator.
Autorisation	Utilisez l’abonnement Foundry Tools si vous transmettez un jeton d’authentification. La valeur est le jeton du porteur : `Bearer <token>`.
Ocp-Apim -Subscription-Region	Utiliser avec des ressources de traduction multiservices et régionales. La valeur est la région de la ressource de traduction multiservices ou régionales. Cette valeur est facultative lors de l’utilisation d’une ressource translator globale.

Clé secrète

La première option consiste à s’authentifier à l’aide de l’en-tête Ocp-Apim-Subscription-Key . Ajoutez l’en-tête Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> à votre demande.

Authentification avec une ressource globale

Lorsque vous utilisez une ressource de traduction globale, vous devez inclure un en-tête pour appeler Translator.

headers	Descriptif
Ocp-Apim -Subscription-Key	La valeur est la clé secrète Azure pour votre abonnement à Translator.

Voici un exemple de demande d’appel de Translator à l’aide de la ressource de traduction globale

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

Authentification avec une ressource régionale

Lorsque vous utilisez une ressource de traduction régionale, il existe deux en-têtes que vous devez appeler Translator.

headers	Descriptif
Ocp-Apim -Subscription-Key	La valeur est la clé secrète Azure pour votre abonnement à Translator.
Ocp-Apim -Subscription-Region	La valeur est la région de la ressource translator.

Voici un exemple de requête pour appeler Translator à l’aide de la ressource de traduction régionale

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

Authentification avec une ressource multiservices

Une ressource multiservices vous permet d’utiliser une clé API unique pour authentifier les demandes de plusieurs services.

Lorsque vous utilisez une clé secrète multiservices, vous devez inclure deux en-têtes d’authentification avec votre demande. Il existe deux en-têtes que vous devez appeler Translator.

headers	Descriptif
Ocp-Apim -Subscription-Key	La valeur est la clé secrète Azure pour votre ressource multiservices.
Ocp-Apim -Subscription-Region	La valeur est la région de la ressource multiservices.

La région est requise pour l’abonnement à l’API de texte multiservice. La région que vous sélectionnez est la seule région que vous pouvez utiliser pour la traduction de texte lors de l’utilisation de la clé multiservices. Il doit s’agir de la même région que celle que vous avez sélectionnée lorsque vous vous êtes inscrit à votre abonnement multiservice via le portail Azure.

Si vous passez la clé secrète dans la chaîne de requête avec le paramètre Subscription-Key, vous devez spécifier la région avec le paramètre Subscription-Regionde requête.

S’authentifier avec un jeton d’accès

Vous pouvez également échanger votre clé secrète pour un jeton d’accès. Ce jeton est inclus dans chaque requête comme en-tête Authorization . Pour obtenir un jeton d’autorisation, effectuez une POST demande à l’URL suivante :

Type de ressource	URL du service d’authentification
Mondial	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Régional ou multiservices	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Voici des exemples de demandes d’obtention d’un jeton donné une clé secrète pour une ressource globale :

// 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>'

Voici des exemples de demandes d’obtention d’un jeton en fonction d’une clé secrète pour une ressource régionale située dans la région USA Centre :

// 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>"

Une requête réussie retourne le jeton d’accès encodé sous forme de texte brut dans le corps de la réponse. Le jeton valide est transmis à Translator en tant que jeton du porteur dans l’autorisation.

Authorization: Bearer <Base64-access_token>

Un jeton d’authentification est valide pendant 10 minutes. Le jeton doit être réutilisé lors de plusieurs appels à Translator. Toutefois, si votre programme envoie des demandes à Translator sur une période prolongée, votre programme doit demander un nouveau jeton d’accès à intervalles réguliers (par exemple, toutes les 8 minutes).

Authentification avec Microsoft Entra ID

Translator v3.0 prend en charge l’authentification Microsoft Entra, la solution de gestion des identités et des accès basée sur le cloud de Microsoft. Les en-têtes d’autorisation permettent à Translator de vérifier que le client demandeur est autorisé à utiliser la ressource et à terminer la demande.

Conditions préalables

Une brève compréhension de l’authentification auprès de Microsoft Entra ID.
Une brève compréhension de la façon d’autoriser l’accès aux identités managées.

En-têtes d’ID Microsoft Entra

En-tête de page	Valeur
Autorisation	La valeur est un jeton du porteur d’accès généré par l’ID Microsoft Entra. Le jeton du porteur fournit une preuve d’authentification et valide l’autorisation du client d’utiliser la ressource. Un jeton d’authentification est valide pendant 10 minutes et doit être réutilisé lors de plusieurs appels à Translator. Consultezl’exemple de demande : 2. Obtenir un jeton
Ocp-Apim -Subscription-Region	La valeur est la région de la ressource translator. Cette valeur est facultative si la ressource est globale.
Ocp-Apim-ResourceId	La valeur est l’ID de ressource de votre instance de ressource Translator. Vous trouverez l’ID de ressource dans le portail Azure sur les propriétés de la ressource Translator Resource →. Format de l’ID de ressource : /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Page de propriétés Translator — Portail Azure

Capture d’écran : page des propriétés translator dans le portail Azure.

Important

Attribuez un rôle d’utilisateur Cognitive Services au principal du service. En affectant ce rôle, vous accordez au principal de service l’accès à la ressource Translator.

Exemples

Utilisation du point de terminaison 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.'}]"

Utilisation de votre point de terminaison personnalisé

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

Exemples utilisant des identités managées

Translator v3.0 prend également en charge l’autorisation d’accès aux identités managées. Si une identité managée est activée pour une ressource translator, vous pouvez transmettre le jeton du porteur généré par une identité managée dans l’en-tête de requête.

Avec le point de terminaison 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.'}]"

Avec votre point de terminaison personnalisé

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

Prise en charge des réseaux virtuels

Translator est désormais disponible avec des fonctionnalités de réseau virtuel (VNET) dans toutes les régions du cloud public Azure. Pour activer le réseau virtuel, consultezConfiguration des réseaux virtuels Foundry Tools.

Une fois cette fonctionnalité activée, vous devez utiliser le point de terminaison personnalisé pour appeler Translator. Vous ne pouvez pas utiliser le point de terminaison de traducteur global (« api.cognitive.microsofttranslator.com ») et vous ne pouvez pas vous authentifier avec un jeton d’accès.

Vous trouverez le point de terminaison personnalisé après avoir créé une ressource translator et autorisé l’accès à partir de réseaux sélectionnés et de points de terminaison privés.

Accédez à votre ressource Traducteur dans le portail Azure.
Sélectionnez Mise en réseau dans la section Gestion des ressources.
Sous l’onglet Pare-feux et réseaux virtuels, choisissez Réseaux et points de terminaison privés sélectionnés.
Sélectionnez Enregistrer pour appliquer vos modifications.
Sélectionnez Clés et point de terminaison dans la section Gestion des ressources .
Sélectionnez l’onglet Réseau virtuel .
La liste contient les points de terminaison pour la traduction de texte et la traduction de documents.

headers	Descriptif
Ocp-Apim -Subscription-Key	La valeur est la clé secrète Azure pour votre abonnement à Translator.
Ocp-Apim -Subscription-Region	La valeur est la région de la ressource translator. Cette valeur est facultative si la ressource est `global`

Voici un exemple de demande d’appel de Translator à l’aide du point de terminaison personnalisé

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

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-11-18