Avviare la conversione batch

Articolo
06/01/2024

Funzionalità di riferimento
: Azure AI Traduttore → versione dell'API Traduzione
documenti: metodo HTTP 2024-05-01
: POST

Usare il Start Translation metodo per eseguire una richiesta di conversione batch asincrona.
Il metodo richiede un account di archiviazione BLOB di Azure con contenitori di archiviazione per i documenti di origine e tradotti.

Suggerimento

Questo metodo restituisce il parametro del processo id per le stringhe di query get-translation-status, get-documents-status, get-document-status e cancel-translation request.

È possibile trovare il processo id nel valore DELL'URL dell'intestazione Operation-Location della risposta del metodo POSTstart-batch-translation. La stringa alfanumerica che segue il /document/ parametro è il processo iddell'operazione :

Intestazione di risposta	URL di risposta
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

È anche possibile usare una richiesta get-translations-status per recuperare un elenco di processi di traduzione e i relativi idprocessi.

Richiesta URL

Importante

Tutte le richieste API alla funzionalità Traduzione documenti richiedono un endpoint di dominio personalizzato che si trova nella pagina di panoramica delle risorse nella portale di Azure.

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

Intestazioni delle richieste

Le intestazioni della richiesta sono le seguenti:

Intestazioni	Descrizione	Condizione
Ocp-Apim-Subscription-Key	La chiave API del servizio Traduttore dal portale di Azure.	Richiesto
Ocp-Apim-Subscription-Region	Area in cui è stata creata la risorsa.	• Obbligatorio quando si usa una risorsa regionale (geografica) come Stati Uniti occidentali. &bullet.
Content-Type	Tipo di contenuto del payload. Il valore accettato è application/json o charset=UTF-8.	• Obbligatorio

BatchRequest (corpo)

Ogni richiesta può contenere più documenti e deve contenere un contenitore di origine e di destinazione per ogni documento. Tipi di supporti di origine: application/json, text/json, application/*+json.
Il filtro di prefisso e suffisso (se specificato) viene usato per filtrare le cartelle. Il prefisso viene applicato al sottopercorso dopo il nome del contenitore.
I glossari possono essere inclusi nella richiesta. Se il glossario non è valido o non raggiungibile durante la traduzione, viene indicato un errore nello stato del documento.
Se nella destinazione di destinazione esiste già un file con lo stesso nome, il processo ha esito negativo.
TargetUrl per ogni lingua di destinazione deve essere univoco.


{
  "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
  }
}

Input

Definizione per la richiesta di conversione batch di input.

Parametro chiave	Type	Obbligatorio	Parametri della richiesta	Descrizione
Ingressi	`array`	Vero	• source (object) • targets (array) • storageType (string)	Dati di origine di input.

inputs.source

Definizione per i dati di origine.

Parametro chiave	Type	Obbligatorio	Parametri della richiesta	Descrizione
inputs.source	`object`	Vero	• sourceUrl (string) • filter (object) • Language (string) • storageSource (string)	Dati di origine per i documenti di input.
inputs.source.sourceUrl	`string`	Vero	•Stringa	Percorso del contenitore per il file o la cartella di origine.
inputs.source.filter	`object`	Falso	• prefisso (stringa) • suffisso (stringa)	Stringhe con distinzione tra maiuscole e minuscole per filtrare i documenti nel percorso di origine.
inputs.source.filter.prefix	`string`	Falso	•Stringa	Stringa di prefisso con distinzione tra maiuscole e minuscole per filtrare i documenti nel percorso di origine per la traduzione. Spesso usato per designare le sottocartelle per la traduzione. Esempio: "FolderA".
inputs.source.filter.suffix	`string`	Falso	•Stringa	Stringa di suffisso con distinzione tra maiuscole e minuscole per filtrare i documenti nel percorso di origine per la traduzione. Più spesso usato per le estensioni di file. Esempio: ".txt"
inputs.source.language	`string`	Falso	•Stringa	Codice linguistico per i documenti di origine. Se non specificato, viene implementata la correzione automatica.
inputs.source.storageSource	`string`	Falso	•Stringa	Archiviazione'origine per gli input. Il valore predefinito è `AzureBlob`.

inputs.targets

Definizione per i dati di destinazione e glossari.

Parametro chiave	Type	Obbligatorio	Parametri della richiesta	Descrizione
inputs.targets	`array`	Vero	• targetUrl (string) • category (string)• language (string) • glossaries (array) • storageSource (string)	Destinazioni e glossari dati per i documenti tradotti.
inputs.targets.targetUrl	`string`	Vero	•Stringa	Posizione del percorso del contenitore per i documenti tradotti.
inputs.targets.category	`string`	Falso	•Stringa	Classificazione o categoria per la richiesta di traduzione. Esempio: generale.
inputs.targets.language	`string`	Vero	•Stringa	Codice della lingua di destinazione. Esempio: "fr".
inputs.targets.glossaries	`array`	Falso	• glossaryUrl (string) • formato (string)• versione (string) • storageSource (string)	VedereCreare e usare glossari
inputs.targets.glossaries.glossaryUrl	`string`	True (se si usano glossari)	•Stringa	Posizione del glossario. L'estensione di file viene usata per estrarre la formattazione se il parametro di formato non viene fornito. Se la coppia di lingue di traduzione non è presente nel glossario, non viene applicata.
inputs.targets.glossaries.format	`string`	Falso	•Stringa	Formato di file specificato per il glossario. Per verificare se il formato di file è supportato, vedereOttenere formati di glossario supportati.
inputs.targets.glossaries.version	`string`	Falso	•Stringa	Indicatore della versione. Esempio: "2.0".
inputs.targets.glossaries.storageSource	`string`	Falso	•Stringa	Archiviazione origine per i glossari. Il valore predefinito è `_AzureBlob_`.
inputs.targets.storageSource	`string`	Falso	•Stringa	Archiviazione origine per targets.defaults su `_AzureBlob_`.

inputs.storageType

Definizione dell'entità di archiviazione per i documenti di input.

Parametro chiave	Type	Obbligatorio	Parametri della richiesta	Descrizione
inputs.storageType	`string`	Falso	•`Folder` • `File`	Archiviazione tipo della stringa di origine dei documenti di input. Solo "Folder" o "File" sono valori validi.

Opzioni

Definizione per la richiesta di conversione batch di input.

Parametro chiave	Type	Obbligatorio	Parametri della richiesta	Descrizione
options	`object`	Falso	Informazioni di origine per i documenti di input.
options.experimental	`boolean`	Falso	•`true` • `false`	Indica se la richiesta include una funzionalità sperimentale (se applicabile). Solo i valori booleani `true` o `false` sono valori validi.

Richiesta di esempi

Di seguito sono riportati esempi di richieste batch.

Nota

Negli esempi seguenti è stato concesso l'accesso limitato al contenuto di un contenitore Archiviazione di Azure usando un token di firma di accesso condiviso.

Traduzione di tutti i documenti in un contenitore

{
    "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"
                }
            ]
        }
    ]
}

Traduzione di tutti i documenti in un contenitore che applica glossari

{
    "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"
                        }
                    ]

                }
            ]
        }
    ]
}

Conversione di una cartella specifica in un contenitore

Assicurarsi di specificare il nome della cartella (con distinzione tra maiuscole e minuscole) come prefisso nel filtro.

{
    "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"
                }
            ]
        }
    ]
}

Traduzione di un documento specifico in un contenitore

Specificare "storageType": File.
Creare un token di URL e firma di accesso condiviso di origine per il BLOB/documento specifico.
Specificare il nome file di destinazione come parte dell'URL di destinazione, anche se il token di firma di accesso condiviso è ancora per il contenitore.

Questa richiesta di esempio mostra un singolo documento tradotto in due lingue di destinazione.

{
    "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"
                }
            ]
        }
    ]
}

Codici di stato della risposta

Di seguito sono riportati i possibili codici di stato HTTP restituiti da una richiesta.

Codice di stato	Descrizione
202	Accettato. Richiesta riuscita e richiesta batch creata. L'intestazione Operation-Location indica un URL di stato con l'operazione ID.HeadersOperation-Location: stringa
400	Richiesta non valida. Richiesta non valida. Controllare i parametri di input.
401	Non autorizzato. Controllare le credenziali.
429	La frequenza delle richieste è troppo elevata.
500	Errore interno del server.
503	Il servizio non è attualmente disponibile. Riprovare.
Altri codici di stato	• Troppe richieste. Il server non è disponibile temporaneamente

Risposta con errore

Parametro chiave	Tipo	Descrizione
codice	`string`	Enumerazioni contenenti codici di errore di alto livello. Valori possibili:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Non autorizzato
messaggio	`string`	Ottiene un messaggio di errore di alto livello.
innerError	InnerTranslationError	Nuovo formato di errore interno conforme alle linee guida dell'API dei servizi di intelligenza artificiale di Azure. Questo messaggio di errore contiene le proprietà necessarie: ErrorCode, message e proprietà facoltative di destinazione, dettagli(coppia chiave-valore) e errore interno(può essere annidato).
Interno. Errorcode	`string`	Ottiene la stringa di errore del codice.
innerError.message	`string`	Ottiene un messaggio di errore di alto livello.
innerError.target	`string`	Ottiene l'origine dell'errore. Ad esempio, sarebbe `documents` o `document id` se il documento non è valido.

Esempio di risposta di errore

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

Passaggi successivi

Seguire la guida introduttiva per altre informazioni sull'uso della traduzione dei documenti e della raccolta client.

Introduzione alla traduzione di documenti

Condividi tramite