Usare API REST in modo programmatico

  • Articolo

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

  • In genere, quando si crea una risorsa Azure per intelligenza artificiale nel portale di Azure, è possibile creare una chiave multiservizio o una chiave a servizio singolo. Tuttavia, la traduzione di documenti è attualmente supportata solo nella risorsa Traduttore (a servizio singolo) e non è inclusa nella risorsa Servizi di Azure AI (multiservizio).

  • Traduzione di documenti è supportato nel piano di servizio Standard S1 (con pagamento in base al consumo) e nei piani Sconto quantità C2, C3, C4 e D3. Vedere Prezzi 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 è il percorso in cui vengono archiviati i file tradotti (obbligatorio).

  • Una risorsa Traduttore a servizio singolo (non una risorsa Servizi di Azure AI multiservizio):

    Completare i campi dei dettagli del progetto Traduttore e dell'istanza come indicato di seguito:

    1. Sottoscrizione. Selezionare una delle sottoscrizioni di Azure disponibili.

    2. Gruppo di risorse. È possibile creare un nuovo gruppo di risorse o aggiungere la risorsa a un gruppo di risorse preesistente che condivide ciclo di vita, autorizzazioni e criteri identici.

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

    4. 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 sarà il parametro del nome di dominio personalizzato per l'endpoint.

    5. Piano tariffario. La traduzione di documenti non è supportata nel livello gratuito. Per provare il servizio, selezionare Standard S1.

    6. Selezionare Rivedi e crea.

    7. Esaminare le condizioni del servizio e selezionare Crea per distribuire la risorsa.

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

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

  2. Nel riquadro a sinistra, in Gestione risorse, selezionare Chiavi ed endpoint.

  3. Copiare e incollare key e document translation endpoint in una posizione comoda, ad esempio Blocco note Microsoft. Per effettuare una chiamata API è necessaria una sola chiave.

  4. Incollare key e document translation endpoint negli esempi di codice per autenticare la richiesta al servizio Traduzione di documenti.

    Screenshot che mostra il campo Ottieni la chiave nel portale di Azure.

Ottenere la chiave

Le richieste al servizio Traduttore richiedono una chiave di sola lettura per l'autenticazione dell'accesso.

  1. 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.
  2. Nel riquadro a sinistra, in Gestione risorse, selezionare Chiavi ed endpoint.
  3. Copiare e incollare la chiave in una posizione comoda, ad esempio Blocco note Microsoft.
  4. Incollarla nell'esempio di codice per autenticare la richiesta al servizio Traduzione di documenti.

Immagine del campo Otteni la chiave nel portale di Azure.

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 includere glossaryUrl con la richiesta. Se la coppia di lingue di traduzione non è presente nel glossario, non verrà applicata. Vedere Tradurre i documenti usando un glossario personalizzato

Creare token di accesso di firma di accesso condiviso per Traduzione di documenti

sourceUrl, targetUrl e facoltativamente glossaryUrl devono includere un token di firma di accesso condiviso (SAS), aggiunto come stringa di query. Il token può essere assegnato al contenitore o a BLOB specifici. Vedere Creare token di firma di accesso condiviso per il processo di Traduzione di documenti.

  • Il contenitore o il BLOB di origine deve designare l'accesso in lettura e per elenchi.
  • 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 stanno traducendo più file (BLOB) in un'operazione, delegare l'accesso di firma di accesso condiviso a livello di contenitore.
  • Se si sta traducendo un file singolo (BLOB) in un'operazione, delegare l'accesso di firma di accesso condiviso a livello di BLOB.
  • In alternativa ai token di firma di accesso condiviso, è possibile usare 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, vedere Limiti 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.
Content-Type 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 inputs contiene sia indirizzi di contenitore sourceURL che targetURL per le coppie di lingue di origine e di destinazione.
  • prefix e suffix sono stringhe che fanno distinzione tra maiuscole e minuscole per filtrare i documenti nel percorso di origine per la traduzione. Il campo prefix viene spesso usato per delineare le sottocartelle per la traduzione. Il campo suffix viene spesso usato per le estensioni di file.
  • Quando il documento viene convertito, viene applicato un valore per il campo glossaries (facoltativo).
  • targetUrl per ogni lingua di destinazione deve essere univoco.

Nota

Se nella destinazione esiste già un file con lo stesso nome, il processo avrà 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 token di URL e firma di accesso condiviso di origine per il BLOB/documento specifico (non per il contenitore).
  • Assicurarsi di aver specificato 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 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

Importante

Per gli esempi di codice, è necessario impostare come hardcoded l'URL della firma di accesso condiviso (SAS), dove indicato. Ricordarsi di rimuovere l'URL della firma di accesso condiviso dal codice al termine 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, vedere Sicurezza di Archiviazione di Azure.

Potrebbe essere necessario aggiornare i campi seguenti, a seconda dell'operazione:

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (ID processo)

Individuazione del valore id

  • 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={date}
  • È usare anche una richiesta get-translations-status anche 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 processo

Breve panoramica

Annullare l'elaborazione 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 è stata completata.
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 o il token siano validi e nell'area corretta. Quando si gestisce la sottoscrizione nel portale di Azure, assicurarsi di usare la risorsa Traduttore a servizio singolo e non i Servizi di Azure AI come risorsa multiservizio.
429 Troppe richieste È stata superata la quota o la frequenza di richieste consentite per la sottoscrizione.
502 Gateway non valido Problema di rete o lato server. Può anche indicare intestazioni non valide.

Altre informazioni

Passaggi successivi

Creare un sistema di lingua personalizzato usando Traduttore personalizzato