Guida introduttiva: API REST di Traduttore per Azure AI

Provare la versione più recente di Traduttore per Azure AI. In questa guida introduttiva si inizierà a usare il servizio Traduttore per tradurre testo usando un linguaggio di programmazione preferito o l'API REST. Per questo progetto è consigliabile usare il piano tariffario gratuito (F0) mentre si impara la tecnologia. Successivamente si potrà passare a un piano a pagamento per la produzione.

Prerequisiti

È necessaria una sottoscrizione di Azure attiva. Se non si possiede una sottoscrizione di Azure, è possibile crearne una gratuitamente.

• Dopo aver creato la sottoscrizione di Azure, creare una risorsa Traduttore nel portale di Azure.

• Dopo la distribuzione della risorsa, selezionare Vai alla risorsa e recuperare la chiave e l'endpoint.

  • La chiave e l'endpoint della risorsa sono necessari per connettere l'applicazione al servizio Traduttore. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido. È possibile trovare questi valori nella pagina Chiavi ed endpoint del portale di Azure:

    

    Nota

    • Per questo avvio rapido è consigliabile usare una risorsa globale a servizio singolo di Traduzione testuale.
    • Con una risorsa globale a servizio singolo si includerà una sola intestazione di autorizzazione (Ocp-Apim-Subscription-key) con la richiesta dell'API REST. Il valore di Ocp-Apim-Subscription-key è la chiave privata di Azure per la sottoscrizione di Traduzione testuale.
    • Se si sceglie di usare una risorsa multiservizio di Azure per intelligenza artificiale o una risorsa Traduttore regionale, saranno necessarie due intestazioni di autenticazione: (Ocp-Api-Subscription-Key e Ocp-Apim-Subscription-Region). Il valore di Ocp-Apim-Subscription-Region è l'area associata alla sottoscrizione.
    • Per altre informazioni su come usare l'intestazione Ocp-Apim-Subscription-Region, vedere Intestazioni dell'API REST Traduzione testuale.

Intestazioni

Per chiamare il servizio Traduttore tramite l'API REST, è necessario includere le intestazioni seguenti con ogni richiesta. Per evitare problemi, includiamo le intestazioni nel codice di esempio per ogni linguaggio di programmazione.

Per altre informazioni sulle opzioni di autenticazione di Traduttore, vedere la guida Informazioni di riferimento su Translator v3.

Intestazione	Valore	Condizione
Ocp-Apim-Subscription-Key	La chiave del servizio Traduttore dal portale di Azure.	• Obbligatorio
Ocp-Apim-Subscription-Region	Area in cui è stata creata la risorsa.	• Obbligatorio quando si usa una risorsa multiservizio o area geografica di Azure per intelligenza artificiale, ad esempio Stati Uniti occidentali. • Facoltativo quando si usa una risorsa Traduttore globale a servizio singolo.
Content-Type	Tipo di contenuto del payload. Il valore accettato è application/json o charset=UTF-8.	• Obbligatorio
Content-Length	Lunghezza del corpo della richiesta.	• Facoltativo

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo Sicurezza di Servizi di Azure AI.

Tradurre testo

La funzione principale del servizio Traduttore è tradurre testo. In questo avvio rapido si compilerà una richiesta usando un linguaggio di programmazione di propria scelta che accetta una singola origine (from) e fornisce due output (to). Si esamineranno quindi alcuni parametri che possono essere usati per modificare sia la richiesta che la risposta.

Per informazioni dettagliate sui limiti delle richieste del servizio Traduttore per Azure AI, vedere Limiti delle richieste di traduzione testuale.

C#: Visual Studio

Configurare il progetto di Visual Studio

1. Assicurarsi che sia disponibile la versione corrente dell'IDE di Visual Studio.

   Suggerimento

   Se non si ha familiarità con Visual Studio, provare il modulo Learn Introduzione a Visual Studio.

2. Aprire Visual Studio.

3. Nella pagina Avvio, scegliere Crea nuovo progetto.

   

4. Nella pagina Crea un nuovo progetto immettere console nella casella di ricerca. Scegliere il modello Applicazione console, quindi selezionare Avanti.

   

5. Nella finestra di dialogo Configura il nuovo progetto, immettere translator_quickstart nella casella Nome progetto. Lasciare la casella di controllo "Inserisci soluzione e progetto nella stessa directory" deselezionata e scegliere Avanti.

   

6. Nella finestra di dialogo Altre informazioni assicurarsi che sia selezionata l'opzione .NET 6.0 (supporto a lungo termine). Lasciare la casella di controllo "Non usare istruzioni di primo livello" deselezionata e scegliere Crea.

   

Installare il pacchetto Newtonsoft.json con NuGet

1. Fare clic con il pulsante destro del mouse sul progetto translator_quickstart e selezionare Gestisci pacchetti NuGet....

   

2. Selezionare la scheda Sfoglia e digitare Newtonsoft.json.

   

3. Per aggiungere il pacchetto al progetto, selezionare Installa nella finestra di gestione pacchetti corretta.

   

Compilare l'applicazione C#

Nota

• A partire da .NET 6, i nuovi progetti che usano il modello console generano un nuovo stile di programma, diverso dalle versioni precedenti.
• Il nuovo output usa le funzionalità C# recenti che semplificano il codice da scrivere.
• Quando si usa la versione più recente, è sufficiente scrivere il corpo del metodo Main. Non è necessario includere istruzioni di primo livello, direttive d'uso globali o implicite.
• Per altre informazioni, vedere i nuovi modelli di C# generano istruzioni di primo livello.

1. Aprire il file Program.cs.

2. Eliminare il codice esistente, inclusa la riga Console.WriteLine("Hello World!"). Copiare e incollare l'esempio di codice nel file Program.cs dell'applicazione. Assicurarsi di aggiornare la variabile chiave con il valore dell'istanza di Traduttore del portale di Azure:

using System.Text;
using Newtonsoft.Json;

class Program
{
    private static readonly string key = "<your-translator-key>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=fr&to=zu";
        string textToTranslate = "I would really like to drive your car around the block a few times!";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Eseguire l'applicazione C#

Dopo aver aggiunto un esempio di codice all'applicazione, scegliere il pulsante verde di avvio accanto a formRecognizer_quickstart per compilare ed eseguire il programma oppure premere F5.

Output di traduzione:

Dopo una chiamata riuscita, si dovrebbe vedere la risposta seguente:

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Go

Configurare l'ambiente Go

Per scrivere applicazioni Go è possibile usare qualsiasi editor di testo. È consigliabile usare la versione più recente di Visual Studio Code e l'estensione Go.

Suggerimento

Se non si ha familiarità con Go, provare il modulo Learn Introduzione a Go.

1. Assicurarsi che sia installata la versione più recente di Go:

   • Scaricare la versione del linguaggio di programmazione Go per il sistema operativo in uso.

   • Al termine del download, eseguire il programma di installazione.

   • Aprire un prompt dei comandi e immettere quanto segue per confermare che Go è stato installato:

       go version
     

Compilare l'applicazione Go

1. In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app denominata translator-app.

2. Creare un nuovo file GO denominato translation.go dalla directory translator-app.

3. Copiare e incollare l'esempio di codice fornito nel file translation.go. Assicurarsi di aggiornare la variabile chiave con il valore dell'istanza di Traduttore del portale di Azure:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "net/url"
)

func main() {
    key := "<YOUR-TRANSLATOR-KEY>"
    endpoint := "https://api.cognitive.microsofttranslator.com/"
    uri := endpoint + "/translate?api-version=3.0"

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    location := "<YOUR-RESOURCE-LOCATION>"

    // Build the request URL. See: https://go.dev/pkg/net/url/#example_URL_Parse
    u, _ := url.Parse(uri)
    q := u.Query()
    q.Add("from", "en")
    q.Add("to", "fr")
    q.Add("to", "zu")
    u.RawQuery = q.Encode()

    // Create an anonymous struct for your request body and encode it to JSON
    body := []struct {
        Text string
    }{
        {Text: "I would really like to drive your car around the block a few times."},
    }
    b, _ := json.Marshal(body)

    // Build the HTTP POST request
    req, err := http.NewRequest("POST", u.String(), bytes.NewBuffer(b))
    if err != nil {
        log.Fatal(err)
    }
    // Add required headers to the request
    req.Header.Add("Ocp-Apim-Subscription-Key", key)
    // location required if you're using a multi-service or regional (not global) resource.
    req.Header.Add("Ocp-Apim-Subscription-Region", location)
    req.Header.Add("Content-Type", "application/json")

    // Call the Translator API
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }

    // Decode the JSON response
    var result interface{}
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        log.Fatal(err)
    }
    // Format and print the response to terminal
    prettyJSON, _ := json.MarshalIndent(result, "", "  ")
    fmt.Printf("%s\n", prettyJSON)
}

Eseguire l'applicazione Go

Dopo aver aggiunto un esempio di codice all'applicazione, il programma Go può essere eseguito in un prompt dei comandi o del terminale. Assicurarsi che il percorso del prompt sia impostato sulla cartella translator-app e usare il comando seguente:

 go run translation.go

Output di traduzione:

Dopo una chiamata riuscita, si dovrebbe vedere la risposta seguente:

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Java: Gradle

Configurare l'ambiente Java

• È necessario avere la versione più recente di Visual Studio Code o l'IDE preferito. Vedere Java in Visual Studio Code.

  Suggerimento

  • Visual Studio Code offre un Coding Pack per Java per Windows e macOS. Il Coding Pack è un bundle di VS Code, Java Development Kit (JDK) e una raccolta di estensioni suggerite da Microsoft. Il Coding Pack può essere usato anche per correggere un ambiente di sviluppo esistente.
  • Se si usano VS Code e Coding Pack per Java, installare l'estensione Gradle per Java.

• Se non si usa Visual Studio Code, assicurarsi di avere installato quanto segue nell'ambiente di sviluppo:

  • Un Java Development Kit (OpenJDK) versione 8 o successiva.

  • Gradle, versione 6.8 o successiva.

Creare un nuovo progetto Gradle

1. In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app denominata translator-text-app.

   mkdir translator-text-app && translator-text-app
   

    mkdir translator-text-app; cd translator-text-app
   

2. Eseguire il comando gradle init dalla directory translator-text-app. Questo comando crea i file di compilazione essenziali per Gradle, tra cui build.gradle.kts, che viene usato in fase di esecuzione per creare e configurare l'applicazione.

   gradle init --type basic
   

3. Quando viene chiesto di scegliere un linguaggio DSL, selezionare Kotlin.

4. Accettare il nome del progetto predefinito (translator-text-app) selezionando Torna o Invio.

5. Aggiornare build.gradle.kts con il codice seguente:

plugins {
  java
  application
}
application {
  mainClass.set("TranslatorText")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.squareup.okhttp3:okhttp:4.10.0")
  implementation("com.google.code.gson:gson:2.9.0")
}

Creare l'applicazione Java

1. Dalla directory translator-text-app eseguire il comando seguente:

   mkdir -p src/main/java
   

   Si crea la struttura di directory seguente:

   

2. Passare alla directory java e creare un file denominato TranslatorText.java.

   Suggerimento

   • È possibile creare un nuovo file usando PowerShell.

   • Aprire una finestra di PowerShell nella directory del progetto tenendo premuto MAIUSC e facendo clic con il pulsante destro del mouse sulla cartella.

   • Digitare il comando New-Item TranslatorText.java.

   • È anche possibile creare un nuovo file nell'IDE denominato TranslatorText.java e salvarlo nella directory java.

3. Aprire il file TranslatorText.java nell'IDE e quindi copiare e incollare l'esempio di codice seguente nell'applicazione. Assicurarsi di aggiornare la chiave con uno dei valori chiave dell'istanza di Traduttore del portale di Azure:

import java.io.IOException;

import com.google.gson.*;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class TranslatorText {
    private static String key = "<your-translator-key";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static String location = "<YOUR-RESOURCE-LOCATION>";


    // Instantiates the OkHttpClient.
    OkHttpClient client = new OkHttpClient();

    // This function performs a POST request.
    public String Post() throws IOException {
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType,
                "[{\"Text\": \"I would really like to drive your car around the block a few times!\"}]");
        Request request = new Request.Builder()
                .url("https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&to=zu")
                .post(body)
                .addHeader("Ocp-Apim-Subscription-Key", key)
                // location required if you're using a multi-service or regional (not global) resource.
                .addHeader("Ocp-Apim-Subscription-Region", location)
                .addHeader("Content-type", "application/json")
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }

    // This function prettifies the json response.
    public static String prettify(String json_text) {
        JsonParser parser = new JsonParser();
        JsonElement json = parser.parse(json_text);
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        return gson.toJson(json);
    }

    public static void main(String[] args) {
        try {
            TranslatorText translateRequest = new TranslatorText();
            String response = translateRequest.Post();
            System.out.println(prettify(response));
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

Compilare ed eseguire l'applicazione Java

Dopo aver aggiunto un esempio di codice all'applicazione, tornare alla directory principale del progetto (translator-text-app), aprire una finestra della console e immettere i comandi seguenti:

1. Compilare l'applicazione con il comando build:

   gradle build
   

2. Eseguire l'applicazione con il comando run:

   gradle run
   

Output di traduzione:

Dopo una chiamata riuscita, si dovrebbe vedere la risposta seguente:

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

JavaScript: Node.js

Configurare il progetto Node.js Express

1. Assicurarsi che sia installata la versione più recente di Node.js. Node Package Manager (npm) è incluso nell'installazione Node.js.

   Suggerimento

   Se non si ha familiarità con Node.js, provare il modulo di Learn Introduzione a Node.js.

2. In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app denominata translator-app.

       mkdir translator-app && cd translator-app
   

     mkdir translator-app; cd translator-app
   

3. Eseguire il comando npm init per inizializzare l'applicazione ed eseguire lo scaffolding del progetto.

      npm init
   

4. Specificare gli attributi del progetto usando le richieste presentate nel terminale.

   • Gli attributi più importanti sono nome, numero di versione e punto di ingresso.
   • È consigliabile mantenere index.js per il nome del punto di ingresso. La descrizione, il comando di test, il repository GitHub, le parole chiave, l'autore e le informazioni sulla licenza sono attributi facoltativi, ma possono essere ignorati per questo progetto.
   • Accettare i suggerimenti tra parentesi selezionando Restituisci o Immetti.
   • Dopo aver completato le richieste, nella directory translator-app verrà creato un file package.json.

5. Aprire una finestra della console e usare npm per installare la libreria HTTP axios e il pacchetto uuid:

      npm install axios uuid
   

6. Creare il file index.js nella directory dell'applicazione.

   Suggerimento

   • È possibile creare un nuovo file usando PowerShell.

   • Aprire una finestra di PowerShell nella directory del progetto tenendo premuto MAIUSC e facendo clic con il pulsante destro del mouse sulla cartella.

   • Digitare il comando New-Item index.js.

   • È anche possibile creare un nuovo file nell'IDE denominato index.js e salvarlo nella directory translator-app.

Compilare l'applicazione JavaScript

Aggiungere l'esempio di codice seguente al file index.js. Assicurarsi di aggiornare la variabile chiave con il valore dell'istanza di Traduttore del portale di Azure:

    const axios = require('axios').default;
    const { v4: uuidv4 } = require('uuid');

    let key = "<your-translator-key>";
    let endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    let location = "<YOUR-RESOURCE-LOCATION>";

    axios({
        baseURL: endpoint,
        url: '/translate',
        method: 'post',
        headers: {
            'Ocp-Apim-Subscription-Key': key,
             // location required if you're using a multi-service or regional (not global) resource.
            'Ocp-Apim-Subscription-Region': location,
            'Content-type': 'application/json',
            'X-ClientTraceId': uuidv4().toString()
        },
        params: {
            'api-version': '3.0',
            'from': 'en',
            'to': 'fr,zu'
        },
        data: [{
            'text': 'I would really like to drive your car around the block a few times!'
        }],
        responseType: 'json'
    }).then(function(response){
        console.log(JSON.stringify(response.data, null, 4));
    })

Eseguire l'applicazione JavaScript

Dopo aver aggiunto l'esempio di codice all'applicazione, eseguire il programma:

1. Passare alla directory dell'applicazione (translator-app).

2. Digitare il comando seguente nel terminale:

   node index.js
   

Output di traduzione:

Dopo una chiamata riuscita, si dovrebbe vedere la risposta seguente:

[
    {
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Python

Configurare il progetto Python

1. Assicurarsi che sia installata la versione più recente di Python 3.x. Il pacchetto del programma di installazione python (pip) è incluso nell'installazione di Python.

   Suggerimento

   Se non si ha familiarità con Python, provare il modulo di Learn Introduzione a Python.

2. Aprire una finestra del terminale e usare pip per installare la libreria Requests e il pacchetto uuid0:

      pip install requests uuid
   

   Nota

   Si userà anche un pacchetto predefinito Python denominato json. Viene usato per lavorare con i dati JSON.

Creare l'applicazione Python

1. Creare un nuovo file Python denominato translator-app.py nell'editor o nell'IDE preferito.

2. Aggiungere l'esempio di codice seguente al file translator-app.py. Assicurarsi di aggiornare la chiave con uno dei valori dell'istanza di Traduttore del portale di Azure.

import requests, uuid, json

# Add your key and endpoint
key = "<your-translator-key>"
endpoint = "https://api.cognitive.microsofttranslator.com"

# location, also known as region.
# required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
location = "<YOUR-RESOURCE-LOCATION>"

path = '/translate'
constructed_url = endpoint + path

params = {
    'api-version': '3.0',
    'from': 'en',
    'to': ['fr', 'zu']
}

headers = {
    'Ocp-Apim-Subscription-Key': key,
    # location required if you're using a multi-service or regional (not global) resource.
    'Ocp-Apim-Subscription-Region': location,
    'Content-type': 'application/json',
    'X-ClientTraceId': str(uuid.uuid4())
}

# You can pass more than one object in body.
body = [{
    'text': 'I would really like to drive your car around the block a few times!'
}]

request = requests.post(constructed_url, params=params, headers=headers, json=body)
response = request.json()

print(json.dumps(response, sort_keys=True, ensure_ascii=False, indent=4, separators=(',', ': ')))

Eseguire l'applicazione Python

Dopo aver aggiunto un esempio di codice all'applicazione, compilare ed eseguire il programma:

1. Passare al file translator-app.py.

2. Digitare il comando seguente nella console:

   python translator-app.py
   

Output di traduzione:

Dopo una chiamata riuscita, si dovrebbe vedere la risposta seguente:

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

Passaggi successivi

Fatto, congratulazioni! Si è appena appreso come usare il servizio Traduttore per tradurre testo.

Esplorare la documentazione sulle procedure e approfondire le funzionalità del servizio Traduzione:

• Tradurre un testo

• Traslitterare testo

• Rilevare e identificare la lingua

• Ottenere la lunghezza delle frasi

• Ricerca nel dizionario e traduzioni alternative