Guida introduttiva: API REST di Traduttore per Azure AI

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#

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"
            }
        ]
    }
]

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.

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"
            }
        ]
    }
]

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"
      }
    ]
  }
]

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"
            }
        ]
    }
]

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"
      }
    ]
  }
]