Guida introduttiva: Rilevare informazioni personali

  • 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 How to detect and redact PII in conversations (Come rilevare e redigire informazioni personali nelle conversazioni).

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

Usare 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

  • 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.
    • Sarà necessaria la chiave e l'endpoint dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È 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. Verrà 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.

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 Example
{
    class Program
    {
        private static readonly AzureKeyCredential credentials = new AzureKeyCredential("replace-with-your-key-here");
        private static readonly Uri endpoint = new Uri("replace-with-your-endpoint-here");

        // 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 | Pacchetto di esempi aggiuntivi | (Maven) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali (PII) con la libreria client per Java. Nell'esempio seguente si creerà 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

  • 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.
    • Sarà necessaria la chiave e l'endpoint dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È 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.

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 {

    private static String KEY = "replace-with-your-key-here";
    private static String ENDPOINT = "replace-with-your-endpoint-here";

    public static void main(String[] args) {
        TextAnalyticsClient client = authenticateClient(KEY, ENDPOINT);
        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 | Pacchetto di esempi aggiuntivi | (npm) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali (PII) con la libreria client per Node.js. Nell'esempio seguente si creerà un'applicazione JavaScript 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

  • 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.
    • sarà necessaria la chiave e l'endpoint dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È 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-text-analytics

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.

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");
const key = '<paste-your-key-here>';
const endpoint = '<paste-your-endpoint-here>';

//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 | Codice sorgente del pacchetto di esempi aggiuntivi | (PyPi)Library |

Usare questa guida introduttiva per creare un'applicazione di rilevamento delle informazioni personali (PII) con la libreria client per Python. Nell'esempio seguente si creerà un'applicazione Python 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

  • 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.
    • Sarà necessaria la chiave e l'endpoint dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È 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.

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.

key = "paste-your-key-here"
endpoint = "paste-your-endpoint-here"

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(key)
    text_analytics_client = TextAnalyticsClient(
            endpoint=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

Usare questa guida introduttiva per inviare richieste di rilevamento delle informazioni personali usando l'API REST. Nell'esempio seguente si userà cURL per 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

  • La versione corrente di cURL.
  • 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.
    • Sarà necessaria la chiave e l'endpoint dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È 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.

Nota

  • Negli esempi BASH seguenti viene usato il carattere di continuazione riga \. Se la console o il terminale usa un carattere di continuazione riga diverso, usare questo carattere.
  • È possibile trovare esempi specifici del linguaggio in GitHub.
  • Passare al portale di Azure e trovare la chiave e l'endpoint per la risorsa Lingua creata nei prerequisiti. Si trovano nella pagina Chiave ed endpoint della risorsa, in Gestione risorse. Sostituire quindi le stringhe nel codice seguente con la chiave e l'endpoint. Per chiamare l'API, sono necessarie le informazioni seguenti:
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.

I comandi cURL seguenti vengono eseguiti da una shell BASH. Modificare questi comandi con il nome e la chiave della risorsa e con i valori del file JSON.

Rilevamento delle informazioni personali

  1. Copiare il comando in un editor di testo.
  2. Apportare le modifiche seguenti nel comando, se necessario:
    1. Sostituire il valore <your-language-resource-key> con la propria chiave.
    2. Sostituire la prima parte dell'URL <your-language-resource-endpoint> della richiesta con l'URL dell'endpoint.
  3. Aprire una finestra del prompt dei comandi.
  4. Incollare il comando dall'editor di testo nella finestra del prompt dei comandi e quindi eseguire il comando.
curl -i -X POST https://<your-language-resource-endpoint>/language/:analyze-text?api-version=2022-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key:<your-language-resource-key>" \
-d \
'
{
    "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"
            }
        ]
    }
}
'

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