Utiliser les API REST par programmation
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
En général, quand vous créez une ressource Azure AI dans le Portail Azure, vous pouvez créer une clé multiservice ou monoservice. Toutefois, la traduction de documentation est actuellement prise en charge dans la ressource Traducteur (monoservice) uniquement, et n’est pas incluse dans la ressource Azure AI services (multiservice).
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 Translator de service unique (et pas une ressource multiservice Azure AI services) :
Complétez les champs des détails du projet Translator et de l’instance comme suit :
Abonnement. Sélectionnez l’un de vos abonnements Azure disponibles.
Groupe de ressources. Vous pouvez créer un groupe de ressources ou ajouter votre ressource à un groupe de ressources préexistant qui partage le même cycle de vie, les mêmes autorisations et les mêmes stratégies.
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.
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.
Niveau tarifaire. La traduction de documentation n’est pas prise en charge dans le niveau gratuit. Pour essayer le service, sélectionnez Standard S1.
Sélectionnez Vérifier + créer.
Passez en revue les conditions du service, puis sélectionnez Créer pour déployer votre ressource.
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.
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.
Dans le rail de gauche, sous Gestion des ressources, sélectionnez Clés et point de terminaison.
Copiez et collez votre
key
et votredocument translation endpoint
dans un endroit pratique, comme le Bloc-notes Microsoft. Une seule clé est nécessaire pour effectuer un appel d’API.Collez la
key
et ledocument translation endpoint
dans l’exemple de code pour authentifier votre demande auprès du service Traduction de documentation.
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.
- 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.
- Dans le rail de gauche, sous Gestion des ressources, sélectionnez Clés et point de terminaison.
- Copiez et collez votre clé dans un endroit pratique, par exemple le Bloc-notes Microsoft.
- Vous le collez dans l’exemple de code pour authentifier votre requête auprès du service Traduction de documentation.
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 conteneursourceURL
ettargetURL
pour vos paires de langue source et cible. prefix
etsuffix
sont des chaînes respectant la casse afin de filtrer les documents dans le chemin source pour la traduction. Le champprefix
est souvent utilisé pour délimiter les sous-dossiers pour la traduction. Le champsuffix
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"
}
]
}
]
}
]
}
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’URLOperation-Location
de l’en-tête de réponse de la méthodestart-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. Lors de la gestion de votre abonnement sur le Portail Azure, assurez-vous d’utiliser la ressource à service unique Traducteur, et non la ressource multiservice Azure AI services. |
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. |