Translator v3.0

Article
02/14/2024

Nouveautés

Translator v3.0 fournit une API web moderne basée sur JSON. Elle simplifie l’utilisation et améliorer les performances en regroupant les fonctionnalités existantes en moins d’opérations, et elle fournit de nouvelles fonctionnalités.

Translittération pour convertir du texte dans une langue d’un script vers un autre script.
Traduction en plusieurs langues en une seule demande.
Détection de la langue, traduction et translittération en une seule demande.
Dictionnaire permettant de rechercher d’autres traductions d’un terme et de rechercher des traductions inverses et des exemples montrant les termes utilisés en contexte.
Résultats de détection de langue plus informatifs.

URL de base

Les requêtes adressées à Translator sont dans la plupart des cas gérées par le centre de données le plus proche de l’emplacement d’origine de la requête. En cas de défaillance du centre de production lors de l’utilisation du point de terminaison global, la requête peut être acheminée en dehors de la zone géographique.

Pour forcer le traitement de la requête dans une zone géographique spécifique, utilisez le point de terminaison géographique souhaité. Toutes les requêtes sont traitées dans les centres de données de la zone géographique.

Geography	URL de base (point de terminaison géographique)	Centres de données
Global (`non-regional`)	api.cognitive.microsofttranslator.com	Centre de données disponible le plus proche
Asie-Pacifique	api-apc.cognitive.microsofttranslator.com	Corée Sud, Japon Est, Asie Sud-Est et Australie Est
Europe	api-eur.cognitive.microsofttranslator.com	Europe Nord, Europe Ouest
États-Unis	api-nam.cognitive.microsofttranslator.com	USA Est, USA Centre Sud, USA Centre-Ouest, USA Ouest 2

¹ Les clients disposant d’une ressource située dans la région Suisse Nord ou Suisse Ouest peuvent s’assurer que leurs requêtes d’API de texte sont traitées en Suisse. Pour vous assurer que les demandes sont gérées en Suisse, créez la ressource Traducteur dans le Resource regionSwitzerland North ou Switzerland West, puis utilisez le point de terminaison personnalisé de la ressource dans vos demandes d’API.

Par exemple : si vous créez une ressource de Traducteur dans Portail Azure avec Resource region le nom de votre ressource et que Switzerland North le nom de votre ressource est my-swiss-n, votre point de terminaison personnalisé est https://my-swiss-n.cognitiveservices.azure.com. Et voici un exemple de demande de traduction :

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

² Custom Translator n’est actuellement pas disponible en Suisse.

Authentification

Abonnez-vous à Translator ou à un abonnement multiservice dans Azure AI Services, et utilisez votre clé (disponible dans le portail Azure) pour vous authentifier.

Trois en-têtes sont à votre disposition pour authentifier votre abonnement. Ce tableau décrit la façon dont chaque en-tête est utilisé :

headers	Description
Ocp-Apim-Subscription-Key	À utiliser avec un abonnement à Azure AI Services si vous transmettez votre clé secrète. La valeur est la clé secrète Azure pour votre abonnement à Translator.
Autorisation	À utiliser avec un abonnement à Cognitive Services si vous transmettez un jeton d'authentification. La valeur est le jeton du porteur : `Bearer <token>`.
Ocp-Apim-Subscription-Region	Utilisation avec la ressource multiservice et la ressource du traducteur régional. La valeur est la région de la ressource multiservice ou de la ressource du traducteur régional. Cette valeur est facultative si vous utilisez une ressource de traducteur globale.

Clé secrète

La première option consiste à procéder à l’authentification à l’aide de l’en-tête Ocp-Apim-Subscription-Key. Ajoutez l’en-tête Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> à votre requête.

Authentification avec une ressource globale

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

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

Voici un exemple de demande d’appel du Translator à l’aide de la ressource de traducteur 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	Description
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 du traducteur.

Voici un exemple de demande d’appel du Translator à l’aide de la ressource de traducteur régional

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

La ressource multiservice vous permet d’utiliser une clé d’API unique pour authentifier les requêtes de plusieurs services.

Quand vous utilisez une clé secrète multiservice, vous devez inclure deux en-têtes d’authentification avec votre requête. Il existe 2 en-têtes dont vous avez besoin pour appeler le Translator.

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

La région est obligatoire pour l’abonnement à l’API Texte multiservice. La région que vous sélectionnez est la seule région que vous pouvez utiliser pour la traduction de texte quand vous utilisez la clé multiservice. Il doit s’agir de la même région que celle que vous avez sélectionnée lors de l’inscription à 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 de requête Subscription-Region.

S’authentifier avec un jeton d’accès

Vous pouvez également échanger votre clé secrète contre un jeton d’accès. Ce jeton est inclus avec chaque requête sous la forme de l’en-tête Authorization. Pour obtenir un jeton d’autorisation, exécutez une demande POST pour l’URL suivante :

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

Voici des exemples de requêtes permettant d’obtenir un jeton en fonction d’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 requêtes permettant d’obtenir un jeton en fonction d’une clé secrète pour une ressource 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 demande réussie retourne le jeton d’accès codé sous forme de texte brut dans le corps de la réponse. Le jeton valide est transmis au service de traduction sous forme de jeton du porteur dans l’autorisation.

Authorization: Bearer <Base64-access_token>

Un jeton d’authentification est valide pour une durée de 10 minutes. Le jeton doit être réutilisé lorsque vous effectuez plusieurs appels au Translator. Toutefois, si votre programme effectue des requêtes au 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

Traducteur 3.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 au service Traducteur de valider le fait que le client demandeur est autorisé à utiliser la ressource et à terminer la requête.

Conditions préalables

Une brève compréhension de l’authentification auprès de Microsoft Entra ID.
Notions sur l’autorisation d’accès aux identités managées.

En-têtes

En-tête	Valeur
Autorisation	La valeur est un jeton du porteur d’accès généré par Azure AD. Le jeton du porteur fournit une preuve d’authentification et valide l’autorisation du client pour utiliser la ressource. Un jeton d’authentification est valide pendant 10 minutes et doit être réutilisé lors de l’exécution de plusieurs appels de Traducteur. ConsultezExemple de requête : 2. Obtenir un jeton
Ocp-Apim-Subscription-Region	La valeur est la région de la ressource du traducteur. Cette valeur est facultative si la ressource est globale.
Ocp-Apim-ResourceId	La valeur est l’ID de ressource de votre instance de ressource Traducteur. Vous trouvez l’ID de ressource dans Ressource Traducteur → Propriétés dans le portail Azure. Format d’ID de ressource : /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Page de propriétés de Traducteur — Portail Azure

Screenshot:Translator properties page in the Azure portal.

Exemples

À l’aide 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.'}]"

À l’aide 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.'}]"

Exemple utilisant des identités managées

Traducteur 3.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 du traducteur, vous pouvez transmettre le jeton du porteur généré par l’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

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

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

Vous pouvez trouver le point de terminaison personnalisé après avoir créé une ressource de traduction et autorisé l’accès à partir des réseaux et points terminaux privés sélectionné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 enregistrer vos modifications.
Sélectionnez Clés et point de terminaison dans la section Gestion des ressources.
Sélectionnez l’onglet Réseau virtuel.
Les points de terminaison de la traduction de texte et de la traduction de documentation sont répertoriés ici.

En-têtes	Description
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 du traducteur. Cette valeur est facultative si la ressource est `global`

Voici un exemple de requête 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?'}]"

Erreurs

Une réponse d’erreur standard est un objet JSON avec une paire nom/valeur nommée error. La valeur est également un objet JSON avec les propriétés :

code: code d’erreur défini par le serveur.
message: chaîne fournissant une représentation lisible de l’erreur.

Par exemple, un client avec un abonnement d’essai gratuit recevrait l’erreur suivante une fois le quota gratuit épuisé :

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

Le code d’erreur est un nombre à 6 chiffres qui combine le code d’état HTTP à 3 chiffres et un nombre à 3 chiffres qui sert à catégoriser plus précisément l’erreur. Voici les codes d’erreur courants :

Code	Description
400000	Une des requêtes d’entrées n’est pas valide.
400001	Le paramètre « scope » n’est pas valide.
400002	Le paramètre « category » n’est pas valide.
400003	Un spécificateur de langage est manquant ou non valide.
400004	Un spécificateur de script cible (« To script ») est manquant ou non valide.
400005	Un texte d’entrée est manquant ou non valide.
400006	La combinaison de langue et de script n’est pas valide.
400018	Un spécificateur de script source (« From script ») est manquant ou non valide.
400019	L’une des langues spécifiées n’est pas prise en charge.
400020	L’un des éléments du tableau de texte d’entrée n’est pas valide.
400021	Le paramètre de version d’API est manquant ou non valide.
400023	L’une des paires de langues spécifiées n’est pas valide.
400035	La langue source (champ « From ») n’est pas valide.
400036	La langue cible (champ « To ») est manquante ou non valide.
400042	L’une des options spécifiées (champ « Options ») n’est pas valide.
400043	L’ID de trace client (champ de ClientTraceId ou en-tête de X-ClientTranceId) est manquant ou non valide.
400050	Le texte d’entrée est trop long. Affichez les limites de requête.
400064	Le paramètre « translation » est manquant ou non valide.
400070	Le nombre de scripts de cible (paramètre ToScript) ne correspond pas au nombre de langages cible (paramètre To).
400071	La valeur n’est pas valide pour TextType.
400072	Le tableau de texte d’entrée compte trop d’éléments.
400073	Le paramètre de script n’est pas valide.
400074	Le corps de la requête n’est pas un élément JSON valide.
400075	La combinaison de paire de langue et de catégorie n’est pas valide.
400077	La taille de requête maximale a été dépassée. Affichez les limites de requête.
400079	Le système personnalisé demandé pour la traduction entre le langage source et le langage cible n’existe pas.
400080	La translittération n’est pas prise en charge pour la langue ou le script.
401000	La requête n’est pas autorisée, car les informations d’identification sont manquantes ou non valides.
401015	« Les informations d’identification fournies sont valables pour l’API Speech. Cette requête nécessite des informations d’identification pour l’API Texte. Utilisez un abonnement à Translator. »
403000	L’opération n’est pas autorisée.
403001	L’opération n’est pas autorisée, car l’abonnement a dépassé son quota gratuit.
405000	La méthode de requête n’est pas prise en charge pour la ressource demandée.
408001	Le système de traduction demandé est en cours de préparation. Réessayez dans quelques minutes.
408002	Le délai d’attente de la requête a expiré sur le flux entrant. Le client n’a pas produit de requête dans la limite du délai pendant lequel le serveur était préparé à attendre. Le client peut répéter la requête sans modification à tout moment.
415000	L’en-tête Content-Type est manquante ou invalide.
429000, 429001, 429002	Le serveur a rejeté la requête, car le client a dépassé les limites de requête.
500000	Une erreur inattendue s’est produite. Si l’erreur persiste, signalez-la en fournissant les informations suivantes : date et heure de l’erreur, identificateur de la demande dans l’en-tête de réponse X-RequestId, et identificateur du client dans l’en-tête de demande X-ClientTraceId.
503000	Le service est temporairement indisponible. Reprise Si l’erreur persiste, signalez-la en fournissant les informations suivantes : date et heure de l’erreur, identificateur de la demande dans l’en-tête de réponse X-RequestId, et identificateur du client dans l’en-tête de demande X-ClientTraceId.

Mesures

Les métriques vous permettent de voir des informations sur l’utilisation et la disponibilité du traducteur dans le portail Azure, sous la section des métriques, comme illustré dans la capture d’écran ci-dessous. Pour plus d’informations, consultez Métriques de données et de plateforme.

Translator Metrics

Ce tableau liste les métriques disponibles et décrit la façon dont elles sont utilisées pour superviser les appels d’API de traduction.

Mesures	Description
TotalCalls	Nombre total d’appels d’API.
TotalTokenCalls	Nombre total d’appels d’API par le biais du service de jeton qui utilisent un jeton d’authentification.
SuccessfulCalls	Nombre d’appels réussis.
TotalErrors	Nombre d’appels avec réponse d’erreur.
BlockedCalls	Nombre d’appels ayant dépassé la limite de débit ou de quota.
ServerErrors	Nombre d’appels avec erreur interne du serveur (5XX).
ClientErrors	Nombre d’appels avec erreur côté client (4XX).
Latence	Durée d’exécution de la demande en millisecondes.
CharactersTranslated	Nombre total de caractères dans la requête de texte entrante.