Traduttore v3.0

Articolo
02/14/2024

Novità

La versione 3.0 del Traduttore fornisce un'API Web moderna basata su JSON. Migliora l'usabilità e le prestazioni consolidando le funzionalità esistenti in un minor numero di operazioni e offre nuove funzionalità.

Traslitterazione per convertire il testo in una lingua da un carattere all'altro.
Traduzione in più lingue in una sola richiesta.
Rilevamento della lingua, traduzione e traslitterazione in una sola richiesta.
Dizionario per cercare traduzioni alternative di un termine, per trovare traduzioni e esempi che mostrano i termini usati nel contesto.
Altri risultati informativi sul rilevamento della lingua.

URL di base

Le richieste di Traduttore sono, nella maggior parte dei casi, gestite dal data center più vicino a dove ha avuto origine la richiesta. Se si verifica un errore del data center quando si usa l'endpoint globale, la richiesta potrebbe essere instradata all'esterno dell'area geografica.

Per forzare la gestione della richiesta all'interno di un'area geografica specifica, usare l'endpoint geografico desiderato. Tutte le richieste vengono elaborate tra i data center all'interno dell'area geografica.

Area geografica	URL di base (endpoint geografico)	Data center
Globale (`non-regional`)	api.cognitive.microsofttranslator.com	Data center più vicino disponibile
Asia Pacifico	api-apc.cognitive.microsofttranslator.com	Corea meridionale, Giappone orientale, Asia sud-orientale e Australia orientale
Europa	api-eur.cognitive.microsofttranslator.com	Nord Europa, Europa occidentale
Stati Uniti	api-nam.cognitive.microsofttranslator.com	Stati Uniti orientali, Stati Uniti centro-meridionali, Stati Uniti centro-occidentali e Stati Uniti occidentali 2

¹ I clienti con una risorsa che si trova in Svizzera settentrionale o svizzera occidentale possono garantire che le richieste dell'API Text vengano gestite in Svizzera. Per assicurarsi che le richieste vengano gestite in Svizzera, creare la risorsa Traduttore in Resource regionSwitzerland North o Switzerland West, quindi usare l'endpoint personalizzato della risorsa nelle richieste API.

Ad esempio: se si crea una risorsa Traduttore in portale di Azure con Resource region come Switzerland North e il nome della risorsa è my-swiss-n, l'endpoint personalizzato è https://my-swiss-n.cognitiveservices.azure.com. Una richiesta di esempio da tradurre è:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

²La Traduttore personalizzata non è attualmente disponibile in Svizzera.

Autenticazione

Sottoscrivere Traduttore o multiservizio nei servizi di intelligenza artificiale di Azure e usare la chiave (disponibile nella portale di Azure) per l'autenticazione.

Sono tre le intestazioni che è possibile usare per autenticare la sottoscrizione. Questa tabella descrive il modo in cui vengono usati i singoli elementi:

Intestazioni	Descrizione
Ocp-Apim-Subscription-Key	Usare con la sottoscrizione dei servizi di intelligenza artificiale di Azure se si passa la chiave privata. Il valore è la chiave privata di Azure per la sottoscrizione da Traduttore.
Autorizzazione	Usare con la sottoscrizione dei servizi di intelligenza artificiale di Azure se si passa un token di autenticazione. Il valore è il token di connessione: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Usare con risorse multiservizio e traduttore a livello di area. Il valore è l'area della risorsa traduttore multiservizio o regionale. Questo valore è facoltativo quando si usa una risorsa traduttore globale.

Chiave privata

La prima opzione consiste nell'eseguire l'autenticazione usando l'intestazione Ocp-Apim-Subscription-Key. Aggiungere l'intestazione Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> alla richiesta.

Autenticazione con una risorsa globale

Quando si usa una risorsa traduttore globale, è necessario includere un'intestazione per chiamare il Traduttore.

Intestazioni	Descrizione
Ocp-Apim-Subscription-Key	Il valore è la chiave privata di Azure per la sottoscrizione da Traduttore.

Ecco una richiesta di esempio per chiamare il Traduttore usando la risorsa traduttore globale

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Autenticazione con una risorsa a livello di area

Quando si usa una risorsa di traduzione a livello di area, sono necessarie due intestazioni per chiamare il Traduttore.

Intestazioni	Descrizione
Ocp-Apim-Subscription-Key	Il valore è la chiave privata di Azure per la sottoscrizione da Traduttore.
Ocp-Apim-Subscription-Region	Il valore è l'area della risorsa traduttore.

Ecco una richiesta di esempio per chiamare il Traduttore usando la risorsa traduttore a livello di area

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Autenticazione con una risorsa multiservizio

Una risorsa multiservizio consente di usare una singola chiave API per autenticare le richieste per più servizi.

Quando si usa una chiave privata multiservizio, è necessario includere due intestazioni di autenticazione con la richiesta. Esistono due intestazioni che è necessario chiamare il Traduttore.

Intestazioni	Descrizione
Ocp-Apim-Subscription-Key	Il valore è la chiave privata di Azure per la risorsa multiservizio.
Ocp-Apim-Subscription-Region	Il valore è l'area della risorsa multiservizio.

L'area è necessaria per la sottoscrizione dell'API Testo multiservizio. L'area selezionata è l'unica area che è possibile usare per la traduzione testuale quando si usa la chiave multiservizio. Deve essere la stessa area selezionata al momento dell'iscrizione alla sottoscrizione multiservizio tramite il portale di Azure.

Se si passa la chiave privata nella stringa di query con il parametro Subscription-Key, è necessario specificare l'area con il parametro di query Subscription-Region.

Autenticazione con un token di accesso

In alternativa, è possibile scambiare la chiave privata con un token di accesso. Questo token viene incluso in ogni richiesta come intestazione Authorization. Per ottenere un token di autorizzazione, effettuare una richiesta POST all'URL seguente:

Tipo di risorsa	URL servizio di autenticazione
Generale	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
A livello di area o multiservizio	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Di seguito sono riportate le richieste di esempio per ottenere un token dato una chiave privata per una risorsa globale:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Di seguito sono riportate le richieste di esempio per ottenere un token dato una chiave privata per una risorsa a livello di area che si trova negli Stati Uniti centrali:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Una richiesta con esito positivo restituisce il token di accesso codificato come testo normale nel corpo della risposta. Il token valido viene passato al servizio Translator come token di connessione nell'autorizzazione.

Authorization: Bearer <Base64-access_token>

Un token di autenticazione è valido per 10 minuti. Il token deve essere riutilizzato quando si effettuano più chiamate al Traduttore. Tuttavia, se il programma effettua richieste al Traduttore in un lungo periodo di tempo, il programma deve richiedere un nuovo token di accesso a intervalli regolari (ad esempio, ogni 8 minuti).

Autenticazione con Microsoft Entra ID

Traduttore v3.0 supporta l'autenticazione di Microsoft Entra, la soluzione di gestione delle identità e degli accessi basata sul cloud di Microsoft. Le intestazioni di autorizzazione consentono al servizio Traduttore di verificare che il client richiedente sia autorizzato a usare la risorsa e a completare la richiesta.

Prerequisiti

Breve comprensione di come eseguire l'autenticazione con Microsoft Entra ID.
Breve comprensione di come autorizzare l'accesso alle identità gestite.

Intestazioni

Intestazione	Valore
Autorizzazione	Il valore è un token di connessione di accesso generato da Azure AD. Il token di connessione fornisce la prova dell'autenticazione e convalida l'autorizzazione del client per l'uso della risorsa. Un token di autenticazione è valido per 10 minuti e deve essere riutilizzato quando si eseguono più chiamate a Traduttore. VedereRichiesta di esempio: 2. Ottenere un token
Ocp-Apim-Subscription-Region	Il valore è l'area della risorsa traduttore. Questo valore è facoltativo se la risorsa è globale.
Ocp-Apim-ResourceId	Il valore è l'ID risorsa per l'istanza della risorsa Traduttore. L'ID risorsa è disponibile nella portale di Azure in proprietà → risorsa Traduttore. Formato ID risorsa: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName/>

pagina delle proprietà Traduttore: portale di Azure

Screenshot:Translator properties page in the Azure portal.

Esempi

Uso dell'endpoint globale

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Uso dell'endpoint personalizzato

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Esempi di uso delle identità gestite

Traduttore v3.0 supporta anche l'autorizzazione dell'accesso alle identità gestite. Se un'identità gestita è abilitata per una risorsa traduttore, è possibile passare il token di connessione generato dall'identità gestita nell'intestazione della richiesta.

Con l'endpoint globale

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Con l'endpoint personalizzato

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Supporto della rete virtuale

Il servizio Traduttore è ora disponibile con funzionalità di Rete virtuale (VNET) in tutte le aree del cloud pubblico di Azure. Per abilitare Rete virtuale, vedereConfigurazione delle reti virtuali dei servizi di intelligenza artificiale di Azure.

Dopo aver attivato questa funzionalità, è necessario usare l'endpoint personalizzato per chiamare il Traduttore. Non è possibile usare l'endpoint traduttore globale ("api.cognitive.microsofttranslator.com") e non è possibile eseguire l'autenticazione con un token di accesso.

È possibile trovare l'endpoint personalizzato dopo aver creato una risorsa traduttore e consentire l'accesso da reti selezionate ed endpoint privati.

Passare alla risorsa Traduttore nella portale di Azure.
Selezionare Rete nella sezione Gestione risorse.
Nella scheda Firewall e reti virtuali scegliere Reti selezionate ed endpoint privati.
Seleziona Salva per applicare le modifiche.
Selezionare Chiavi ed endpoint nella sezione Gestione risorse.
Selezionare la scheda Rete virtuale.
Nell'elenco sono elencati gli endpoint per la traduzione testuale e la traduzione dei documenti.

Intestazioni	Descrizione
Ocp-Apim-Subscription-Key	Il valore è la chiave privata di Azure per la sottoscrizione da Traduttore.
Ocp-Apim-Subscription-Region	Il valore è l'area della risorsa traduttore. Questo valore è facoltativo se la risorsa è `global`

Ecco una richiesta di esempio per chiamare il Traduttore usando l'endpoint personalizzato

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Errori

Una risposta di errore standard è un oggetto JSON con coppia nome/valore denominato error. Il valore è anche un oggetto JSON con proprietà:

code: codice di errore definito dal server.
message: stringa che fornisce una rappresentazione dell'errore leggibile dall'utente.

Ad esempio, un cliente con una sottoscrizione della versione di valutazione gratuita riceverebbe l'errore seguente al superamento della quota gratuita:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

Il codice errore è un numero a 6 cifre che combina il codice di stato HTTP a 3 cifre seguito da un numero a 3 cifre per classificare ulteriormente l'errore. Codici errore comuni sono:

Codice	Descrizione
400000	Uno degli input della richiesta non è valido.
400001	Il parametro "scope" non è valido.
400002	Il parametro "category" non è valido.
400003	Un identificatore di lingua manca o non è valido.
400004	Un identificatore di script di destinazione ("To script") manca o non è valido.
400005	Un testo di input manca o non è valido.
400006	La combinazione di lingua e script non è valida.
400018	Un identificatore di script di origine ("From script") manca o non è valido.
400019	Una delle lingue specificate non è supportata.
400020	Uno degli elementi nella matrice del testo di input non è valido.
400021	Il parametro della versione API manca o non è valido.
400023	Una delle coppie di lingue specificata non è valida.
400035	La lingua di origine (campo "From") non è valida.
400036	La lingua di destinazione (campo "To") manca o non è valida.
400042	Una delle opzioni specificate (campo "Options") non è valida.
400043	L'ID traccia client (campo ClientTraceId o intestazione X-ClientTraceId) manca o non è valido.
400050	Il testo di input è troppo lungo. Vedere i limiti delle richieste.
400064	Il parametro "translation" manca o non è valido.
400070	Il numero di script di destinazione (parametro ToScript) non corrisponde al numero di lingue di destinazione (parametro To).
400071	Il valore non è valido per TextType.
400072	La matrice del testo di input contiene troppi elementi.
400073	Il parametro script non è valido.
400074	Il corpo della richiesta non è in formato JSON valido.
400075	La combinazione di coppia di lingue e categoria non è valida.
400077	Le dimensioni massime della richiesta sono state superate. Vedere i limiti delle richieste.
400079	Il sistema personalizzato richiesto per la traduzione da/verso la lingua non esiste.
400080	La traslitterazione non è supportata per la lingua o lo script.
401000	La richiesta non è autorizzata perché le credenziali sono mancanti o non valide.
401015	"Le credenziali specificate si riferiscono a Speech API. Per questa richiesta sono necessarie le credenziali per l'API Testo. Usare una sottoscrizione per Traduttore."
403000	L'operazione non è consentita.
403001	L'operazione non è consentita perché la sottoscrizione ha superato la quota gratuita.
405000	Il metodo di richiesta non è supportato per la risorsa richiesta.
408001	È in corso la preparazione del sistema di traduzione richiesto. Riprovare tra qualche minuto.
408002	Timeout della richiesta in attesa del flusso in ingresso. Il client non ha generato una richiesta entro l'intervallo di attesa previsto per il server. Il client può ripetere la richiesta senza modifiche in un secondo momento.
415000	L'intestazione Content-Type manca o non è valida.
429000, 429001, 429002	Il server ha rifiutato la richiesta perché il client ha superato i limiti delle richieste.
500.000	Errore imprevisto. Se l'errore persiste, segnalarlo specificando data e ora dell'errore, identificatore della richiesta indicato in X-RequestId nell'intestazione della risposta e identificatore del client indicato in X-ClientTraceId nell'intestazione della richiesta.
503000	Il servizio è temporaneamente non disponibile. Riprova. Se l'errore persiste, segnalarlo specificando data e ora dell'errore, identificatore della richiesta indicato in X-RequestId nell'intestazione della risposta e identificatore del client indicato in X-ClientTraceId nell'intestazione della richiesta.

Metrica

Le metriche consentono di visualizzare le informazioni sull'utilizzo e sulla disponibilità del traduttore in portale di Azure, nella sezione metriche, come illustrato nello screenshot seguente. Per altre informazioni, vedere Metriche dei dati e della piattaforma.

Translator Metrics

Questa tabella elenca le metriche disponibili con la descrizione del modo in cui vengono usate per monitorare le chiamate API di traduzione.

Metrica di	Descrizione
TotalCalls	Numero totale di chiamate API.
TotalTokenCalls	Numero totale di chiamate API tramite il servizio token usando il token di autenticazione.
SuccessfulCalls	Numero di chiamate riuscite.
TotalErrors	Numero di chiamate con risposta di errore.
BlockedCalls	Numero di chiamate che hanno superato il limite di frequenza o di quota.
ServerErrors	Numero di chiamate con errore interno del server (5XX).
ClientErrors	Numero di chiamate con errore sul lato client (4XX).
Latenza	Durata del completamento della richiesta in millisecondi.
CharactersTranslated	Numero totale di caratteri nella richiesta di testo in ingresso.