Démarrer la traduction par lots

Fonctionnalité de référence
: Méthode HTTP Azure AI Translator → Version de l’API traduction de documents
: méthode HTTP 2024-05-01
: POST

Utilisez la Start Translation méthode pour exécuter une demande de traduction par lots asynchrone.
La méthode nécessite un compte de stockage Blob Azure avec des conteneurs de stockage pour vos documents sources et traduits.

URL de la requête

Important

Toutes les demandes d’API adressées à la fonctionnalité de traduction de documents nécessitent un point de terminaison de domaine personnalisé situé sur la page vue d’ensemble de votre ressource dans le portail Azure.

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

En-têtes de requête

Les en-têtes de requête sont les suivants :

headers	Descriptif	Condition
Ocp-Apim-Subscription-Key	Votre clé API de service Translator à partir de l’Portail Azure.	Obligatoire
Ocp-Apim-Subscription-Region	Région dans laquelle votre ressource a été créée.	Obligatoire lors de l’utilisation d’une ressource régionale (géographique) comme USA Ouest. &puce.
Type de contenu	Type de contenu de la charge utile. Les valeurs acceptées sont application/json ou charset=UTF-8.	Obligatoire

BatchRequest (corps)

Chaque requête peut contenir plusieurs documents et doit contenir un conteneur source et un conteneur cible pour chaque document. Types de médias sources : application/json, text/json, application/*+json.
Les filtres de préfixe et de suffixe (s’ils sont fournis) sont utilisés pour filtrer les dossiers. Le préfixe est appliqué au sous-chemin après le nom du conteneur.
Les glossaires peuvent être inclus dans la demande. Si le glossaire n’est pas valide ou est inaccessible lors de la traduction, une erreur est signalée dans l’état du document.
Si un fichier portant le même nom existe déjà dans la destination cible, le travail échoue.
La valeur targetUrl de chaque langue cible doit être unique.


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Entrées

Définition de la demande de traduction par lot d’entrée.

Paramètre clé	Catégorie	Requis	Paramètres de la demande	Descriptif
Entrées	`array`	Vrai	• source (objet) • targets (groupe) • storageType (chaîne)	Données sources d’entrée.

inputs.source

Définition des données sources.

Paramètre clé	Catégorie	Requis	Paramètres de la demande	Descriptif
inputs.source	`object`	Vrai	• sourceUrl (chaîne) • filter (objet) • language (chaîne) • storageSource (chaîne)	Données sources pour les documents d’entrée.
inputs.source.sourceUrl	`string`	Vrai	•corde	Emplacement du conteneur pour le fichier ou dossier source.
inputs.source.filter	`object`	Faux	• prefix (chaîne) • suffix (chaîne)	Chaînes respectant la casse pour filtrer des documents dans le chemin d’accès source.
inputs.source.filter.prefix	`string`	Faux	•corde	Chaîne de préfixe respectant la casse pour filtrer les documents dans le chemin d’accès source pour la traduction. Souvent utilisé pour désigner des sous-dossiers pour la traduction. Exemple : « FolderA ».
inputs.source.filter.suffix	`string`	Faux	•corde	Chaîne de suffixe respectant la casse pour filtrer les documents dans le chemin source pour la traduction. Le plus souvent utilisée pour les extensions de fichier. Exemple : « .txt »
inputs.source.language	`string`	Faux	•corde	Le code de langue pour les documents sources. S’il n’est pas spécifié, la détection automatique est implémentée.
inputs.source.storageSource	`string`	Faux	•corde	Source de stockage pour les entrées. La valeur par défaut est `AzureBlob`.

inputs.targets

Définition des données des cibles et des glossaires.

Paramètre clé	Catégorie	Requis	Paramètres de la demande	Descriptif
inputs.targets	`array`	Vrai	• targetUrl (chaîne) • category (chaîne) • language (chaîne) • glossaries (groupe) • storageSource (chaîne)	Données de cibles et de glossaires pour les documents traduits.
inputs.targets.targetUrl	`string`	Vrai	•corde	Localisation de l’emplacement du conteneur pour les documents traduits.
inputs.targets.category	`string`	Faux	•corde	Classification ou catégorie pour la requête de traduction. Exemple : général.
inputs.targets.language	`string`	Vrai	•corde	Code de langue cible. Example : « fr ».
inputs.targets.glossaries	`array`	Faux	• glossaryUrl (chaîne) • format (chaîne) • version (chaîne) • storageSource (chaîne)	VoirCréer et utiliser des glossaires
inputs.targets.glossaries.glossaireUrl	`string`	True (si vous utilisez des glossaires)	•corde	Emplacement du glossaire. L’extension de fichier est utilisée pour extraire la mise en forme si le paramètre de format n’est pas fourni. Si la paire de langues de traduction n’est pas présente dans le glossaire, elle n’est pas appliquée.
inputs.targets.glossaries.format	`string`	Faux	•corde	Format de fichier spécifié pour le glossaire. Pour vérifier si votre format de fichier est pris en charge, consultezObtenir les formats de glossaire pris en charge.
inputs.targets.glossaries.version	`string`	Faux	•corde	Indicateur de version. Exemple : « 2.0 ».
inputs.targets.glossaries.storageSource	`string`	Faux	•corde	Source de stockage pour les glossaires. La valeur par défaut est `_AzureBlob_`.
inputs.targets.storageSource	`string`	Faux	•corde	Source de stockage pour targets.defaults sur `_AzureBlob_`.

inputs.storageType

Définition de l’entité de stockage pour les documents d’entrée.

Paramètre clé	Catégorie	Requis	Paramètres de la demande	Descriptif
inputs.storageType	`string`	Faux	•`Folder` • `File`	Type de stockage de la chaîne source des documents d’entrée. Seules « Dossier » ou « Fichier » sont des valeurs valides.

Paramètres

Définition de la demande de traduction par lot d’entrée.

Paramètre clé	Catégorie	Requis	Paramètres de la demande	Descriptif
Options	`object`	Faux	Informations sources pour les documents d’entrée.
options.experimental	`boolean`	Faux	•`true` • `false`	Indique si la demande inclut une fonctionnalité expérimentale (le cas échéant). Seules les valeurs booléennes `true` ou `false` sont des valeurs valides.

Exemple de requête

Voici des exemples de demandes de lots :

Notes

Dans les exemples suivants, l’accès limité est accordé au contenu d’un conteneur de stockage Azure à l’aide d’un jeton de signature d’accès partagé (SAP).

Traduction de tous les documents dans un conteneur

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduction de tous les documents d’un conteneur avec application de glossaires

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Traduction d’un dossier spécifique dans un conteneur

Veillez à spécifier le nom du dossier (respectant la casse) comme préfixe dans le filtre.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduction d’un document spécifique dans un conteneur

Spécifiez « storageType » : File.
Créez l’URL source et le jeton SAS pour l’objet blob/document spécifique.
Spécifiez 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 requête montre un document unique traduit en deux langues cibles.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

Conseil

Cette méthode retourne le paramètre de travail id pour les chaînes de requête de requête get-translation-status, get-documents-status, get-document-status et cancel-translation request.

L’id de travail se trouve dans la valeur d’URL start-batch-translation de l’en-tête de réponse de la méthode Operation-Location 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
Opération-Emplacement	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec` ?api-version=2024-05-01

Vous pouvez également utiliser une demande get-translation-status pour récupérer une liste de travaux de traduction et leurs ids.

Codes d’état de réponse

Voici les codes d’état HTTP qu’une demande peut retourner.

Code d’état	Descriptif
202	Accepté. La demande ayant réussi et la demande de lot ont été créées. L’en-tête Operation-Location indique une URL d’état avec la chaîne ID.HeadersOperation-Location: de l’opération
400	Demande incorrecte. Demande non valide. Vérifiez les paramètres d’entrée.
401	Non autorisé. Vérifiez vos informations d’identification.
429	Le taux de demandes est trop élevé.
500	Erreur interne du serveur.
503	Le service est actuellement indisponible. Réessayez plus tard.
Autres codes d’état	• Trop de demandes. Le serveur n’est pas disponible temporairement

Réponse d’erreur

Paramètre clé	Catégorie	Descriptif
code	`string`	Enums contenant des codes d’erreur généraux. Valeurs acceptées :</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Non autorisé
Message	`string`	Obtient un message d’erreur général.
erreur interne	InnerTranslationError	Nouveau format d’erreur interne conforme aux instructions de l’API Azure AI services. Ce message d’erreur contient les propriétés requises : ErrorCode, message et cible de propriétés facultatives, détails(paire valeur clé) et erreur interne (il peut être imbriqué).
intérieur. Code d’erreur	`string`	Obtient la chaîne d’erreur de code.
innerError.message	`string`	Obtient un message d’erreur général.
innerError.target	`string`	Obtient la source de l’erreur. Par exemple, ce serait `documents` ou `document id` si le document était invalide.

Exemple de réponse d’erreur

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Étapes suivantes

Suivez notre guide de démarrage rapide pour en savoir plus sur l’utilisation de la traduction de documents et de la bibliothèque cliente.

Prise en main de la traduction de documents

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-05-20