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 o risco de que segredos possam ser vazados acidentalmente, porque você evita armazenar informações de segurança em seu aplicativo.

Pré-requisitos

Nota

Reveja a documentação e os artigos de início rápido do serviço de IA do Azure que está a utilizar para compreender sobre:

  • As credenciais e outras informações necessárias para enviar chamadas de API.
  • Os pacotes e o código que você precisará para executar seu aplicativo.

Obtenha suas credenciais do recurso de serviços de IA do Azure

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

  1. Navegue até seu recurso do Azure no portal do Azure.

  2. No menu dobrável à esquerda, selecione Teclas 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 uma chave e uma região. Certifique-se de recuperar essas informações antes de continuar.

Adicione as suas credenciais ao cofre de chaves

Para que seu aplicativo recupere e use suas credenciais para autenticar chamadas de API, você precisará adicioná-las aos segredos do cofre de chaves.

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

  1. Abra uma nova guia ou janela do navegador. Navegue até o cofre da chave no portal do Azure.

  2. No menu dobrável à esquerda, selecione Segredos de objetos>.

  3. Selecione Gerar/Importar.

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

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

    Nome Valor
    Opções de carregamento Manual
    Nome Um nome secreto para sua chave ou ponto de extremidade. Por exemplo: "CognitiveServicesKey" ou "CognitiveServicesEndpoint"
    Value Sua chave de recurso ou ponto de extremidade dos serviços de IA do Azure.

    Mais tarde, a sua aplicação utilizará o "Nome" secreto para aceder com segurança ao "Valor".

  5. Deixe os outros valores como padrão. Selecione Criar.

    Gorjeta

    Lembre-se dos nomes que você definiu para seus segredos, pois você os usará mais tarde em seu aplicativo.

Agora você deve ter nomeado segredos para suas informações de recurso.

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

Recomendamos a criação de uma variável de ambiente para o nome do seu cofre de chaves do Azure. Seu aplicativo lerá essa variável de ambiente em tempo de execução para recuperar suas informações de chave e ponto final.

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

Crie e atribua variável de ambiente persistente, dado 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 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 que você acesse segredos em seu cofre de chaves entrando em sua assinatura do Azure de dentro do IDE.

Para autenticar no Visual Studio, selecione Ferramentas no menu de navegação superior e selecione Opções. Navegue até a opção Autenticação de Serviço do Azure para entrar com seu nome de usuário e senha.

Autenticar usando a linha de comando

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

Para autenticar com a CLI do Azure, execute o az login comando.

az login

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

Se tiver várias subscrições, certifique-se de que seleciona a subscrição do Azure que contém o seu cofre de chaves.

Conceder acesso ao seu cofre de chaves

Crie uma política de acesso para o cofre de chaves que conceda permissões secretas à sua conta de utilizador.

Para definir 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 seu 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 C#

Com o IDE do Visual Studio, crie uma nova aplicação de consola .NET Core. Isso criará um projeto "Hello World" com um único arquivo de origem C#: program.cs.

Instale as seguintes bibliotecas de cliente 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 aberto, selecione Procurar e procure as seguintes bibliotecas e selecione Instalar para cada uma:

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

Importar o código de exemplo

Copie o código de exemplo a seguir para o program.cs arquivo. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes secretos que definiu 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 a aplicação

Execute o aplicativo selecionando o botão Depurar na parte superior do Visual Studio. Os segredos da sua chave e do ponto final serão recuperados do seu cofre de chaves.

Enviar uma chamada de serviço de idioma de teste (opcional)

Se você estiver usando um recurso multisserviço ou um recurso de idioma, poderá atualizar seu aplicativo seguindo estas etapas para enviar um exemplo de chamada de Reconhecimento de Entidade Nomeada recuperando uma chave e um ponto de extremidade do seu cofre de chaves.

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

  2. Adicione a seguinte diretiva à parte superior do ficheiro program.cs .

    using Azure.AI.TextAnalytics;

  3. Adicione o exemplo de código a seguir ao seu 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 seguinte código para chamar EntityRecognitionExample() a partir do seu método principal, com os seus valores de chave e ponto final.

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

  5. Execute a aplicação.

Autenticar a sua aplicação

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

Para autenticar com a CLI do Azure, execute o az login comando.

az login

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

Se tiver várias subscrições, certifique-se de que seleciona a subscrição do Azure que contém o seu cofre de chaves.

Conceder acesso ao seu cofre de chaves

Crie uma política de acesso para o cofre de chaves que conceda permissões secretas à sua conta de utilizador.

Para definir 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 seu 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 uma aplicação Python

Crie uma nova pasta com o nome keyVaultExample. Em seguida, use seu editor de código preferido para criar um arquivo nomeado program.py dentro da pasta recém-criada.

Instalar pacotes de serviço Key Vault e 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 exemplo de código a seguir ao arquivo chamado program.py. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes secretos que definiu 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 a aplicação

Use o seguinte comando para executar o aplicativo. Os segredos da sua chave e do ponto final serão recuperados do seu cofre de chaves.

python ./program.py

Enviar uma chamada de serviço de idioma de teste (opcional)

Se você estiver usando um recurso multisserviço ou um recurso de idioma, poderá atualizar seu aplicativo seguindo estas etapas para enviar um exemplo de chamada de Reconhecimento de Entidade Nomeada recuperando uma chave e um ponto de extremidade do seu cofre de chaves.

  1. Instale a biblioteca do serviço de idiomas:

    pip install azure-ai-textanalytics==5.1.0

  2. Adicione o seguinte código ao seu 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. Execute a aplicação.

Autenticar a sua aplicação

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

Para autenticar com a CLI do Azure, execute o az login comando.

az login

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

Se tiver várias subscrições, certifique-se de que seleciona a subscrição do Azure que contém o seu cofre de chaves.

Conceder acesso ao seu cofre de chaves

Crie uma política de acesso para o cofre de chaves que conceda permissões secretas à sua conta de utilizador.

Para definir 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 seu 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 uma aplicação java

No seu IDE preferido, crie um novo projeto de aplicativo de console Java e crie uma classe chamada Example.

Adicionar dependências

Em seu projeto, adicione as seguintes dependências ao seu pom.xml arquivo.

<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

Copie o código a seguir em um arquivo chamado Example.java. Substitua Your-Key-Secret-Name e Your-Endpoint-Secret-Name pelos nomes secretos que definiu 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 serviço de idioma de teste (opcional)

Se você estiver usando um recurso multisserviço ou um recurso de idioma, poderá atualizar seu aplicativo seguindo estas etapas para enviar um exemplo de chamada de Reconhecimento de Entidade Nomeada recuperando uma chave e um ponto de extremidade do seu cofre de chaves.

  1. Em seu 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 seguintes instruções de importação ao seu 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 main() método em seu 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. Executar a aplicação

Autenticar a sua aplicação

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

Para autenticar com a CLI do Azure, execute o az login comando.

az login

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

Se tiver várias subscrições, certifique-se de que seleciona a subscrição do Azure que contém o seu cofre de chaves.

Conceder acesso ao seu cofre de chaves

Crie uma política de acesso para o cofre de chaves que conceda permissões secretas à sua conta de utilizador.

Para definir 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 seu 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 uma nova aplicação Node.js

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

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

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

Inicialize o projeto Node.js:

npm init -y

Instalar pacotes de serviço Key Vault e 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 de Identidades do Azure, @azure/pacote de identidade para autenticar em um Cofre de Chaves.

    npm install @azure/identity

Importar o exemplo de código

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 secretos que definiu 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 exemplo de aplicação

Use o seguinte comando para executar o aplicativo. Os segredos da sua chave e do ponto final serão recuperados do seu cofre de chaves.

node index.js

Enviar uma chamada de serviço de idioma de teste (opcional)

Se você estiver usando um recurso multisserviço ou um recurso de idioma, poderá atualizar seu aplicativo seguindo estas etapas para enviar um exemplo de chamada de Reconhecimento de Entidade Nomeada recuperando uma chave e um ponto de extremidade do seu cofre de chaves.

  1. Instale o serviço Azure AI para biblioteca de idiomas, @azure/ai-text-analytics para enviar solicitações de API para o serviço de idiomas.

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

  2. Adicione o seguinte código ao seu aplicativo:

    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. Execute a aplicação.

Próximos passos