Translator v3.0

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.

✔️ Fonctionnalité : Traduction de texte Translator Text

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 region Switzerland 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 à 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é :

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.

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.

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.

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 :

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

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

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 Réseau virtuel, consultez Configuration des réseaux virtuels des services Azure AI.

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.

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.

   

4. Sélectionnez Enregistrer pour enregistrer 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. Les points de terminaison de la traduction de texte et de la traduction de documentation sont répertoriés ici.

   

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 :

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.

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.