Partager via

Translator v3.0

Quoi de neuf?

La version 3.0 de Translator fournit une API web moderne basée sur JSON. Il améliore la facilité d’utilisation et les performances en consolidant les fonctionnalités existantes en moins d’opérations et fournit de nouvelles fonctionnalités.

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

URL de base

Les demandes adressées à Translator sont, dans la plupart des cas, gérées par le centre de données le plus proche de l’endroit où provient la demande. En cas d’échec d’un centre de données lors de l’utilisation du point de terminaison global, la requête peut être routé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 demandes sont traitées parmi les centres de données de la zone géographique.

✔️ Fonctionnalité : Traduction de texte Translator Text

Point de terminaison de service Centre de données de traitement des requêtes
Global (recommandé) :
api.cognitive.microsofttranslator.com		 Centre de données disponible le plus proche.
Amériques :
api-nam.cognitive.microsofttranslator.com		 USA Est 2, USA Ouest 2
Asie-Pacifique :
api-apc.cognitive.microsofttranslator.com		 Japon Est • Asie Sud-Est
Europe (à l’exception de la Suisse) :
api-eur.cognitive.microsofttranslator.com		 France Centre • Europe Ouest
Suisse :
Pour découvrir plus d’informations, consultezPoints de terminaison de service Suisse.		 Suisse Nord, Suisse Ouest

Points de terminaison de service Suisse

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 veiller à ce que les requêtes soient gérées en Suisse, créez la ressource Traducteur dans la Resource regionSwitzerland North ou Switzerland West, puis utilisez le point de terminaison personnalisé de la ressource dans vos requêtes d’API.

Par exemple : si vous créez une ressource Translator dans le Portail Azure avec Resource region comme Switzerland North et que 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

Traducteur personnalisé n’est actuellement pas disponible en Suisse.

Authentification

Abonnez-vous à Translator ou multiservices dans les services Azure AI 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 aux services Azure AI si vous passez votre clé secrète.
La valeur est la clé secrète Azure pour votre abonnement à Translator.
Autorisation Utilisez l’abonnement aux services Azure AI 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 au service 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 au service Translator de vérifier que le client demandeur est autorisé à utiliser la ressource et à terminer la demande.

Conditions préalables

En-têtes

En-tête de page 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 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

Le service 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 des services Azure AI.

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.

  1. Accédez à votre ressource Traducteur dans le portail Azure.

  2. Sélectionnez Mise en réseau dans la section Gestion des ressources.

  3. Sous l’onglet Pare-feux et réseaux virtuels, choisissez Réseaux et points de terminaison privés sélectionnés.

    Capture d’écran du paramètre de réseau virtuel dans le portail Azure.

  4. Sélectionnez Enregistrer pour appliquer vos modifications.

  5. Sélectionnez Clés et point de terminaison dans la section Gestion des ressources .

  6. Sélectionnez l’onglet Réseau virtuel .

  7. La liste contient les points de terminaison pour la traduction de texte et la traduction de documents.

    Capture d’écran du point de terminaison de réseau virtuel.

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

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 des propriétés :

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

Par exemple, un client disposant d’un abonnement d’essai gratuit reçoit l’erreur suivante une fois que le quota gratuit est é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 Descriptif
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 ClientTraceId ou en-tête X-ClientTraceId) 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 maximale de la demande est 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 demande n’est pas autorisée, car les informations d’identification sont manquantes ou non valides.
401015 « Les informations d’identification fournies concernent l’API Speech. Cette demande 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 manquant ou non valide.
429000, 429001, 429002 Le serveur a rejeté la demande, car le client a dépassé les limites de requête.
500 000 Une erreur inattendue s’est produite. Si l’erreur persiste, signalez-la avec la date/l’heure d’erreur, l’identificateur de demande de l’en-tête de réponse X-RequestId et l’identificateur client de l’en-tête de requête X-ClientTraceId.
503000 Le service est temporairement indisponible. Réessayez. Si l’erreur persiste, signalez-la avec la date/l’heure d’erreur, l’identificateur de demande de l’en-tête de réponse X-RequestId et l’identificateur client de l’en-tête de requête X-ClientTraceId.

Métriques

Les métriques vous permettent d’afficher les informations d’utilisation et de disponibilité du traducteur dans le portail Azure. Pour plus d’informations, consultez Les métriques de données et de plateforme.

Métriques Translator

Ce tableau répertorie les métriques disponibles avec une description de la façon dont elles sont utilisées pour surveiller les appels d’API de traduction.

Métriques Descriptif
TotalCalls Nombre total d’appels d’API.
TotalTokenCalls Nombre total d’appels d’API via le service de jeton à l’aide du 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 requête en millisecondes.
CharactersTranslated Nombre total de caractères dans la requête de texte entrante.