Avvia traduzione

Articolo
02/23/2024

Servizio di riferimento
: Versione dell'API Traduzione
documenti di Azure per intelligenza artificiale: v1.1

Usare questa API per avviare una richiesta di traduzione con il servizio traduzione documenti. Ogni richiesta può contenere più documenti e deve contenere un contenitore di origine e di destinazione per ogni documento.

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.

La memoria di glossario/traduzione può essere inclusa nella richiesta e applicata dal servizio quando il documento viene tradotto.

Se il glossario non è valido o non raggiungibile durante la traduzione, viene indicato un errore nello stato del documento. Se nella destinazione esiste già un file con lo stesso nome, il processo ha esito negativo. TargetUrl per ogni lingua di destinazione deve essere univoco.

Richiesta URL

Inviare una richiesta POST a:

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

Informazioni su come trovare il nome di dominio personalizzato.

Importante

Tutte le richieste API al servizio traduzione documenti richiedono un endpoint di dominio personalizzato.
Non è possibile usare l'endpoint trovato nella pagina delle chiavi e dell'endpoint della risorsa portale di Azure né nell'endpoint traduttore globale,api.cognitive.microsofttranslator.com per effettuare richieste HTTP a Traduzione documenti.

Intestazioni delle richieste

Le intestazioni della richiesta sono le seguenti:

Intestazioni	Descrizione
Ocp-Apim-Subscription-Key	Intestazione della richiesta obbligatoria

BatchRequest (corpo)

Definizione per la richiesta di conversione batch di input. 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.


{
  "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 le destinazioni. Il valore predefinito è `_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?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduzione di tutti i documenti in un contenitore che applica glossari

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "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?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "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?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "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 • Server temporaneo non disponibile

Risposta con errore

Parametro chiave	Tipo	Descrizione
codice	`string`	Enumerazioni contenenti codici di errore di alto livello. Valori possibili: InternalServerError InvalidArgument InvalidRequest RequestRateTooHigh ResourceNotFound ServiceUnavailable Non autorizzata
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.

Esempi

Esempio di risposta riuscita

Le informazioni seguenti vengono restituite in una risposta con esito positivo.

È possibile trovare l'ID processo nel valore dell'URL dell'intestazione dell'operazione di intestazione del metodo POST. L'ultimo parametro dell'URL è l'ID processo dell'operazione (la stringa seguente "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

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

Share via