Avviare la conversione batch

Articolo
09/26/2024

Funzionalità di riferimento
: Azure AI Translator → 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.

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 Translator dal portale di Azure.	Obbligatorio
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.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

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	•corda	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	•corda	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	•corda	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	•corda	Codice linguistico per i documenti di origine. Se non specificato, viene implementata la correzione automatica.
inputs.source.storageSource	`string`	Falso	•corda	Origine di archiviazione 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	•corda	Posizione del percorso del contenitore per i documenti tradotti.
inputs.targets.category	`string`	Falso	•corda	Classificazione o categoria per la richiesta di traduzione. Esempio: generale.
inputs.targets.language	`string`	Vero	•corda	Codice della lingua di destinazione. Esempio: "fr".
inputs.targets.glossaries	`array`	Falso	• glossaryUrl (string) • formato (string)• versione (string) • storageSource (string)	Vedere Creare e usare glossari
inputs.targets.glossaries.glossaryUrl	`string`	True (se si usano glossari)	•corda	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	•corda	Formato di file specificato per il glossario. Per verificare se il formato di file è supportato, vedere Ottenere formati di glossario supportati.
inputs.targets.glossaries.version	`string`	Falso	•corda	Indicatore della versione. Esempio: "2.0".
inputs.targets.glossaries.storageSource	`string`	Falso	•corda	Origine di archiviazione per i glossari. Il valore predefinito è `_AzureBlob_`.
inputs.targets.storageSource	`string`	Falso	•corda	Origine di archiviazione 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`	Tipo di archiviazione 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"
                }
            ]
        }
    ]
}

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.

Il id del processo viene trovato nell’intestazione della risposta del metodo start-batch-translation POST, in corrispondenza del valore URL Operation-Location. La stringa alfanumerica che segue il parametro /document/ è il id del processo dell'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.

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

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