Condividi tramite

Guida introduttiva: rilevare informazioni personali (PII)

  • Articolo

Nota

Questa guida introduttiva illustra solo il rilevamento delle informazioni personali nei documenti. Per altre informazioni sul rilevamento delle informazioni personali nelle conversazioni, vedere Come rilevare e offuscare le informazioni personali nelle conversazioni.

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

Considerare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali con la libreria client per .NET. Nell'esempio seguente si creerà un'applicazione C# in grado di identificare le informazioni riservate riconosciute nel testo.

Suggerimento

È possibile usare Language Studio per provare il rilevamento delle informazioni personali nei documenti senza dover scrivere codice.

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

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

  2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

    Screenshot che mostra opzioni di funzionalità aggiuntive nel 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 nell'elenco a discesa.
    Gruppo di risorse Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
    Area La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
    Nome Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
    Piano tariffario Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

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

  4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

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

  6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

  1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

    Screenshot che mostra i passaggi successivi alla distribuzione di una risorsa.

  2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

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

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

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

  • Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
  • Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

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

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

Creare una nuova applicazione .NET Core

Usando l'IDE di Visual Studio, creare una nuova app console .NET Core. Con questa operazione 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 seguente codice nel file program.cs ed eseguirlo.

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

namespace Example
{
    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");

        private static readonly AzureKeyCredential credentials = new AzureKeyCredential(languageKey);
        private static readonly Uri endpoint = new Uri(languageEndpoint);

        // Example method for detecting sensitive information (PII) from text 
        static void RecognizePIIExample(TextAnalyticsClient client)
        {
            string document = "Call our office at 312-555-1234, or send an email to support@contoso.com.";
        
            PiiEntityCollection entities = client.RecognizePiiEntities(document).Value;
        
            Console.WriteLine($"Redacted Text: {entities.RedactedText}");
            if (entities.Count > 0)
            {
                Console.WriteLine($"Recognized {entities.Count} PII entit{(entities.Count > 1 ? "ies" : "y")}:");
                foreach (PiiEntity entity in entities)
                {
                    Console.WriteLine($"Text: {entity.Text}, Category: {entity.Category}, SubCategory: {entity.SubCategory}, Confidence score: {entity.ConfidenceScore}");
                }
            }
            else
            {
                Console.WriteLine("No entities were found.");
            }
        }

        static void Main(string[] args)
        {
            var client = new TextAnalyticsClient(endpoint, credentials);
            RecognizePIIExample(client);

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

    }
}

Output

Redacted Text: Call our office at ************, or send an email to *******************.
Recognized 2 PII entities:
Text: 312-555-1234, Category: PhoneNumber, SubCategory: , Confidence score: 0.8
Text: support@contoso.com, Category: Email, SubCategory: , Confidence score: 0.8

Documentazione di riferimento | Altri esempi | Pacchetto (Maven) | Codice sorgente della libreria

Considerare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali con la libreria client per Java. Nell'esempio seguente si crea un'applicazione Java in grado di identificare le informazioni riservate riconosciute nel testo.

Suggerimento

È possibile usare Language Studio per provare il rilevamento delle informazioni personali nei documenti senza dover scrivere codice.

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

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

  2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

    Screenshot che mostra opzioni di funzionalità aggiuntive nel 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 nell'elenco a discesa.
    Gruppo di risorse Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
    Area La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
    Nome Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
    Piano tariffario Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

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

  4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

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

  6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

  1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

    Screenshot che mostra i passaggi successivi alla distribuzione di una risorsa.

  2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

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

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

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

  • Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
  • Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

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

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

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. A questo punto, eseguire il codice.

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);
        recognizePiiEntitiesExample(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 sensitive information (PII) from text 
    static void recognizePiiEntitiesExample(TextAnalyticsClient client)
    {
        // The text that need be analyzed.
        String document = "My SSN is 859-98-0987";
        PiiEntityCollection piiEntityCollection = client.recognizePiiEntities(document);
        System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
        piiEntityCollection.forEach(entity -> System.out.printf(
            "Recognized Personally Identifiable Information entity: %s, entity category: %s, entity subcategory: %s,"
                + " confidence score: %f.%n",
            entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));
    }
}

Output

Redacted Text: My SSN is ***********
Recognized Personally Identifiable Information entity: 859-98-0987, entity category: USSocialSecurityNumber, entity subcategory: null, confidence score: 0.650000.

Documentazione di riferimento | Altri esempi | Pacchetto (npm) | Codice sorgente della libreria

Considerare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali con la libreria client per Node.js. Nell’esempio seguente si crea un’applicazione JavaScript in grado di identificare le informazioni riservate riconosciute nel 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 Lingua.

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

  2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

    Screenshot che mostra opzioni di funzionalità aggiuntive nel 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 nell'elenco a discesa.
    Gruppo di risorse Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
    Area La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
    Nome Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
    Piano tariffario Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

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

  4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

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

  6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

  1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

    Screenshot che mostra i passaggi successivi alla distribuzione di una risorsa.

  2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

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

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

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

  • Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
  • Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

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

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

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-text-analytics

Esempio di codice

Aprire il file e copiare il codice seguente. A questo punto, eseguire il codice.

"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;

//an example document for pii recognition
const documents = [ "The employee's phone number is (555) 555-5555." ];

async function main() {
    console.log(`PII recognition sample`);
  
    const client = new TextAnalyticsClient(endpoint, new AzureKeyCredential(key));
  
    const documents = ["My phone number is 555-555-5555"];
  
    const [result] = await client.analyze("PiiEntityRecognition", documents, "en");
  
    if (!result.error) {
      console.log(`Redacted text: "${result.redactedText}"`);
      console.log("Pii Entities: ");
      for (const entity of result.entities) {
        console.log(`\t- "${entity.text}" of type ${entity.category}`);
      }
    }
}

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

Output

PII recognition sample
Redacted text: "My phone number is ************"
Pii Entities:
        - "555-555-5555" of type PhoneNumber

Documentazione di riferimento | Altri esempi | Pacchetto (PyPi) | Codice sorgente della libreria

Considerare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali con la libreria client per Python. Nell'esempio seguente si creerà un'applicazione Python in grado di identificare le informazioni riservate riconosciute nel 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 Lingua.

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

  2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

    Screenshot che mostra opzioni di funzionalità aggiuntive nel 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 nell'elenco a discesa.
    Gruppo di risorse Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
    Area La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
    Nome Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
    Piano tariffario Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

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

  4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

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

  6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

  1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

    Screenshot che mostra i passaggi successivi alla distribuzione di una risorsa.

  2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

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

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

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

  • Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
  • Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

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

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

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. A questo punto, eseguire il codice.

# 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 sensitive information (PII) from text 
def pii_recognition_example(client):
    documents = [
        "The employee's SSN is 859-98-0987.",
        "The employee's phone number is 555-555-5555."
    ]
    response = client.recognize_pii_entities(documents, language="en")
    result = [doc for doc in response if not doc.is_error]
    for doc in result:
        print("Redacted Text: {}".format(doc.redacted_text))
        for entity in doc.entities:
            print("Entity: {}".format(entity.text))
            print("\tCategory: {}".format(entity.category))
            print("\tConfidence Score: {}".format(entity.confidence_score))
            print("\tOffset: {}".format(entity.offset))
            print("\tLength: {}".format(entity.length))
pii_recognition_example(client)

Output

Redacted Text: The ********'s SSN is ***********.
Entity: employee
        Category: PersonType
        Confidence Score: 0.97
        Offset: 4
        Length: 8
Entity: 859-98-0987
        Category: USSocialSecurityNumber
        Confidence Score: 0.65
        Offset: 22
        Length: 11
Redacted Text: The ********'s phone number is ************.
Entity: employee
        Category: PersonType
        Confidence Score: 0.96
        Offset: 4
        Length: 8
Entity: 555-555-5555
        Category: PhoneNumber
        Confidence Score: 0.8
        Offset: 31
        Length: 12

Documentazione di riferimento

Considerare questa guida introduttiva per inviare richieste di rilevamento delle informazioni personali (PII) usando l'API REST. Nell'esempio seguente si userà cURL per identificare le informazioni riservate riconosciute nel 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 Lingua.

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

  2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

    Screenshot che mostra opzioni di funzionalità aggiuntive nel 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 nell'elenco a discesa.
    Gruppo di risorse Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
    Area La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
    Nome Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
    Piano tariffario Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

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

  4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

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

  6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

  1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

    Screenshot che mostra i passaggi successivi alla distribuzione di una risorsa.

  2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

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

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

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

  • Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
  • Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

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

Dopo aver aggiunto le variabili di ambiente, potrebbe essere necessario riavviare tutti i programmi in esecuzione che dovranno leggerle, 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_pii_payload.json e copiare l'esempio JSON seguente. Questa richiesta di esempio verrà inviata all'API nel passaggio successivo.

{
    "kind": "PiiEntityRecognition",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "language": "en",
                "text": "Call our office at 312-555-1234, or send an email to support@contoso.com"
            }
        ]
    }
}
'

Salvare test_pii_payload.json da qualche parte nel computer. Ad esempio, sul desktop.

Inviare una richiesta API di rilevamento delle informazioni personali

Usare i comandi seguenti per inviare la richiesta API tramite 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_pii_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=2022-05-01" ^
-H "Content-Type: application/json" ^
-H "Ocp-Apim-Subscription-Key: %LANGUAGE_KEY%" ^
-d "@C:\Users\<myaccount>\Desktop\test_pii_payload.json"

PowerShell

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

Risposta JSON

{
	"kind": "PiiEntityRecognitionResults",
	"results": {
		"documents": [{
			"redactedText": "Call our office at ************, or send an email to *******************",
			"id": "1",
			"entities": [{
				"text": "312-555-1234",
				"category": "PhoneNumber",
				"offset": 19,
				"length": 12,
				"confidenceScore": 0.8
			}, {
				"text": "support@contoso.com",
				"category": "Email",
				"offset": 53,
				"length": 19,
				"confidenceScore": 0.8
			}],
			"warnings": []
		}],
		"errors": [],
		"modelVersion": "2021-01-15"
	}
}

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è 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