Démarrer la traduction par lots

Article
06/22/2024

Fonctionnalité de référence
: Azure AI Traducteur → Traduction de documentation
Version de l’API : 2024-05-01
méthode HTTP : PUBLIER

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é 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	Description	Condition
Ocp-Apim-Subscription-Key	Votre clé API de service Translator à partir de l’Portail Azure.	Requis
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.
Content-Type	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.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

Entrées

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

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

inputs.source

Définition des données sources.

Paramètre clé	Type	Requis	Paramètres de la demande	Description
inputs.source	`object`	True	• sourceUrl (chaîne) • filter (objet) • language (chaîne) • storageSource (chaîne)	Données sources pour les documents d’entrée.
inputs.source.sourceUrl	`string`	True	•corde	Emplacement du conteneur pour le fichier ou dossier source.
inputs.source.filter	`object`	False	• 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`	False	•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`	False	•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`	False	•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`	False	•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é	Type	Requis	Paramètres de la demande	Description
inputs.targets	`array`	True	• 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`	True	•corde	Localisation de l’emplacement du conteneur pour les documents traduits.
inputs.targets.category	`string`	False	•corde	Classification ou catégorie pour la requête de traduction. Exemple : général.
inputs.targets.language	`string`	True	•corde	Code de langue cible. Example : « fr ».
inputs.targets.glossaries	`array`	False	• glossaryUrl (chaîne) • format (chaîne) • version (chaîne) • storageSource (chaîne)	Voir Créer et utiliser des glossaires
inputs.targets.glossaries.glossaryUrl	`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`	False	•corde	Format de fichier spécifié pour le glossaire. Pour vérifier si votre format de fichier est pris en charge, consultez Obtenir les formats de glossaire pris en charge.
inputs.targets.glossaries.version	`string`	False	•corde	Indicateur de version. Exemple : « 2.0 ».
inputs.targets.glossaries.storageSource	`string`	False	•corde	Source de stockage pour les glossaires. La valeur par défaut est `_AzureBlob_`.
inputs.targets.storageSource	`string`	False	•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é	Type	Requis	Paramètres de la demande	Description
inputs.storageType	`string`	False	•`Folder` • `File`	Type de stockage de la chaîne source des documents d’entrée. Seules « Dossier » ou « Fichier » sont des valeurs valides.

Options

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

Paramètre clé	Type	Requis	Paramètres de la demande	Description
options	`object`	False	Informations sources pour les documents d’entrée.
options.experimental	`boolean`	False	•`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, un accès limité a été accordé au contenu d’un conteneur de stockage Azure à l’aide d’un jeton de signature d’accès partagé (SAS).

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 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 {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.

En-tête de réponse	URL de réponse
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

Codes d’état de réponse

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

Code d’état	Description
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é	Type	Description
code	`string`	Enums contenant des codes d’erreur généraux. Valeurs possibles :</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Non autorisé
message	`string`	Obtient un message d’erreur général.
innerError	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é).
inner.Errorcode	`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 du service Traduction de document et de la bibliothèque de client.

Bien démarrer avec la traduction de documentation

Partager via