Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Traduzione di documenti è una funzionalità basata sul cloud del servizio Traduttore per Azure AI. È possibile usare l'API Traduzione di documenti per tradurre in modo asincrono interi documenti in lingue supportate e vari formati di file mantenendo al tempo stesso la struttura del documento di origine e la formattazione del testo. Questa guida pratica illustra come usare le API Traduzione di documenti con un linguaggio di programmazione preferito e l'API REST HTTP.
Prerequisiti
Nota
La traduzione di documenti è supportata nel piano di servizio Standard S1 (con pagamento in base al consumo) e nei piani Sconto per volume C2, C3, C4 e D3. VederePrezzi dei Servizi di Azure AI - Translator.
Per iniziare, è necessario:
Un account Azure attivo. Se non si ha un account, è possibile crearne uno gratuito
Un account di Archiviazione BLOB di Azure. È anche necessario creare i contenitori nell'account di Archiviazione BLOB di Azure per i file di origine e di destinazione:
- Contenitore di origine. Questo contenitore consente di caricare i file per la traduzione (obbligatorio).
- Contenitore di destinazione. Questo contenitore è la posizione in cui vengono archiviati i file tradotti (obbligatorio).
Una risorsa di Traduttore:
Completare i campi dei dettagli del progetto Traduttore e dell'istanza come indicato di seguito:
Sottoscrizione. Selezionare una delle sottoscrizioni di Azure disponibili.
Gruppo di risorse. È possibile creare un nuovo gruppo di risorse o aggiungere la risorsa a un gruppo di risorse esistente che condivide lo stesso ciclo di vita, autorizzazioni e criteri.
Area della risorsa. Scegliere Globale a meno che l'azienda o l'applicazione non richieda un'area specifica. Se si prevede di usare un'identità gestita assegnata dal sistema per l'autenticazione, scegliere un'area geografica come Stati Uniti occidentali.
Nome. Immettere il nome scelto per la risorsa. Il nome scelto deve essere univoco in Azure.
Nota
Traduzione di documenti richiede un endpoint di dominio personalizzato. Il valore immesso nel campo Nome è il parametro del nome di dominio personalizzato per l'endpoint.
Piano tariffario. La traduzione di documenti non è supportata nel livello gratuito. Per provare il servizio, selezionare Standard S1.
Selezionare Rivedi e crea.
Esaminare le condizioni del servizio e selezionare Crea per distribuire la risorsa.
Dopo la distribuzione riuscita della risorsa, selezionare Vai alla risorsa per recuperare la chiave e l'endpoint.
Recuperare la chiave e l'endpoint di dominio personalizzato
- Le richieste al servizio Traduttore richiedono una chiave di sola lettura e un endpoint personalizzato per autenticare l'accesso. L'endpoint di dominio personalizzato è un URL formattato con il nome della risorsa, il nome host e le sottodirectory di Traduttore ed è disponibile nel portale di Azure.
Se è stata creata una nuova risorsa, dopo la distribuzione selezionare Vai alla risorsa. Se si dispone di una risorsa di Traduzione di documenti esistente, passare direttamente alla pagina della risorsa.
Nel riquadro a sinistra, in Gestione risorse, selezionare Chiavi ed endpoint.
Copiare e incollare
keyedocument translation endpointin una posizione comoda, ad esempio Blocco note Microsoft. Per effettuare una chiamata API è necessaria una sola chiave.Incollare
keyedocument translation endpointnegli esempi di codice per autenticare la richiesta al servizio Traduzione di documenti.
Ottenere la chiave
Le richieste al servizio Traduttore richiedono una chiave di sola lettura per l'autenticazione dell'accesso.
- Se è stata creata una nuova risorsa, dopo la distribuzione selezionare Vai alla risorsa. Se si dispone di una risorsa di Traduzione di documenti esistente, passare direttamente alla pagina della risorsa.
- Nel riquadro a sinistra, in Gestione risorse, selezionare Chiavi ed endpoint.
- Copiare e incollare la chiave in una posizione comoda, ad esempio Blocco note Microsoft.
- Incollarla nell'esempio di codice per autenticare la richiesta al servizio Traduzione di documenti.
Creare contenitori di Archiviazione BLOB di Azure
Sarà necessario creare contenitori nell'account di Archiviazione BLOB di Azure per i file di origine e di destinazione.
- Contenitore di origine. Questo contenitore consente di caricare i file per la traduzione (obbligatorio).
- Contenitore di destinazione. Questo contenitore è la posizione in cui vengono archiviati i file tradotti (obbligatorio).
Nota
Traduzione di documenti supporta i glossari come BLOB nei contenitori di destinazione (non in contenitori di glossario separati). Se si vuole includere un glossario personalizzato, aggiungerlo al contenitore di destinazione e includerlo glossaryUrl con la richiesta. Se la coppia di lingue di traduzione non è presente nel glossario, il glossario non viene applicato. VedereTradurre i documenti usando un glossario personalizzato
Creare token di accesso SAS per la traduzione dei documenti
sourceUrl, targetUrl e facoltativamente glossaryUrl devono includere un token di firma di accesso condiviso (SAS), aggiunto come stringa di query. È possibile assegnare il token al contenitore o a BLOB specifici. ConsultaCreare token SAS per il processo di Traduzione di Documenti.
- Il contenitore o il BLOB di origine deve designare l'accesso di lettura ed elenco.
- Il contenitore o il BLOB di destinazione deve designare l'accesso di scrittura e per elenchi.
- Il BLOB del glossario deve designare l'accesso in lettura e per elenchi.
Suggerimento
- Se si traducono più file (BLOB) in un'operazione, delegare l'accesso di firma di accesso condiviso a livello di contenitore.
- Se stai traducendo un file singolo (blob) in un'operazione, delega l'accesso SAS a livello di blob.
- In alternativa ai SAS token di firma di accesso condiviso, è possibile utilizzare un'identità gestita assegnata dal sistema per l'autenticazione.
Richieste HTTP
Una richiesta di traduzione batch asincrona viene inviata all'endpoint del servizio Traduttore tramite una richiesta POST. In caso di esito positivo, il metodo POST restituisce un codice di risposta 202 Accepted e il servizio crea una richiesta batch. I documenti tradotti vengono elencati nel contenitore di destinazione.
Per informazioni dettagliate sui limiti delle richieste del servizio Traduttore per Azure AI, vedereLimiti delle richieste di traduzione di documenti.
Intestazioni HTTP
Le intestazioni seguenti sono incluse in ogni richiesta dell'API Traduzione di documenti:
| Intestazione HTTP | Descrizione |
|---|---|
| Ocp-Apim-Subscription-Key | Obbligatorio: il valore è la chiave di Azure per la risorsa Traduttore o di Servizi di Azure AI. |
| Tipo di Contenuto | Obbligatorio: specifica il tipo di contenuto del payload. I valori accettati sono application/json o charset=UTF-8. |
Proprietà del corpo della richiesta POST
- L'URL della richiesta è POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches. - Il corpo della richiesta POST è un oggetto JSON denominato
inputs. - L'oggetto
inputscontiene sia indirizzi di contenitoresourceURLchetargetURLper le coppie di lingue di origine e di destinazione. prefixesuffixsono stringhe che fanno distinzione tra maiuscole e minuscole per filtrare i documenti nel percorso di origine per la traduzione. Il campoprefixviene spesso usato per delineare le sottocartelle per la traduzione. Il camposuffixviene spesso usato per le estensioni di file.- Quando il documento viene convertito, viene applicato un valore per il campo
glossaries(facoltativo). targetUrlper ogni lingua di destinazione deve essere univoco.
Nota
Se nella destinazione esiste già un file con lo stesso nome, il processo ha esito negativo.
Tradurre tutti i documenti in un contenitore
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
Tradurre un documento specifico in un contenitore
- Specificare
"storageType": "File". - Se non si usa un'identità gestita assegnata dal sistema per l'autenticazione, assicurarsi di aver creato URL di origine e token SAS per il blob/documento specifico (non per il contenitore).
- Assicurarsi di aver specificato il nome del file di destinazione come parte dell'URL di destinazione, anche se il token SAS è ancora per il contenitore.
- Questa richiesta di esempio restituisce un singolo documento tradotto in due lingue di destinazione.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Tradurre i documenti usando un glossario personalizzato
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
Usare il codice per inviare richieste di Traduzione di documenti
Configurare la piattaforma di codifica
- Creare un nuovo progetto.
- Sostituire Program.cs con l'esempio di codice C#.
- Impostare i valori dell'endpoint, della chiave e dell'URL del contenitore in Program.cs.
- Aggiungere il pacchetto Newtonsoft.Json usando l'interfaccia della riga di comando di .NET per l'elaborazione dei dati JSON.
- Esegui il programma dalla directory del progetto.
Importante
Per gli esempi di codice, è necessario impostare come hardcoded l'URL della firma di accesso condiviso (SAS), dove indicato. Ricorda di rimuovere l'URL SAS dal codice quando hai finito, e di non pubblicarlo mai. Per la produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Identità gestita di Azure. Per altre informazioni, vedereSicurezza di Archiviazione di Azure.
Potrebbe essere necessario aggiornare i campi seguenti, a seconda dell'operazione:
endpointbasePathkeysourceURLtargetURLglossaryURLid(ID lavoro)
Individuazione del valore id
- È possibile trovare il processo
idnel valore URL dell’intestazione della risposta del metodostart-batch-translationPOSTOperation-Location. La stringa alfanumerica che segue il parametro/document/è il processo dell'operazioneid:
| Intestazione di risposta | URL di risposta |
|---|---|
| Operation-Location | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- Puoi anche utilizzare una richiesta get-translations-status per recuperare un elenco dei processi di traduzione e dei relativi
id.
Avviare traduzione batch asincrona
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
Ottenere i formati di documento supportati
Recuperare un elenco di formati di file supportati. In caso di esito positivo, questo metodo restituisce un codice di risposta 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Ottenere lo stato di un processo di traduzione
Ottenere lo stato corrente per un singolo processo e un riepilogo di tutti i processi in una richiesta di Traduzione di documenti. In caso di esito positivo, questo metodo restituisce un codice di risposta 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
Ottenere lo stato di un documento specifico
Breve panoramica
Recuperare lo stato di un documento specifico in una richiesta di Traduzione di documenti. In caso di esito positivo, questo metodo restituisce un codice di risposta 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Eliminare un'attività
Breve panoramica
Annullare il processo corrente o il processo in coda. Vengono annullati solo i documenti per i quali la traduzione non viene avviata.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Codici di stato HTTP comuni
| Codice di stato HTTP | Descrizione | Possibile motivo |
|---|---|---|
| 200 | OK | La richiesta è riuscita. |
| 400 | Richiesta non valida | Un parametro obbligatorio è mancante, vuoto o Null. In alternativa, il valore passato a un parametro obbligatorio o facoltativo non è valido. Un problema comune è la lunghezza eccessiva dell'intestazione. |
| 401 | Non autorizzata | La richiesta non è autorizzata. Assicurarsi che la chiave di sottoscrizione o il token sia valido e si trovi nell'area corretta. |
| 429 | Troppe richieste | È stata superata la quota o la frequenza di richieste consentite per la sottoscrizione. |
| 502 | Gateway non valido | Problema di rete o problema nel server. Può anche indicare intestazioni non valide. |