Sviluppare applicazioni di Servizi di Azure AI con Azure Key Vault

• Una sottoscrizione di Azure valida: crearne una gratuitamente.
• IDE di Visual Studio
• Azure Key Vault
• Risorsa di Servizi di Azure AI

• Una sottoscrizione di Azure valida: crearne una gratuitamente.
• Python 3.7 o versioni successive
• Interfaccia della riga di comando di Azure o Azure PowerShell
• Azure Key Vault
• Risorsa di Servizi di Azure AI

• Una sottoscrizione di Azure valida: crearne una gratuitamente.
• Java Development Kit (JDK) versione 8 o successiva
• Interfaccia della riga di comando di Azure o Azure PowerShell
• Azure Key Vault
• Risorsa di Servizi di Azure AI

• Una sottoscrizione di Azure valida: crearne una gratuitamente.
• Node.js v14 LTS corrente o versioni successive
• Interfaccia della riga di comando di Azure o Azure PowerShell
• Azure Key Vault
• Risorsa di Servizi di Azure AI

Eseguire l'autenticazione in Azure tramite Visual Studio

Gli sviluppatori che usano Visual Studio 2017 o versioni successive possono eseguire l'autenticazione di un account Microsoft Entra tramite Visual Studio. In questo modo è possibile accedere ai segreti nell'insieme di credenziali delle chiavi accedendo alla sottoscrizione di Azure nell'IDE.

Per eseguire l'autenticazione in Visual Studio, selezionare Strumenti dal menu di navigazione in alto, e quindi Opzioni. Passare all'opzione Autenticazione servizi di Azure per accedere con il nome utente e la password.

Eseguire l'autenticazione tramite la riga di comando

Prima di poter concedere l'accesso all'insieme di credenziali delle chiavi, è necessario eseguire l'autenticazione con il nome utente e la password di Microsoft Entra.

az login

Connect-AzAccount

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare un criterio di accesso per l'insieme di credenziali delle chiavi che concede le autorizzazioni per il segreto all'account utente.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Set-AzKeyVaultAccessPolicy -VaultName 'Your-Key-Vault-Name' -UserPrincipalName 'user@domain.com' -PermissionsToSecrets delete,get,list,set,purge -PassThru

Creare una nuova applicazione C#

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 le seguenti librerie client facendo clic con il pulsante destro del mouse sulla soluzione in Esplora soluzioni e scegliendo Gestisci pacchetti NuGet. Nella gestione pacchetti visualizzata, selezionare Sfoglia e cercare le seguenti librerie, quindi selezionare Installa per ognuna di esse:

• Azure.Security.KeyVault.Secrets
• Azure.Identity

Importare il codice di esempio

Copiare il seguente codice di esempio nel file program.cs. Sostituire Your-Key-Secret-Name e Your-Endpoint-Secret-Name con i nomi dei segreti impostati nell'insieme di credenziali delle chiavi.

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using System.Net;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            //Name of your key vault
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");

            //variables for retrieving the key and endpoint from your key vault.
            //Set these variables to the names you created for your secrets
            const string keySecretName = "Your-Key-Secret-Name";
            const string endpointSecretName = "Your-Endpoint-Secret-Name";

            //Endpoint for accessing your key vault
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var keyVaultClient = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.WriteLine($"Retrieving your secrets from {keyVaultName}.");

            //Key and endpoint secrets retrieved from your key vault
            var keySecret = await keyVaultClient.GetSecretAsync(keySecretName);
            var endpointSecret = await keyVaultClient.GetSecretAsync(endpointSecretName);
            Console.WriteLine($"Your key secret value is: {keySecret.Value.Value}");
            Console.WriteLine($"Your endpoint secret value is: {endpointSecret.Value.Value}");
            Console.WriteLine("Secrets retrieved successfully");

        }
    }
}

Eseguire l'applicazione

Eseguire l'applicazione selezionando il pulsante Debug nella parte superiore di Visual Studio. I segreti della chiave e dell'endpoint verranno recuperati dall'insieme di credenziali delle chiavi.

Inviare una chiamata di test al servizio di linguaggio (facoltativo)

Se si usa una risorsa multiservizio o una risorsa linguistica, è possibile aggiornare l'applicazione seguendo questa procedura per inviare un esempio di chiamata di Riconoscimento entità denominata recuperando una chiave e un endpoint dall'insieme di credenziali delle chiavi.

1. Installare la libreria Azure.AI.TextAnalytics facendo clic con il pulsante destro del mouse sulla soluzione in Esplora soluzioni e scegliendo Gestisci pacchetti NuGet. Nella gestione pacchetti visualizzata, selezionare Sfoglia e cercare le seguenti librerie, quindi selezionare Installa per ognuna di esse:

2. Aggiungere la seguente direttiva all'inizio del file program.cs.

   using Azure.AI.TextAnalytics;
   

3. Aggiungere il seguente esempio di codice all'applicazione.

   // Example method for extracting named entities from text 
   private static void EntityRecognitionExample(string keySecret, string endpointSecret)
   {
       //String to be sent for Named Entity Recognition
       var exampleString = "I had a wonderful trip to Seattle last week.";
   
       AzureKeyCredential azureKeyCredential = new AzureKeyCredential(keySecret);
       Uri endpoint = new Uri(endpointSecret);
       var languageServiceClient = new TextAnalyticsClient(endpoint, azureKeyCredential);
   
       Console.WriteLine($"Sending a Named Entity Recognition (NER) request");
       var response = languageServiceClient.RecognizeEntities(exampleString);
       Console.WriteLine("Named Entities:");
       foreach (var entity in response.Value)
       {
           Console.WriteLine($"\tText: {entity.Text},\tCategory: {entity.Category},\tSub-Category: {entity.SubCategory}");
           Console.WriteLine($"\t\tScore: {entity.ConfidenceScore:F2},\tLength: {entity.Length},\tOffset: {entity.Offset}\n");
       }
   }
   

4. Aggiungere il seguente codice per chiamare EntityRecognitionExample() dal metodo principale con i valori della chiave e dell'endpoint.

   EntityRecognitionExample(keySecret.Value.Value, endpointSecret.Value.Value);
   

5. Eseguire l'applicazione.

Autenticare l'applicazione

Prima di poter concedere l'accesso all'insieme di credenziali delle chiavi, è necessario eseguire l'autenticazione con il nome utente e la password di Microsoft Entra.

az login

Connect-AzAccount

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare un criterio di accesso per l'insieme di credenziali delle chiavi che concede le autorizzazioni per il segreto all'account utente.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Set-AzKeyVaultAccessPolicy -VaultName 'Your-Key-Vault-Name' -UserPrincipalName 'user@domain.com' -PermissionsToSecrets delete,get,list,set,purge -PassThru

Creare un'applicazione Python

Creare una nuova cartella denominata keyVaultExample, Usare quindi l'editor di codice preferito per creare un file denominato program.py all'interno della cartella appena creata.

Installare i pacchetti di Key Vault e del servizio di linguaggio

1. In un terminale o in un prompt dei comandi, passare alla cartella del progetto e installare la libreria di identità di Microsoft Entra:

   pip install azure-identity
   

2. Installare la libreria di segreti di Key Vault:

   pip install azure-keyvault-secrets
   

Importare il codice di esempio

Aggiungere il seguente codice di esempio al file denominato program.py. Sostituire Your-Key-Secret-Name e Your-Endpoint-Secret-Name con i nomi dei segreti impostati nell'insieme di credenziali delle chiavi.

import os
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
from azure.core.credentials import AzureKeyCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]

# Set these variables to the names you created for your secrets
keySecretName = "Your-Key-Secret-Name"
endpointSecretName = "Your-Endpoint-Secret-Name"

# URI for accessing key vault
KVUri = f"https://{keyVaultName}.vault.azure.net"

# Instantiate the client and retrieve secrets
credential = DefaultAzureCredential()
kv_client = SecretClient(vault_url=KVUri, credential=credential)

print(f"Retrieving your secrets from {keyVaultName}.")

retrieved_key = kv_client.get_secret(keySecretName).value
retrieved_endpoint = kv_client.get_secret(endpointSecretName).value

print(f"Your secret key value is {retrieved_key}.");
print(f"Your secret endpoint value is {retrieved_endpoint}.");

Eseguire l'applicazione

Usare il seguente comando per eseguire l'applicazione. I segreti della chiave e dell'endpoint verranno recuperati dall'insieme di credenziali delle chiavi.

python ./program.py

Inviare una chiamata di test al servizio di linguaggio (facoltativo)

Se si usa una risorsa multiservizio o una risorsa linguistica, è possibile aggiornare l'applicazione seguendo questa procedura per inviare un esempio di chiamata di Riconoscimento entità denominata recuperando una chiave e un endpoint dall'insieme di credenziali delle chiavi.

1. Installare la libreria del servizio di linguaggio:

   pip install azure-ai-textanalytics==5.1.0
   

2. Aggiungere il codice seguente all'applicazione

   from azure.ai.textanalytics import TextAnalyticsClient
   # Authenticate the key vault secrets client using your key and endpoint 
   azure_key_credential = AzureKeyCredential(retrieved_key)
   # Now you can use key vault credentials with the Language service
   language_service_client = TextAnalyticsClient(
       endpoint=retrieved_endpoint, 
       credential=azure_key_credential)
   
   # Example of recognizing entities from text
   
   print("Sending NER request")
   
   try:
       documents = ["I had a wonderful trip to Seattle last week."]
       result = language_service_client.recognize_entities(documents = documents)[0]
       print("Named Entities:\n")
       for entity in result.entities:
           print("\tText: \t", entity.text, "\tCategory: \t", entity.category, "\tSubCategory: \t", entity.subcategory,
                   "\n\tConfidence Score: \t", round(entity.confidence_score, 2), "\tLength: \t", entity.length, "\tOffset: \t", entity.offset, "\n")
   
   except Exception as err:
       print("Encountered exception. {}".format(err))
   

3. Eseguire l'applicazione.

Autenticare l'applicazione

Prima di poter concedere l'accesso all'insieme di credenziali delle chiavi, è necessario eseguire l'autenticazione con il nome utente e la password di Microsoft Entra.

az login

Connect-AzAccount

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare un criterio di accesso per l'insieme di credenziali delle chiavi che concede le autorizzazioni per il segreto all'account utente.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Set-AzKeyVaultAccessPolicy -VaultName 'Your-Key-Vault-Name' -UserPrincipalName 'user@domain.com' -PermissionsToSecrets delete,get,list,set,purge -PassThru

Creare un'applicazione Java

Nell'IDE preferito creare un nuovo progetto dell'applicazione console Java e una classe denominata Example.

Aggiungere le dipendenze

Nel progetto, aggiungere le seguenti dipendenze al file pom.xml.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-secrets</artifactId>
        <version>4.2.3</version>
    </dependency>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity</artifactId>
        <version>1.2.0</version>
    </dependency>
</dependencies>

Importare il codice di esempio

Copiare il seguente codice in un file denominato Example.java. Sostituire Your-Key-Secret-Name e Your-Endpoint-Secret-Name con i nomi dei segreti impostati nell'insieme di credenziali delle chiavi.

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.core.credential.AzureKeyCredential;

public class Example {

    public static void main(String[] args) {

        String keyVaultName = System.getenv("KEY_VAULT_NAME");
        String keyVaultUri = "https://" + keyVaultName + ".vault.azure.net";

        //variables for retrieving the key and endpoint from your key vault.
        //Set these variables to the names you created for your secrets
        String keySecretName = "Your-Key-Secret-Name";
        String endpointSecretName = "Your-Endpoint-Secret-Name";

        //Create key vault secrets client
        SecretClient secretClient = new SecretClientBuilder()
                .vaultUrl(keyVaultUri)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();

        //retrieve key and endpoint from key vault
        String keyValue = secretClient.getSecret(keySecretName).getValue();
        String endpointValue = secretClient.getSecret(endpointSecretName).getValue();
        System.out.printf("Your secret key value is: %s", keyValue)
        System.out.printf("Your secret endpoint value is: %s", endpointValue)
    }
}

Inviare una chiamata di test al servizio di linguaggio (facoltativo)

Se si usa una risorsa multiservizio o una risorsa linguistica, è possibile aggiornare l'applicazione seguendo questa procedura per inviare un esempio di chiamata di Riconoscimento entità denominata recuperando una chiave e un endpoint dall'insieme di credenziali delle chiavi.

1. Nell'applicazione, aggiungere la seguente dipendenza:

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

2. Aggiungere le seguenti istruzioni di importazione al file.

   import com.azure.ai.textanalytics.models.*;
   import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
   import com.azure.ai.textanalytics.TextAnalyticsClient;
   

3. Aggiungere il seguente codice al metodo main() nell'applicazione:

   
   TextAnalyticsClient languageClient = new TextAnalyticsClientBuilder()
           .credential(new AzureKeyCredential(keyValue))
           .endpoint(endpointValue)
           .buildClient();
   
   // Example for recognizing entities in text
   String text = "I had a wonderful trip to Seattle last week.";
   
   for (CategorizedEntity entity : languageClient.recognizeEntities(text)) {
       System.out.printf(
               "Recognized entity: %s, entity category: %s, entity sub-category: %s, score: %s, offset: %s, length: %s.%n",
               entity.getText(),
               entity.getCategory(),
               entity.getSubcategory(),
               entity.getConfidenceScore(),
               entity.getOffset(),
               entity.getLength());
   }
   

4. Eseguire l'applicazione

Autenticare l'applicazione

Prima di poter concedere l'accesso all'insieme di credenziali delle chiavi, è necessario eseguire l'autenticazione con il nome utente e la password di Microsoft Entra.

az login

Connect-AzAccount

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare un criterio di accesso per l'insieme di credenziali delle chiavi che concede le autorizzazioni per il segreto all'account utente.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Set-AzKeyVaultAccessPolicy -VaultName 'Your-Key-Vault-Name' -UserPrincipalName 'user@domain.com' -PermissionsToSecrets delete,get,list,set,purge -PassThru

Creare una nuova applicazione Node.js

Creare un'applicazione Node.js che usa l'insieme di credenziali delle chiavi.

In un terminale creare una cartella denominata key-vault-js-example e passare a tale cartella:

mkdir key-vault-js-example && cd key-vault-js-example

Inizializzare il progetto Node.js:

npm init -y

Installare i pacchetti di Key Vault e del servizio di linguaggio

1. Usando il terminale, installare la libreria dei segreti di Azure Key Vault, @azure/keyvault-secrets, per Node.js.

   npm install @azure/keyvault-secrets
   

2. Installare il pacchetto @azure/identity della libreria di identità di Azure per eseguire l'autenticazione in Key Vault.

   npm install @azure/identity
   

Importare il codice di esempio

Aggiungere il seguente codice di esempio a un file denominato index.js. Sostituire Your-Key-Secret-Name e Your-Endpoint-Secret-Name con i nomi dei segreti impostati nell'insieme di credenziali delle chiavi.

const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");
// Load the .env file if it exists
const dotenv = require("dotenv");
dotenv.config();

async function main() {
    const credential = new DefaultAzureCredential();

    const keyVaultName = process.env["KEY_VAULT_NAME"];
    const url = "https://" + keyVaultName + ".vault.azure.net";

    const kvClient = new SecretClient(url, credential);

    // Set these variables to the names you created for your secrets
    const keySecretName = "Your-Key-Secret-Name";
    const endpointSecretName = "Your-Endpoint-Secret-Name";

    console.log("Retrieving secrets from ", keyVaultName);
    const retrievedKey = await (await kvClient.getSecret(keySecretName)).value;
    const retrievedEndpoint = await (await kvClient.getSecret(endpointSecretName)).value;
    console.log("Your secret key value is: ", retrievedKey);
    console.log("Your secret endpoint value is: ", retrievedEndpoint);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Eseguire l'applicazione di esempio

Usare il seguente comando per eseguire l'applicazione. I segreti della chiave e dell'endpoint verranno recuperati dall'insieme di credenziali delle chiavi.

node index.js

Inviare una chiamata di test al servizio di linguaggio (facoltativo)

Se si usa una risorsa multiservizio o una risorsa linguistica, è possibile aggiornare l'applicazione seguendo questa procedura per inviare un esempio di chiamata di Riconoscimento entità denominata recuperando una chiave e un endpoint dall'insieme di credenziali delle chiavi.

1. Installare la libreria del Servizio Azure AI per la lingua, @azure/ai-text-analytics, per inviare richieste API al servizio di linguaggio.

   npm install @azure/ai-text-analytics@5.1.0
   

2. Aggiungere il codice seguente all'applicazione:

   const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
   // Authenticate the language client with your key and endpoint
   const languageClient = new TextAnalyticsClient(retrievedEndpoint,  new AzureKeyCredential(retrievedKey));
   
   // Example for recognizing entities in text
   console.log("Sending NER request")
   const entityInputs = [
       "I had a wonderful trip to Seattle last week."
   ];
   const entityResults = await languageClient.recognizeEntities(entityInputs);
   entityResults.forEach(document => {
       console.log(`Document ID: ${document.id}`);
       document.entities.forEach(entity => {
           console.log(`\tName: ${entity.text} \tCategory: ${entity.category} \tSubcategory: ${entity.subCategory ? entity.subCategory : "N/A"}`);
           console.log(`\tScore: ${entity.confidenceScore}`);
       });
   });
   

3. Eseguire l'applicazione.