Translator v3.0

Novità

La versione 3.0 di Translator 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 a Translator sono, 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 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.

✔️ Funzionalità: Traduzione testuale

Endpoint di servizio Svizzera

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 Translator nel Resource region Switzerland North o Switzerland West, quindi usare l'endpoint personalizzato della risorsa nelle richieste API.

Ad esempio: se si crea una risorsa Translator nel 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

Custom Translator non è attualmente disponibile in Svizzera.

Autenticazione

Sottoscrivere Translator 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:

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

Ecco una richiesta di esempio per chiamare Translator usando la risorsa 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 area

Quando si usa una risorsa traduttore a livello di area, sono necessarie due intestazioni per chiamare Translator.

Ecco una richiesta di esempio per chiamare Translator 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 Translator.

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:

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 a Translator. Tuttavia, se il programma effettua richieste a Translator per 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

Translator 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

Pagina delle proprietà di Translator- portale di Azure

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

Translator 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 Translator è ora disponibile con funzionalità di Rete virtuale (VNET) in tutte le aree del cloud pubblico di Azure. Per abilitare Rete virtuale, vedere Configurazione delle reti virtuali dei servizi di intelligenza artificiale di Azure.

Dopo aver attivato questa funzionalità, è necessario usare l'endpoint personalizzato per chiamare Translator. 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.

1. Passare alla risorsa Traduttore nel portale di Azure.

2. Selezionare Rete nella sezione Gestione risorse.

3. Nella scheda Firewall e reti virtuali scegliere Reti selezionate ed endpoint privati.

   

4. Seleziona Salva per applicare le modifiche.

5. Selezionare Chiavi ed endpoint nella sezione Gestione risorse.

6. Selezionare la scheda Rete virtuale.

7. Nell'elenco sono elencati gli endpoint per la traduzione testuale e la traduzione dei documenti.

   

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

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:

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.

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