Partager via


Démarrer la traduction par lots

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

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.