Desenvolver aplicativos de serviços de IA do Azure com o Key Vault

  • Artigo

Saiba como desenvolver aplicativos de serviços de IA do Azure com segurança usando o Azure Key Vault.

O Key Vault reduz os riscos de vazamento acidental de segredos, pois você evita armazenar informações de segurança em seu aplicativo.

Pré-requisitos

Observação

Examine a documentação e os artigos de início rápido do serviço de IA do Azure que você está usando para entender melhor:

  • As credenciais e outras informações necessárias para enviar chamadas de API.
  • Os pacotes e códigos necessários para executar o aplicativo.

Obter credenciais do recurso de serviços de IA do Azure

Antes de adicionar suas informações de credenciais ao Azure Key Vault, você precisa recuperá-las do recurso de serviços de IA do Azure. Por exemplo, se seu serviço precisar de uma chave e de um ponto de extremidade, você os encontrará seguindo estas etapas:

  1. Acesse o recurso do Azuro no portal do Azure.

  2. No menu recolhível à esquerda, selecione Chaves e ponto de extremidade.

    A screenshot showing the key and endpoint page in the Azure portal.

Alguns serviços de IA do Azure exigem informações diferentes para autenticar chamadas de API, como chave e região. Recupere essas informações antes de continuar.

Adicionar credenciais ao cofre de chaves

Para que o aplicativo recupere e use suas credenciais a fim de autenticar chamadas de API, é necessário adicioná-las aos segredos do cofre de chaves.

Repita essas etapas a fim de gerar um segredo para cada credencial de recurso necessária. Por exemplo, uma chave e um ponto de extremidade. Esses nomes de segredos serão usados ​​posteriormente para autenticar o aplicativo.

  1. Abra uma guia ou janela do navegador. Acesse o cofre de chaves em Portal do Azure.

  2. No menu recolhível à esquerda, selecione Objetos>Segredos.

  3. Selecione Gerar/Importar.

    A screenshot showing the key vault key page in the Azure portal.

  4. Na tela Criar segredo, insira os seguintes valores:

    Name Valor
    Opções de upload Manual
    Nome Um nome de segredo para a chave ou o ponto de extremidade. Por exemplo: "CognitiveServicesKey" ou "CognitiveServicesEndpoint"
    Valor Sua chave de recurso ou ponto de extremidade dos serviços de IA do Azure.

    Mais tarde, o aplicativo usará o "Nome" do segredo para acessar com segurança o "Valor".

  5. Deixe os outros valores com seus padrões. Selecione Criar.

    Dica

    Lembre-se dos nomes que você definiu para os segredos, pois eles serão usados posteriormente no aplicativo.

Agora, você tem segredos nomeados para as informações do recurso.

Criar uma variável de ambiente para o nome do cofre de chaves

Recomenda-se criar uma variável de ambiente para o nome do cofre de chaves do Azure. O aplicativo lerá essa variável de ambiente no runtime para recuperar as informações da chave e do ponto de extremidade.

Para definir variáveis ​​de ambiente, use um dos comandos a seguir. KEY_VAULT_NAME com o nome da variável de ambiente e substitua Your-Key-Vault-Name pelo nome do cofre de chaves, que será armazenado na variável.

Crie e atribua variáveis de ambiente persistentes, considerando o valor.

setx KEY_VAULT_NAME "Your-Key-Vault-Name"

Em uma nova instância do Prompt de comando, leia a variável de ambiente.

echo %KEY_VAULT_NAME%

Autenticar-se no Azure usando o Visual Studio

Os desenvolvedores que usam o Visual Studio 2017 ou posterior podem autenticar uma conta do Microsoft Entra por meio do Visual Studio. Isso permite acessar segredos no cofre de chaves entrando na assinatura do Azure por meio do IDE.

Para realizar a autenticação no Visual Studio, selecione Ferramentas no menu de navegação superior e clique em Opções. Acesse a opção Autenticação do serviço do Azure para entrar com seu nome de usuário e sua senha.

Autenticar-se usando a linha de comando

Antes de conceder acesso ao cofre de chaves, você deve se autenticar com seu nome de usuário e senha do Microsoft Entra.

Para realizar a autenticação com a CLI do Azure, execute o comando az login.

az login

Em sistemas com um navegador da Web padrão, a CLI do Azure iniciará o navegador para a autenticação. Para sistemas sem um navegador da Web padrão, o comando az login usará o fluxo de autenticação de código do dispositivo. Também é possível forçar a CLI do Azure a usar o fluxo de código do dispositivo, em vez de iniciar um navegador, especificando o argumento --use-device-code.

No caso de muitas assinaturas, selecione a assinatura do Azure que contém o cofre de chaves.

Permitir acesso ao cofre de chaves

Criar uma política de acesso para o cofre de chaves que concede permissões de segredo à sua conta de usuário.

Para configurar a política de acesso, execute o comando az keyvault set-policy. Substitua Your-Key-Vault-Name pelo nome do cofre de chaves. Substitua user@domain.com pelo nome de usuário do Microsoft Entra.

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

Criar um aplicativo em C#

Usando o IDE do Visual Studio, crie um aplicativo de console do .NET Core. Isso criará um projeto "Olá, Mundo" com um arquivo de origem C#: program.cs.

Instale as seguintes bibliotecas de clientes clicando com o botão direito do mouse no Gerenciador de Soluções e selecionando Gerenciar pacotes NuGet. No gerenciador de pacotes que é aberto, selecione Procurar, pesquise as seguintes bibliotecas e selecione Instalar para cada uma delas:

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

Importar o código de exemplo

Copie o código de exemplo a seguir em seu arquivo program.cs. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes dos segredos definidos no cofre de chaves.

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

        }
    }
}

Executar o aplicativo

Execute o aplicativo clicando no botão Depurar na parte superior do Visual Studio. Os segredos da chave e do ponto de extremidade serão recuperados do cofre de chaves.

Enviar uma chamada de teste do serviço Language (opcional)

Se você estiver usando um recurso multisserviço ou Language, atualize o aplicativo seguindo estas etapas a fim de enviar uma chamada de Reconhecimento de Entidade Nomeada de exemplo recuperando uma chave e um ponto de extremidade do cofre de chaves.

  1. Instale a biblioteca Azure.AI.TextAnalytics clicando com o botão direito do mouse na solução no Gerenciador de Soluções e selecionando Gerenciar pacotes NuGet. No gerenciador de pacotes que é aberto, selecione Procurar, pesquise as seguintes bibliotecas e selecione Instalar para cada uma delas:

  2. Adicione a diretiva a seguir à parte superior do arquivo program.cs.

    using Azure.AI.TextAnalytics;

  3. Adicione o código de exemplo a seguir ao aplicativo.

    // 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. Adicione o código a seguir para chamar EntityRecognitionExample() por meio do método principal, com seus valores de chave e ponto de extremidade.

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

  5. Executar o aplicativo.

Autenticar o aplicativo

Antes de conceder acesso ao cofre de chaves, você deve se autenticar com seu nome de usuário e senha do Microsoft Entra.

Para realizar a autenticação com a CLI do Azure, execute o comando az login.

az login

Em sistemas com um navegador da Web padrão, a CLI do Azure iniciará o navegador para a autenticação. Para sistemas sem um navegador da Web padrão, o comando az login usará o fluxo de autenticação de código do dispositivo. Também é possível forçar a CLI do Azure a usar o fluxo de código do dispositivo, em vez de iniciar um navegador, especificando o argumento --use-device-code.

No caso de muitas assinaturas, selecione a assinatura do Azure que contém o cofre de chaves.

Permitir acesso ao cofre de chaves

Criar uma política de acesso para o cofre de chaves que concede permissões de segredo à sua conta de usuário.

Para configurar a política de acesso, execute o comando az keyvault set-policy. Substitua Your-Key-Vault-Name pelo nome do cofre de chaves. Substitua user@domain.com pelo nome de usuário do Microsoft Entra.

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

Criar um aplicativo Python

Crie uma pasta chamada keyVaultExample. Em seguida, use seu editor de código preferencial para criar um arquivo chamado program.py na pasta recém-criada.

Instalar os pacotes de serviço do Key Vault e do Language

  1. Em um terminal ou prompt de comando, navegue até a pasta do projeto e instale a biblioteca de identidades do Microsoft Entra:

    pip install azure-identity

  2. Instale a biblioteca de segredos do Key Vault:

    pip install azure-keyvault-secrets

Importar o código de exemplo

Adicione o código de exemplo a seguir ao arquivo program.py. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes dos segredos definidos no cofre de chaves.

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}.");

Executar o aplicativo

Use o comando a seguir para executar o aplicativo. Os segredos da chave e do ponto de extremidade serão recuperados do cofre de chaves.

python ./program.py

Enviar uma chamada de teste do serviço Language (opcional)

Se você estiver usando um recurso multisserviço ou Language, atualize o aplicativo seguindo estas etapas a fim de enviar uma chamada de Reconhecimento de Entidade Nomeada de exemplo recuperando uma chave e um ponto de extremidade do cofre de chaves.

  1. Instale a biblioteca do serviço Language:

    pip install azure-ai-textanalytics==5.1.0

  2. Adicionar o código a seguir ao aplicativo

    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. Executar o aplicativo.

Autenticar o aplicativo

Antes de conceder acesso ao cofre de chaves, você deve se autenticar com seu nome de usuário e senha do Microsoft Entra.

Para realizar a autenticação com a CLI do Azure, execute o comando az login.

az login

Em sistemas com um navegador da Web padrão, a CLI do Azure iniciará o navegador para a autenticação. Para sistemas sem um navegador da Web padrão, o comando az login usará o fluxo de autenticação de código do dispositivo. Também é possível forçar a CLI do Azure a usar o fluxo de código do dispositivo, em vez de iniciar um navegador, especificando o argumento --use-device-code.

No caso de muitas assinaturas, selecione a assinatura do Azure que contém o cofre de chaves.

Permitir acesso ao cofre de chaves

Criar uma política de acesso para o cofre de chaves que concede permissões de segredo à sua conta de usuário.

Para configurar a política de acesso, execute o comando az keyvault set-policy. Substitua Your-Key-Vault-Name pelo nome do cofre de chaves. Substitua user@domain.com pelo nome de usuário do Microsoft Entra.

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

Criar um aplicativo Java

Em seu IDE preferencial, crie um projeto de aplicativo de console Java e uma classe chamada Example.

Adicionar dependências

No projeto, adicione as dependências a seguir ao arquivo 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>

Importar o código de exemplo

Adicione o código a seguir a um arquivo chamado Example.java. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes dos segredos definidos no cofre de chaves.

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

Enviar uma chamada de teste do serviço Language (opcional)

Se você estiver usando um recurso multisserviço ou Language, atualize o aplicativo seguindo estas etapas a fim de enviar uma chamada de Reconhecimento de Entidade Nomeada de exemplo recuperando uma chave e um ponto de extremidade do cofre de chaves.

  1. No aplicativo, adicione a seguinte dependência:

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

  2. adicione as instruções de importação a seguir ao arquivo.

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

  3. Adicione o seguinte código ao método main() no aplicativo:

    
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. Execute seu aplicativo.

Autenticar o aplicativo

Antes de conceder acesso ao cofre de chaves, você deve se autenticar com seu nome de usuário e senha do Microsoft Entra.

Para realizar a autenticação com a CLI do Azure, execute o comando az login.

az login

Em sistemas com um navegador da Web padrão, a CLI do Azure iniciará o navegador para a autenticação. Para sistemas sem um navegador da Web padrão, o comando az login usará o fluxo de autenticação de código do dispositivo. Também é possível forçar a CLI do Azure a usar o fluxo de código do dispositivo, em vez de iniciar um navegador, especificando o argumento --use-device-code.

No caso de muitas assinaturas, selecione a assinatura do Azure que contém o cofre de chaves.

Permitir acesso ao cofre de chaves

Criar uma política de acesso para o cofre de chaves que concede permissões de segredo à sua conta de usuário.

Para configurar a política de acesso, execute o comando az keyvault set-policy. Substitua Your-Key-Vault-Name pelo nome do cofre de chaves. Substitua user@domain.com pelo nome de usuário do Microsoft Entra.

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

Criar um novo aplicativo do Node.js

Crie um aplicativo Node.js que usa seu cofre de chaves.

Em um terminal, crie uma pasta nomeada key-vault-js-example e altere para essa pasta:

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

Inicializar o projeto Node.js:

npm init -y

Instalar os pacotes de serviço do Key Vault e do Language

  1. Usando o terminal, instale a biblioteca de segredos do Azure Key Vault, @azure/keyvault-secrets para Node.js.

    npm install @azure/keyvault-secrets

  2. Instale a biblioteca do Azure Identity, pacote @azure/identity para autenticar em um Key Vault.

    npm install @azure/identity

Importar o código de exemplo

Adicione o exemplo de código a seguir a um arquivo chamado index.js. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes dos segredos definidos no cofre de chaves.

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);
});

Executar o aplicativo de exemplo

Use o comando a seguir para executar o aplicativo. Os segredos da chave e do ponto de extremidade serão recuperados do cofre de chaves.

node index.js

Enviar uma chamada de teste do serviço Language (opcional)

Se você estiver usando um recurso multisserviço ou Language, atualize o aplicativo seguindo estas etapas a fim de enviar uma chamada de Reconhecimento de Entidade Nomeada de exemplo recuperando uma chave e um ponto de extremidade do cofre de chaves.

  1. Instale o serviço de IA do Azure para a biblioteca de linguagem, @azure/ai-text-analytics para enviar solicitações de API para o serviço de linguagem.

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

  2. Adicione o código a seguir à sua página:

    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. Executar o aplicativo.

Próximas etapas