Translator v3.0

Novità

La versione 3 del Translator offre 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 le traduzioni precedenti ed esempi che mostrano i termini usati nel contesto.
  • Altri risultati informativi sul rilevamento della lingua.

URL di base

Microsoft Translator è accessibile da più posizioni di data center. Attualmente si trovano in 10 aree geografiche di Azure:

  • Americhe: Stati Uniti orientali, Stati Uniti centro-meridionali, Stati Uniti centro-occidentali e Stati Uniti occidentali 2
  • Asia Pacifico: Corea meridionale, Giappone orientale, Asia sud-orientale e Australia orientale
  • Europa: Europa settentrionale, Europa occidentale

Le richieste al Microsoft Translator vengono nella maggior parte dei casi gestite dal data center più vicino alla posizione in cui ha avuto origine la richiesta. Se si verifica un errore del data center, la richiesta può essere instradata all'esterno dell'area geografica.

Per forzare la gestione della richiesta da parte di un'area geografica specifica, modificare l'endpoint globale nella richiesta API con l'endpoint geografico desiderato:

Area geografica URL di base (endpoint geografico)
Globale (non a livello di regione) api.cognitive.microsofttranslator.com
Stati Uniti api-nam.cognitive.microsofttranslator.com
Europa api-eur.cognitive.microsofttranslator.com
Asia Pacifico api-apc.cognitive.microsofttranslator.com

1 I clienti con una risorsa che si trova in Svizzera settentrionale o Svizzera occidentale possono garantire che le richieste dell'API Testo siano servite all'interno della Svizzera. Per assicurarsi che le richieste siano gestite in Svizzera, creare la risorsa Translator nell'area "Area della risorsa" "Svizzera settentrionale" o "Svizzera occidentale", quindi usare l'endpoint personalizzato della risorsa nelle richieste API. Ad esempio: se si crea una risorsa Translator in portale di Azure con "Area della risorsa" come "Svizzera settentrionale" e il nome della risorsa è "my-ch-n", l'endpoint personalizzato è " https://my-ch-n.cognitiveservices.azure.com ". Una richiesta di esempio per la traduzione è:

// Pass secret key and region using headers to a custom endpoint
curl -X POST " my-ch-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

2 L'Translator non è attualmente disponibile in Svizzera.

Authentication

Sottoscrivere Translator o servizi cognitivi multi-servizio in Servizi cognitivi di Azure e usare la chiave di sottoscrizione (disponibile nel portale di Azure) per eseguire l'autenticazione.

Sono tre le intestazioni che è possibile usare per autenticare la sottoscrizione. Questa tabella descrive come viene usato:

Intestazioni Descrizione
Ocp-Apim-Subscription-Key Usare con la sottoscrizione di Servizi cognitivi se si passa la chiave privata.
Il valore è la chiave privata di Azure per la sottoscrizione da Translator.
Autorizzazione Usare con la sottoscrizione di Servizi cognitivi se si passa un token di autenticazione.
Il valore è il token di connessione: Bearer <token>.
Ocp-Apim-Subscription-Region Usare con la risorsa traduzione multi-servizio e regionale di Servizi cognitivi.
Il valore è l'area della risorsa di traduzione multi-servizio o a livello di area. Questo valore è facoltativo quando si usa una risorsa di traduzione globale.

Chiave privata

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

Autenticazione con una risorsa globale

Quando si usa una risorsa di traduzione globale,è necessario includere un'intestazione per chiamare il Translator.

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

Di seguito è riportato un esempio di richiesta per chiamare il Translator usando la risorsa di traduzione 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 regione

Quando si usa una risorsa di traduzione a livello di regione. Sono disponibili due intestazioni che è necessario chiamare Translator.

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

Di seguito è riportato un esempio di richiesta per chiamare il Translator usando la risorsa traduzione a livello di regione

// 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 multi-servizio

Quando si usa una risorsa multi-servizio di Servizi cognitivi. In questo modo è possibile usare una singola chiave privata per autenticare le richieste per più servizi.

Quando si usa una chiave privata multi-servizio, è necessario includere due intestazioni di autenticazione con la richiesta. Sono disponibili due intestazioni che è necessario chiamare Translator.

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

L'area è necessaria per la sottoscrizione dell'API Di testo multi-servizio. L'area selezionata è l'unica area che è possibile usare per la traduzione testuale quando si usa la chiave di sottoscrizione multi-servizio e deve essere la stessa area selezionata al momento dell'iscrizione alla sottoscrizione multi-servizio tramite il portale di Azure.

Le aree disponibili australiaeast sono , , , , , , brazilsouth , , , canadacentral , , , centralindia , , centralus centraluseuap , , eastasia , eastus eastus2 francecentral japaneast japanwest koreacentral e northcentralus northeurope southcentralus southeastasia uksouth westcentralus westeurope westus westus2 southafricanorth .

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
Globale https://api.cognitive.microsoft.com/sts/v1.0/issueToken
A livello di regione o multi-servizio https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Di seguito sono riportati esempi di richieste per ottenere un token con una chiave privata:

// 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>'

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 Translator. Tuttavia, se il programma effettua richieste al Translator per un periodo di tempo prolungato, il programma deve richiedere un nuovo token di accesso a intervalli regolari ,ad esempio ogni 8 minuti.

Supporto della rete virtuale

Il Translator è ora disponibile con funzionalità di rete virtuale (VNET) in tutte le aree del cloud pubblico di Azure. Per abilitare la rete virtuale, vedere Configurazione Servizi cognitivi di Azure reti virtuali.

Dopo aver attivata questa funzionalità, è necessario usare l'endpoint personalizzato per chiamare l'Translator. Non è possibile usare l'endpoint del 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 di traduzione e aver consentito l'accesso da reti selezionate ed endpoint privati.

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

Ecco una richiesta di esempio per chiamare il Translator 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?'}]"

Errors

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 is not 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. Visualizzare 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. Visualizzare i limiti delle richieste.
400079 Il sistema personalizzato richiesto per la traduzione da/verso la lingua non esiste.
400080 La traslitterazione non è supportata per il linguaggio o lo script.
401000 La richiesta non è autorizzata perché le credenziali mancano o non sono 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 Translator."
403000 L'operazione non è consentita.
403001 L'operazione non è consentita perché la sottoscrizione ha superato la quota gratuita.
405000 Il metodo della richiesta non è supportato per la risorsa richiesta.
408001 È in corso la preparazione del sistema di traduzione richiesto. Riprovare tra pochi minuti.
408002 Timeout della richiesta in attesa del flusso in ingresso. Il client non ha generato una richiesta nel tempo in cui il server è stato preparato per l'attesa. 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.
500000 Si è verificato un 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. Riprovare. 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.

Metriche

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

Translator Metriche

Questa tabella elenca le metriche disponibili con una descrizione di come vengono usate per monitorare le chiamate API di traduzione.

Metriche Descrizione
TotalCalls Numero totale di chiamate API.
TotalTokenCalls Numero totale di chiamate API tramite il servizio token tramite 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 lato client (4XX).
Latenza Durata del completamento della richiesta in millisecondi.
CharactersTranslated Numero totale di caratteri nella richiesta di testo in ingresso.