Guida introduttiva: uso della libreria client di rilevamento della lingua e dell'API REST

  • Articolo

Documentazione | di | riferimento Altri esempi pacchetto (NuGet) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di rilevamento della lingua con la libreria client per .NET. Nell'esempio seguente viene creata un'applicazione C# in grado di identificare il linguaggio in cui è stato scritto un esempio di testo.

Suggerimento

È possibile usare Language Studio per provare le funzionalità del servizio di linguaggio senza dover scrivere codice.

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • L'IDE di Visual Studio
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa lingua nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • È necessaria la chiave e l'endpoint della risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nella guida introduttiva.
    • È possibile usare il piano tariffario gratuito (Free F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Configurazione

Creare una nuova applicazione .NET Core

Usando l'IDE di Visual Studio, creare una nuova app console .NET Core. Viene creato un progetto "Hello World" con un singolo file di origine C#: program.cs.

Installare la libreria client facendo clic con il pulsante destro del mouse sulla soluzione in Esplora soluzioni e scegliendo Gestisci pacchetti NuGet. Nella finestra di dialogo Gestione pacchetti visualizzata selezionare Sfoglia e cercare Azure.AI.TextAnalytics. Selezionare la versione 5.2.0, quindi Installa. È anche possibile usare la console di gestione pacchetti.

Esempio di codice

Copiare il codice seguente nel file program.cs . Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa. A questo punto, eseguire il codice.

Importante

Vai al portale di Azure. Se la risorsa Lingua creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint passando alla pagina Chiavi ed endpoint della risorsa in Gestione risorse.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza dei servizi di intelligenza artificiale di Azure.

using Azure;
using System;
using Azure.AI.TextAnalytics;

namespace LanguageDetectionExample
{
    class Program
    {

        // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
        static string languageKey = Environment.GetEnvironmentVariable("LANGUAGE_KEY");
        static string languageEndpoint = Environment.GetEnvironmentVariable("LANGUAGE_ENDPOINT");

        // Example method for detecting the language of text
        static void LanguageDetectionExample(TextAnalyticsClient client)
        {
            DetectedLanguage detectedLanguage = client.DetectLanguage("Ce document est rédigé en Français.");
            Console.WriteLine("Language:");
            Console.WriteLine($"\t{detectedLanguage.Name},\tISO-6391: {detectedLanguage.Iso6391Name}\n");
        }

        static void Main(string[] args)
        {
            var client = new TextAnalyticsClient(languageEndpoint, languageKey);
            LanguageDetectionExample(client);

            Console.Write("Press any key to exit.");
            Console.ReadKey();
        }

    }
}

Output

Language:
    French, ISO-6391: fr

Documentazione di | riferimento | Altro codice sorgente del pacchetto di esempi (Maven)Library |

Usare questa guida introduttiva per creare un'applicazione di rilevamento del linguaggio con la libreria client per Java. Nell'esempio seguente viene creata un'applicazione Java in grado di identificare il linguaggio in cui è stato scritto un esempio di testo.

Suggerimento

È possibile usare Language Studio per provare le funzionalità del servizio di linguaggio senza dover scrivere codice.

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • Java Development Kit (JDK) versione 8 o successiva
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa lingua nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • È necessaria la chiave e l'endpoint della risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint vengono incollati nel codice seguente più avanti nella guida introduttiva.
    • È possibile usare il piano tariffario gratuito (Free F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Configurazione

Aggiungere la libreria client

Creare un progetto Maven nell'ambiente IDE o di sviluppo preferito. Aggiungere quindi la dipendenza seguente al file pom.xml del progetto. È possibile trovare la sintassi di implementazione per altri strumenti di compilazione online.

<dependencies>
     <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-textanalytics</artifactId>
        <version>5.2.0</version>
    </dependency>
</dependencies>

Esempio di codice

Creare un file Java denominato Example.java. Aprire il file e copiare il codice seguente. Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa. A questo punto, eseguire il codice.

Importante

Vai al portale di Azure. Se la risorsa Lingua creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint passando alla pagina Chiavi ed endpoint della risorsa in Gestione risorse.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza dei servizi di intelligenza artificiale di Azure.

import com.azure.core.credential.AzureKeyCredential;
import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;

public class Example {

    // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
    private static String languageKey = System.getenv("LANGUAGE_KEY");
    private static String languageEndpoint = System.getenv("LANGUAGE_ENDPOINT");

    public static void main(String[] args) {
        TextAnalyticsClient client = authenticateClient(languageKey, languageEndpoint);
        detectLanguageExample(client);
    }
    // Method to authenticate the client object with your key and endpoint
    static TextAnalyticsClient authenticateClient(String key, String endpoint) {
        return new TextAnalyticsClientBuilder()
                .credential(new AzureKeyCredential(key))
                .endpoint(endpoint)
                .buildClient();
    }
    // Example method for detecting the language of text
    static void detectLanguageExample(TextAnalyticsClient client)
    {
        // The text to be analyzed.
        String text = "Ce document est rédigé en Français.";

        DetectedLanguage detectedLanguage = client.detectLanguage(text);
        System.out.printf("Detected primary language: %s, ISO 6391 name: %s, score: %.2f.%n",
                detectedLanguage.getName(),
                detectedLanguage.getIso6391Name(),
                detectedLanguage.getConfidenceScore());
    }
}

Output

Detected primary language: French, ISO 6391 name: fr, score: 1.00.

Documentazione di | riferimento | Altro pacchetto di esempi (npm) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di rilevamento della lingua con la libreria client per Node.js. Nell'esempio seguente viene creata un'applicazione JavaScript in grado di identificare il linguaggio in cui è stato scritto un esempio di testo.

Suggerimento

È possibile usare Language Studio per provare le funzionalità del servizio di linguaggio senza dover scrivere codice.

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • Node.js v14 LTS o versioni successive
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa lingua nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • È necessaria la chiave e l'endpoint della risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint vengono incollati nel codice seguente più avanti nella guida introduttiva.
    • È possibile usare il piano tariffario gratuito (Free F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Configurazione

Creare una nuova applicazione Node.js

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

mkdir myapp 

cd myapp

Eseguire il comando npm init per creare un'applicazione Node con un file package.json.

npm init

Installare la libreria client

Installare il pacchetto npm:

npm install @azure/ai-language-text

Esempio di codice

Aprire il file e copiare il codice seguente. Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa. A questo punto, eseguire il codice.

Importante

Vai al portale di Azure. Se la risorsa Lingua creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint passando alla pagina Chiavi ed endpoint della risorsa in Gestione risorse.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza dei servizi di intelligenza artificiale di Azure.

"use strict";

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
const key = process.env.LANGUAGE_KEY;
const endpoint = process.env.LANGUAGE_ENDPOINT;

//Example sentences in different languages to be analyzed
const documents = [
    "This document is written in English.",
    "这是一个用中文写的文件",
];

//Example of how to use the client library to detect language
async function main() {
    console.log("== Language detection sample ==");
  
    const client = new TextAnalysisClient(endpoint, new AzureKeyCredential(key));
  
    const result = await client.analyze("LanguageDetection", documents);
  
    for (const doc of result) {
      if (!doc.error) {
        console.log(
          `ID ${doc.id} - Primary language: ${doc.primaryLanguage.name} (iso6391 name: ${doc.primaryLanguage.iso6391Name})`
        );
      }
    }
}

main().catch((err) => {
    console.error("The sample encountered an error:", err);
});

Output

== Language detection sample ==
ID 0 - Primary language: English (iso6391 name: en)
ID 1 - Primary language: Chinese_Simplified (iso6391 name: zh_chs)

Documentazione di | riferimento | Altro codice sorgente del pacchetto di esempi (PyPi)Library |

Usare questa guida introduttiva per creare un'applicazione di rilevamento del linguaggio con la libreria client per Python. Nell'esempio seguente viene creata un'applicazione Python in grado di identificare il linguaggio in cui è stato scritto un esempio di testo.

Suggerimento

È possibile usare Language Studio per provare le funzionalità del servizio di linguaggio senza dover scrivere codice.

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • Python 3.8 o versione successiva
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa lingua nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • È necessaria la chiave e l'endpoint della risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint vengono incollati nel codice seguente più avanti nella guida introduttiva.
    • È possibile usare il piano tariffario gratuito (Free F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Configurazione

Installare la libreria client

Dopo l'installazione di Python, è possibile installare la libreria client con:

pip install azure-ai-textanalytics==5.2.0

Esempio di codice

Creare un nuovo file Python e copiare il codice seguente. Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa. A questo punto, eseguire il codice.

Importante

Vai al portale di Azure. Se la risorsa Lingua creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint passando alla pagina Chiavi ed endpoint della risorsa in Gestione risorse.

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni, vedere l'articolo sulla sicurezza dei servizi di intelligenza artificiale di Azure.


# This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
language_key = os.environ.get('LANGUAGE_KEY')
language_endpoint = os.environ.get('LANGUAGE_ENDPOINT')

from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential

# Authenticate the client using your key and endpoint 
def authenticate_client():
    ta_credential = AzureKeyCredential(language_key)
    text_analytics_client = TextAnalyticsClient(
            endpoint=language_endpoint, 
            credential=ta_credential)
    return text_analytics_client

client = authenticate_client()

# Example method for detecting the language of text
def language_detection_example(client):
    try:
        documents = ["Ce document est rédigé en Français."]
        response = client.detect_language(documents = documents, country_hint = 'us')[0]
        print("Language: ", response.primary_language.name)

    except Exception as err:
        print("Encountered exception. {}".format(err))
language_detection_example(client)

Output

Language:  French

Documentazione di riferimento

Usare questa guida introduttiva per inviare richieste di rilevamento della lingua usando l'API REST. Nell'esempio seguente si userà cURL per identificare la lingua in cui è stato scritto un esempio di testo.

Prerequisiti

Configurazione

Creare una risorsa di Azure

Per usare l'esempio di codice seguente, è necessario distribuire una risorsa di Azure. Questa risorsa conterrà una chiave e un endpoint che verranno usati per autenticare le chiamate API inviate al servizio di linguaggio.

  1. Usare il collegamento seguente per creare una risorsa di linguaggio usando il portale di Azure. Sarà necessario accedere usando la sottoscrizione di Azure.

  2. Nella schermata Seleziona funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

    Screenshot che mostra opzioni di funzionalità aggiuntive nella portale di Azure.

  3. Nella schermata Crea lingua specificare le informazioni seguenti:

    Dettagli Descrizione
    Abbonamento Account di sottoscrizione a cui verrà associata la risorsa. Selezionare la sottoscrizione di Azure dal menu a discesa.
    Gruppo di risorse Un gruppo di risorse è un contenitore che archivia le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
    Paese Posizione della risorsa Lingua. Diverse aree possono introdurre latenza a seconda della posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questa guida introduttiva, selezionare un'area disponibile nelle vicinanze o scegliere Stati Uniti orientali.
    Nome Nome della risorsa lingua. Questo nome verrà usato anche per creare un URL dell'endpoint che le applicazioni useranno per inviare richieste API.
    Piano tariffario Piano tariffario per la risorsa Lingua. È possibile usare il livello F0 gratuito per provare il servizio ed eseguire l'aggiornamento in un secondo momento a un livello a pagamento per la produzione.

    Screenshot che mostra i dettagli della creazione delle risorse nella portale di Azure.

  4. Assicurarsi che la casella di controllo Avviso di intelligenza artificiale responsabile sia selezionata.

  5. Selezionare Rivedi e crea nella parte inferiore della pagina.

  6. Nella schermata visualizzata verificare che la convalida sia stata superata e che siano state immesse correttamente le informazioni. Selezionare Crea.

Ottenere la chiave e l'endpoint

Sarà quindi necessaria la chiave e l'endpoint dalla risorsa per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nella guida introduttiva.

  1. Dopo aver distribuito correttamente la risorsa lingua, fare clic sul pulsante Vai alla risorsa in Passaggi successivi.

    Screenshot che mostra i passaggi successivi dopo la distribuzione di una risorsa.

  2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Si userà una delle chiavi e l'endpoint nei passaggi seguenti.

    Screenshot che mostra le chiavi e la sezione endpoint per una risorsa.

Creare variabili di ambiente

L'applicazione deve essere autenticata per inviare richieste API. Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio si scriveranno le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Suggerimento

Non includere la chiave direttamente nel codice e non pubblicarla pubblicamente. Per altre opzioni di autenticazione come Azure Key Vault, vedere l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

Per impostare la variabile di ambiente per la chiave della risorsa lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

  1. Per impostare la LANGUAGE_KEY variabile di ambiente, sostituire your-key con una delle chiavi per la risorsa.
  2. Per impostare la LANGUAGE_ENDPOINT variabile di ambiente, sostituire your-endpoint con l'endpoint per la risorsa.
setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se è sufficiente accedere alle variabili di ambiente nella console in esecuzione corrente, è possibile impostare la variabile di setxambiente con set anziché .

Dopo aver aggiunto le variabili di ambiente, potrebbe essere necessario riavviare tutti i programmi in esecuzione che dovranno leggere le variabili di ambiente, inclusa la finestra della console. Se ad esempio si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

Creare un file JSON con il corpo della richiesta di esempio

In un editor di codice creare un nuovo file denominato test_detection_payload.json e copiare l'esempio JSON seguente. Questa richiesta di esempio verrà inviata all'API nel passaggio successivo.

Nota

  • È possibile trovare esempi specifici del linguaggio in GitHub.
{
    "kind": "LanguageDetection",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "text": "This is a document written in English."
            }
        ]
    }
}

Salva test_detection_payload.json da qualche parte sul tuo computer. Ad esempio, il desktop.

Inviare una richiesta di rilevamento della lingua

Usare i comandi seguenti per inviare la richiesta API usando il programma in uso. Copiare il comando nel terminale ed eseguirlo.

parameter Descrizione
-X POST <endpoint> Specifica l'endpoint per l'accesso all'API.
-H Content-Type: application/json Il tipo di contenuto per l'invio di dati JSON.
-H "Ocp-Apim-Subscription-Key:<key> Specifica la chiave per l'accesso all'API.
-d <documents> Il codice JSON contenente i documenti da inviare.

Sostituire C:\Users\<myaccount>\Desktop\test_detection_payload.json con il percorso del file di richiesta JSON di esempio creato nel passaggio precedente.

Prompt dei comandi

curl -X POST "%LANGUAGE_ENDPOINT%/language/:analyze-text?api-version=2023-11-15-preview" ^
-H "Content-Type: application/json" ^
-H "Ocp-Apim-Subscription-Key: %LANGUAGE_KEY%" ^
-d "@C:\Users\<myaccount>\Desktop\test_detection_payload.json"

PowerShell

curl.exe -X POST $env:LANGUAGE_ENDPOINT/language/:analyze-text?api-version=2023-11-15-preview `
-H "Content-Type: application/json" `
-H "Ocp-Apim-Subscription-Key: $env:LANGUAGE_KEY" `
-d "@C:\Users\<myaccount>\Desktop\test_detection_payload.json"

Risposta JSON

{
    "kind": "LanguageDetectionResults",
    "results": {
        "documents": [
            {
                "id": "1",
                "detectedLanguage": {
                    "name": "English",
                    "iso6391Name": "en",
                    "confidenceScore": 1.0,
                    "script": "Latin",
                    "scriptCode": "Latn"
                },
                "warnings": []
            }
        ],
        "errors": [],
        "modelVersion": "2023-12-01"
    }
}

Usare i comandi seguenti per eliminare le variabili di ambiente create per questa guida introduttiva.

reg delete "HKCU\Environment" /v LANGUAGE_KEY /f

reg delete "HKCU\Environment" /v LANGUAGE_ENDPOINT /f

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione dei servizi di intelligenza artificiale di Azure, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Passaggi successivi