Partager via

Utiliser les API REST par programmation

  • Article

La traduction de documentation est une fonctionnalité cloud du service Azure AI Traducteur. Vous pouvez utiliser l’API Traduction de documentation pour traduire de manière asynchrone des documents entiers dans des langues prises en charge et dans différents formats de fichiers tout en conservant la structure et la mise en forme du texte du document source. Dans ce guide pratique, vous apprenez à utiliser les API Traduction de documentation avec le langage de programmation de votre choix et l’API REST HTTP.

Prérequis

Remarque

La traduction de documentation est prise en charge dans le plan de service Standard S1 (paiement à l’utilisation) et les plans de remise en volume C2, C3, C4 et D3. Consultez tarification—des services Azure AI Translator.

Pour commencer, vous avez besoin des éléments suivants :

  • Un compte Azure actif. Si vous n’en avez pas, vous pouvez créer un compte gratuit.

  • Un compte de stockage Blob Azure. Vous devez également créer des conteneurs dans votre compte de stockage Blob Azure pour vos fichiers sources et cibles :

    • Conteneur source. Ce conteneur est l’emplacement où vous chargez vos fichiers pour la traduction (obligatoire).
    • Conteneur cible. Ce conteneur est l’emplacement où vos fichiers traduits sont stockés (obligatoire).

  • Une ressource Traducteur :

    Complétez les champs des détails du projet Translator et de l’instance comme suit :

    1. Abonnement. Sélectionnez l’un de vos abonnements Azure disponibles.

    2. Groupe de ressources. Vous pouvez créer un groupe de ressources ou ajouter votre ressource à un groupe de ressources existant qui partage le même cycle de vie, les mêmes autorisations et les mêmes stratégies.

    3. Région de la ressource. Choisissez Globale, sauf si votre entreprise ou votre application nécessite une région spécifique. Si vous envisagez d’utiliser une identité managée affectée par le système pour l’authentification, choisissez une région géographique telle que USA Ouest.

    4. Nom. Entrez le nom choisi pour votre ressource. Le nom choisi doit être unique dans Azure.

      Notes

      La traduction de documentation requiert un point de terminaison de domaine personnalisé. La valeur que vous entrez dans le champ Nom sera le paramètre de nom de domaine personnalisé pour votre point de terminaison.

    5. Niveau tarifaire. La traduction de documentation n’est pas prise en charge dans le niveau gratuit. Pour essayer le service, sélectionnez Standard S1.

    6. Sélectionnez Vérifier + créer.

    7. Passez en revue les conditions du service, puis sélectionnez Créer pour déployer votre ressource.

    8. Une fois votre ressource correctement déployée, sélectionnez Accéder à la ressource pour récupérer votre clé et votre point de terminaison.

Récupérez votre clé et votre point de terminaison du domaine personnalisé

  • Les demandes adressées au service Translator nécessitent une clé en lecture seule et un point de terminaison personnalisé pour authentifier l’accès. Le point de terminaison de domaine personnalisé est une URL mise en forme avec votre nom de ressource, votre nom d’hôte et les sous-répertoires de Translator et qui est disponible dans le portail Azure.

  1. Si vous avez créé une ressource, après son déploiement, sélectionnez Accéder à la ressource. Si vous disposez déjà d’une ressource de Traduction de documentation, accédez directement à la page de votre ressource.

  2. Dans le rail de gauche, sous Gestion des ressources, sélectionnez Clés et point de terminaison.

  3. Copiez et collez votre key et votre document translation endpoint dans un endroit pratique, comme le Bloc-notes Microsoft. Une seule clé est nécessaire pour effectuer un appel d’API.

  4. Collez la key et le document translation endpoint dans l’exemple de code pour authentifier votre demande auprès du service Traduction de documentation.

    Capture d’écran montrant le champ Récupérer votre clé dans le portail Azure.

Obtenir votre clé

Les requêtes adressées au service Translator nécessitent une clé en lecture seule pour l’authentification de l’accès.

  1. Si vous avez créé une ressource, après son déploiement, sélectionnez Accéder à la ressource. Si vous disposez déjà d’une ressource de Traduction de documentation, accédez directement à la page de votre ressource.
  2. Dans le rail de gauche, sous Gestion des ressources, sélectionnez Clés et point de terminaison.
  3. Copiez et collez votre clé dans un endroit pratique, par exemple le Bloc-notes Microsoft.
  4. Vous le collez dans l’exemple de code pour authentifier votre requête auprès du service Traduction de documentation.

Image du champ Récupérer votre clé dans le Portail Azure.

Créer des conteneurs de stockage d’objets blob Azure

Vous devez créer des conteneurs dans votre compte de stockage Blob Azure pour les fichiers sources et cibles.

  • Conteneur source. Ce conteneur est l’emplacement où vous chargez vos fichiers pour la traduction (obligatoire).
  • Conteneur cible. Ce conteneur est l’emplacement où vos fichiers traduits sont stockés (obligatoire).

Notes

La traduction de documents prend en charge les glossaires en tant qu’objets BLOB dans les conteneurs cibles (pas les conteneurs de Glossaire distincts). Si vous souhaitez inclure un glossaire personnalisé, ajoutez-le au conteneur cible et incluez glossaryUrl avec la requête. Si la paire de langues de traduction n’est pas présente dans le glossaire, elle ne sera pas appliquée. Voir Traduisez des documents à l’aide d’un glossaire personnalisé

Créer des jetons d’accès SAS pour la Traduction de documentation

sourceUrl, targetUrl et glossaryUrl (facultatif) doivent inclure un jeton de signature d’accès partagé (SAP), ajouté comme chaîne de requête. Le jeton peut être attribué à votre conteneur ou à des blobs spécifiques. Consultez Créer des jetons SAS pour le processus de Traduction de documentation.

  • Votre blob ou conteneur source doit désigner un accès lecture et liste.
  • Votre blob ou conteneur cible doit désigner un accès écriture et liste.
  • Votre blob glossaire doit désigner un accès lecture et liste.

Conseil

  • Si vous traduisez plusieurs fichiers (blobs) dans une opération, déléguez l’accès SAP au niveau du conteneur.
  • Si vous traduisez un seul fichier (blob) dans une opération, déléguez l’accès SAS au niveau du blob.
  • Comme alternative aux jetons SAS, vous pouvez utiliser une identité managée affectée par le système pour l’authentification.

Des requêtes HTTP

Une requête de traduction par lots asynchrone est soumise à votre point de terminaison du service Translator via une requête POST. En cas de réussite, la méthode POST retourne un code de réponse 202 Accepted et le service crée une demande de lot. Les documents traduits s’affichent dans votre conteneur cible.

Pour plus d’informations sur les limites d’une requête de service Azure AI Traducteur, consultez Limites d’une requête de traduction de documentation.

En-têtes HTTP

Les en-têtes suivants sont inclus avec chaque requête d’API Traduction de documentation :

En-tête HTTP Description
Ocp-Apim-Subscription-Key Obligatoire : La valeur est la clé Azure de votre ressource Translator ou Azure AI services.
Content-Type Obligatoire : spécifie le type de contenu de la charge utile. Les valeurs acceptées sont application/json ou charset=UTF-8.

Propriétés du corps de la requête POST

  • L’URL de la requête POST est POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Le corps de la requête POST est un objet JSON nommé inputs.
  • L’objet inputs contient à la fois les adresses de conteneur sourceURL et targetURL pour vos paires de langue source et cible.
  • prefix et suffix sont des chaînes respectant la casse afin de filtrer les documents dans le chemin source pour la traduction. Le champ prefix est souvent utilisé pour délimiter les sous-dossiers pour la traduction. Le champ suffix est généralement utilisé pour les extensions de fichier.
  • Une valeur du champ glossaries (facultatif) est appliquée quand le document est en cours de traduction.
  • La valeur targetUrl de chaque langue cible doit être unique.

Notes

Si un fichier portant le même nom existe déjà dans la destination, le travail se solde par un échec.

Traduire tous les documents dans un conteneur

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduire un document spécifique dans un conteneur

  • Spécifier "storageType": "File".
  • Si vous n’utilisez pas d’identité managée affectée par le système pour l’authentification, assurez-vous d’avoir créé l’URL source et les jetons SAS pour le blob/document spécifique (et non pour le conteneur).
  • Vérifiez que vous avez spécifié le nom de fichier cible dans le cadre de l’URL cible, bien que le jeton SAS soit toujours pour le conteneur.
  • Cet exemple de demande retourne un seul document traduit en deux langues cibles.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Traduire des documents à l’aide d’un glossaire personnalisé

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

🆕 Traduire du texte incorporé dans des images au sein des documents

Remarque

  • Cette fonctionnalité est facultative et doit être activée pour chaque requête de traduction.
  • L’activation de cette fonctionnalité entraîne des coûts supplémentaires en fonction de l’utilisation. Pour plus d’informations, consultez les prix appliqués pour Azure AI Vision
  • Cette fonctionnalité est actuellement disponible uniquement avec l’API de traduction de lot de documents.
  • Le seul format de fichier pris en charge est .docx.
  • Une ressource Azure AI Services (et non la ressource Traducteur autonome) est nécessaire pour utiliser cette fonctionnalité.

Configuration de requête

  • Utiliser le paramètre facultatif translateTextWithinImage dans le champ options

    • Type de données : booléen(true ou false)
    • Le paramètre booléen par défaut est false. Choisissez l’option true pour activer la traduction de texte d’image.

  • Détails de la réponse. Lorsque la fonctionnalité est activée, les informations de traitement d’images ajoutées sont incluses dans la réponse :

    • totalImageScansSucceeded. Nombre d’analyses d’images traduites avec succès.

    • totalImageScansFailed. Nombre d’analyses d’images ayant échouées.

Utiliser du code pour soumettre des demandes de traduction de documents

Configurer votre plateforme de programmation

  • Créez un projet.
  • Remplacez Program.cs par l’exemple de code C#.
  • Définissez vos valeurs de point de terminaison, de clé et d’URL de conteneur dans Program.cs.
  • Ajoutez le package Newtonsoft.Json en utilisant l’interface CLI .NET pour traiter les données JSON.
  • Exécutez le programme à partir du répertoire du projet.

Important

Pour les exemples de code, vous allez coder en dur votre URL de signature d’accès partagé (SAS) à l’endroit indiqué. N’oubliez pas de supprimer l’URL SAS de votre code une fois que vous avez terminé et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Identité managée Azure. Pour plus d’informations, consultezSécurité du Stockage Azure.

Vous devrez peut-être mettre à jour les champs suivants, en fonction de l’opération :

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (ID de tâche)

Recherche de la valeur id

  • L’id de travail se trouve dans la valeur d’URL Operation-Location de l’en-tête de réponse de la méthode start-batch-translation POST. La chaîne alphanumérique qui suit le paramètre /document/ est l’id de travail de l’opération :
En-tête de réponse URL de réponse
Operation-Location {point_de_terminaison-traduction-documentations}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}
  • Vous pouvez également utiliser une requête get-translations-status pour récupérer une liste de travaux de traduction et leurs id.

Démarrer la traduction par lots asynchrone


    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    using System.Text;


    class Program
    {

        static readonly string route = "?api-version={date}";

        private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";

        private static readonly string key = "{your-api-key}";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");

        static async Task Main(string[] args)
        {
            using HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {

                StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(basePath + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);
                request.Content = content;

                HttpResponseMessage  response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;
                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Status code: {response.StatusCode}");
                    Console.WriteLine();
                    Console.WriteLine($"Response Headers:");
                    Console.WriteLine(response.Headers);
                }
                else
                    Console.Write("Error");

            }

        }

    }

Obtenir les formats de document pris en charge

Récupérez la liste des formats de fichiers pris en charge. En cas de réussite, cette méthode retourne un code de réponse 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";

    static readonly string route = "?api-version={date}&type=document";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Obtenir l’état d’un travail de traduction

Obtenez l’état actuel d’une seule tâche et un récapitulatif de toutes les tâches d’une demande de Traduction de documentation. En cas de réussite, cette méthode retourne un code de réponse 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
    }
}

Obtenir l’état d’une documentation spécifique

Petite vue d’ensemble

Récupérez l’état d’un documentation spécifique dans une demande de traduction de documentation. En cas de réussite, cette méthode retourne un code de réponse 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Supprimer le travail

Petite vue d’ensemble

Annulez la tâche en cours de traitement ou en file d’attente. Seuls les documents pour lesquels la traduction n’a pas commencé sont annulés.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(basePath + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Codes d'état HTTP courants

Code d'état HTTP Description Raison possible
200 OK La demande a abouti.
400 Demande incorrecte Un paramètre obligatoire est manquant, vide ou présente une valeur Null. Il est également possible que la valeur transmise à un paramètre obligatoire ou facultatif ne soit pas valide. Ce problème est généralement dû à un en-tête trop long.
401 Non autorisé La requête n’est pas autorisée. Vérifiez que votre clé ou votre jeton est valide et dans la région appropriée.
429 Trop de demandes Vous avez dépassé le quota ou le taux de requêtes autorisé pour votre abonnement.
502 Passerelle incorrecte Problème de réseau ou côté serveur. Peut également indiquer des en-têtes non valides.

En savoir plus

Étapes suivantes

Créer un système de langue personnalisé avec Custom Translator