Desarrolle aplicaciones de servicios de Azure AI con Key Vault

  • Artículo

Aprenda a desarrollar aplicaciones de servicios de Azure AI de forma segura mediante Azure Key Vault.

Key Vault reduce el riesgo de que se filtren accidentalmente los secretos, ya que evita almacenar información de seguridad en la aplicación.

Requisitos previos

Nota:

Revise la documentación y los artículos de inicio rápido de servicio de Azure AI que usa para comprender lo siguiente:

  • Las credenciales y otra información que necesitará para enviar llamadas API.
  • Los paquetes y el código que necesitará para ejecutar la aplicación.

Obtenga de las credenciales del recurso de servicios de Azure AI

Antes de agregar la información de credenciales al almacén de claves de Azure, debe recuperarla del recurso de servicios de Azure AI. Por ejemplo, si el servicio necesita una clave y un punto de conexión, los encontrará mediante los siguientes pasos:

  1. Vaya al recurso de Azure en Azure Portal.

  2. En el menú contraíble de la izquierda, seleccione Claves y punto de conexión.

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

Algunas instancias de servicios de Azure AI requieren información diferente para autenticar llamadas API, como una clave y una región. Asegúrese de recuperar esta información antes de continuar.

Agregue las credenciales al almacén de claves

Para que la aplicación recupere y use las credenciales para autenticar las llamadas API, deberá agregarlas a los secretos del almacén de claves.

Repita estos pasos para generar un secreto para cada credencial de recurso necesaria. Por ejemplo, una clave y un punto de conexión. Estos nombres de secretos se usarán más adelante para autenticar la aplicación.

  1. Abra una nueva ventana o pestaña del explorador. Vaya al almacén de claves en Azure Portal.

  2. En el menú contraíble de la izquierda, seleccione Objetos>Secretos.

  3. Seleccione Generar o importar.

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

  4. En la pantalla Crear un secreto, escriba los siguientes valores:

    Nombre Value
    Opciones de carga Manual
    Nombre Un nombre del secreto para la clave o punto de conexión. Por ejemplo: "CognitiveServicesKey" o "CognitiveServicesEndpoint"
    Valor La clave de recurso o el punto de conexión de los servicios de Azure AI.

    Más adelante, la aplicación usará el secreto "Nombre" para acceder de forma segura a "Valor".

  5. Deje las restantes opciones con sus valores predeterminados. Seleccione Crear.

    Sugerencia

    Asegúrese de recordar los nombres que establezca para los secretos, ya que los usará más adelante en la aplicación.

Ahora debería tener secretos con nombre para la información de recursos.

Creación de una variable de entorno para el nombre del almacén de claves

Se recomienda crear una variable de entorno para el nombre del almacén de claves de Azure. La aplicación leerá esta variable de entorno en tiempo de ejecución para recuperar la información de la clave y del punto de conexión.

Para establecer variables de entorno, use uno de los siguientes comandos. KEY_VAULT_NAME por el nombre de la variable de entorno y reemplace Your-Key-Vault-Name por el nombre del almacén de claves, que se almacenará en la variable de entorno.

Cree y asigne una variable de entorno persistente según el valor.

setx KEY_VAULT_NAME "Your-Key-Vault-Name"

En una nueva instancia del símbolo del sistema, lea la variable de entorno.

echo %KEY_VAULT_NAME%

Autenticación en Azure mediante Visual Studio

Los desarrolladores que usan Visual Studio 2017 o posterior pueden autenticar una cuenta de Microsoft Entra a través de Visual Studio. Esto le permite acceder a los secretos del almacén de claves al iniciar sesión en la suscripción de Azure desde el IDE.

Para autenticarse en Visual Studio, seleccione Herramientas en el menú de navegación superior y seleccione Opciones. Vaya a la opción Autenticación de servicio de Azure para iniciar sesión con el nombre de usuario y la contraseña.

Autenticación mediante la línea de comandos

Para poder conceder acceso al almacén de claves, debe autenticarse con el nombre de usuario y la contraseña de Microsoft Entra.

Para autenticarse con los usuarios de la CLI de Azure, ejecute el comando az login.

az login

En los sistemas con un explorador web predeterminado, la CLI de Azure iniciará el explorador para hacer la autenticación. En el caso de los sistemas sin un explorador web predeterminado, el comando az login usará el flujo de autenticación de código del dispositivo. También puede forzar que la CLI de Azure use el flujo de código del dispositivo en lugar de iniciar un explorador especificando el argumento --use-device-code.

Si tiene varias suscripciones, asegúrese de seleccionar la suscripción de Azure que contenga el almacén de claves.

Concesión de acceso al almacén de claves

Cree una directiva de acceso para el almacén de claves que conceda permisos mediante secreto a la cuenta de usuario.

Para establecer la directiva de acceso, ejecute el comando az keyvault set-policy. Reemplace Your-Key-Vault-Name por el nombre del almacén de claves. Reemplace user@domain.com por su nombre de usuario de Microsoft Entra.

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

Creación de una aplicación de C#

Utilice el IDE de Visual Studio para crear una aplicación de consola de .NET Core. Así se creará un proyecto "Hola mundo" con un solo archivo de origen de C#: program.cs.

Instale las siguientes bibliotecas de cliente, para lo que debe hacer clic con el botón derecho en la solución en el Explorador de soluciones y seleccionar Administrar paquetes NuGet. En el administrador de paquetes que se abre, seleccione Examinar y busque las siguientes bibliotecas y seleccione Instalar para cada una:

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

Importación del código de ejemplo

Copie el siguiente código de ejemplo en su archivo program.cs. Reemplace Your-Key-Secret-Name y Your-Endpoint-Secret-Name por los nombres de secretos que establezca en el almacén de claves.

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

        }
    }
}

Ejecutar la aplicación

Ejecute la aplicación al hacer clic en el botón Depurar en la parte superior de la ventana de VIsual Studio. Los secretos de la clave y del punto de conexión se recuperarán del almacén de claves.

Envío de una llamada de servicio de lenguaje de prueba (opcional)

Si usa un recurso de varios servicios o de lenguaje, puede actualizar la aplicación al seguir estos pasos con el fin de enviar una llamada de Reconocimiento de entidades con nombre de ejemplo mediante la recuperación de una clave y un punto de conexión desde el almacén de claves.

  1. Instale la biblioteca Azure.AI.TextAnalytics, para lo que debe hacer clic con el botón derecho en la solución en el Explorador de soluciones y seleccionar Administrar paquetes NuGet. En el administrador de paquetes que se abre, seleccione Examinar y busque las siguientes bibliotecas y seleccione Instalar para cada una:

  2. Agregue la siguiente directiva al principio del archivo program.cs.

    using Azure.AI.TextAnalytics;

  3. Agregue el siguiente código de ejemplo a la aplicación.

    // 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. Agregue el código siguiente para llamar a EntityRecognitionExample() desde el método principal, con los valores de clave y punto de conexión.

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

  5. Ejecute la aplicación.

Autenticación de la aplicación

Para poder conceder acceso al almacén de claves, debe autenticarse con el nombre de usuario y la contraseña de Microsoft Entra.

Para autenticarse con los usuarios de la CLI de Azure, ejecute el comando az login.

az login

En los sistemas con un explorador web predeterminado, la CLI de Azure iniciará el explorador para hacer la autenticación. En el caso de los sistemas sin un explorador web predeterminado, el comando az login usará el flujo de autenticación de código del dispositivo. También puede forzar que la CLI de Azure use el flujo de código del dispositivo en lugar de iniciar un explorador especificando el argumento --use-device-code.

Si tiene varias suscripciones, asegúrese de seleccionar la suscripción de Azure que contenga el almacén de claves.

Concesión de acceso al almacén de claves

Cree una directiva de acceso para el almacén de claves que conceda permisos mediante secreto a la cuenta de usuario.

Para establecer la directiva de acceso, ejecute el comando az keyvault set-policy. Reemplace Your-Key-Vault-Name por el nombre del almacén de claves. Reemplace user@domain.com por su nombre de usuario de Microsoft Entra.

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

Creación de una aplicación de Python

Cree una carpeta nueva denominada keyVaultExample. A continuación, use el editor de código preferido para crear un archivo denominado program.py dentro de la carpeta recién creada.

Instalación de paquetes de servicio de lenguaje y Key Vault

  1. En un terminal o símbolo del sistema, vaya a la carpeta del proyecto e instale la biblioteca de identidades de Microsoft Entra:

    pip install azure-identity

  2. Instale la biblioteca de secretos de Key Vault:

    pip install azure-keyvault-secrets

Importación del código de ejemplo

Agregue el siguiente código de ejemplo al archivo denominado program.py. Reemplace Your-Key-Secret-Name y Your-Endpoint-Secret-Name por los nombres de secretos que establezca en el almacén de claves.

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

Ejecutar la aplicación

Use el siguiente comando para ejecutar la aplicación. Los secretos de la clave y del punto de conexión se recuperarán del almacén de claves.

python ./program.py

Envío de una llamada de servicio de lenguaje de prueba (opcional)

Si usa un recurso de varios servicios o de lenguaje, puede actualizar la aplicación al seguir estos pasos con el fin de enviar una llamada de Reconocimiento de entidades con nombre de ejemplo mediante la recuperación de una clave y un punto de conexión desde el almacén de claves.

  1. Instalación de una biblioteca de servicio de lenguaje:

    pip install azure-ai-textanalytics==5.1.0

  2. Agregue el siguiente código a la aplicación

    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. Ejecute la aplicación.

Autenticación de la aplicación

Para poder conceder acceso al almacén de claves, debe autenticarse con el nombre de usuario y la contraseña de Microsoft Entra.

Para autenticarse con los usuarios de la CLI de Azure, ejecute el comando az login.

az login

En los sistemas con un explorador web predeterminado, la CLI de Azure iniciará el explorador para hacer la autenticación. En el caso de los sistemas sin un explorador web predeterminado, el comando az login usará el flujo de autenticación de código del dispositivo. También puede forzar que la CLI de Azure use el flujo de código del dispositivo en lugar de iniciar un explorador especificando el argumento --use-device-code.

Si tiene varias suscripciones, asegúrese de seleccionar la suscripción de Azure que contenga el almacén de claves.

Concesión de acceso al almacén de claves

Cree una directiva de acceso para el almacén de claves que conceda permisos mediante secreto a la cuenta de usuario.

Para establecer la directiva de acceso, ejecute el comando az keyvault set-policy. Reemplace Your-Key-Vault-Name por el nombre del almacén de claves. Reemplace user@domain.com por su nombre de usuario de Microsoft Entra.

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

Creación de una aplicación Java

En el IDE preferido, cree un nuevo proyecto de aplicación de la consola Java y cree una clase denominada Example.

Adición de dependencias

En el proyecto, agregue las siguientes dependencias al archivo 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>

Importación del código de ejemplo

Copie el código siguiente en un archivo denominado Example.java. Reemplace Your-Key-Secret-Name y Your-Endpoint-Secret-Name por los nombres de secretos que establezca en el almacén de claves.

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

Envío de una llamada de servicio de lenguaje de prueba (opcional)

Si usa un recurso de varios servicios o de lenguaje, puede actualizar la aplicación al seguir estos pasos con el fin de enviar una llamada de Reconocimiento de entidades con nombre de ejemplo mediante la recuperación de una clave y un punto de conexión desde el almacén de claves.

  1. En la aplicación, agregue la dependencia siguiente:

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

  2. agregue las siguientes instrucciones de importación al archivo.

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

  3. Agregue el siguiente código al método main() en la aplicación:

    
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. Ejecución de la aplicación

Autenticación de la aplicación

Para poder conceder acceso al almacén de claves, debe autenticarse con el nombre de usuario y la contraseña de Microsoft Entra.

Para autenticarse con los usuarios de la CLI de Azure, ejecute el comando az login.

az login

En los sistemas con un explorador web predeterminado, la CLI de Azure iniciará el explorador para hacer la autenticación. En el caso de los sistemas sin un explorador web predeterminado, el comando az login usará el flujo de autenticación de código del dispositivo. También puede forzar que la CLI de Azure use el flujo de código del dispositivo en lugar de iniciar un explorador especificando el argumento --use-device-code.

Si tiene varias suscripciones, asegúrese de seleccionar la suscripción de Azure que contenga el almacén de claves.

Concesión de acceso al almacén de claves

Cree una directiva de acceso para el almacén de claves que conceda permisos mediante secreto a la cuenta de usuario.

Para establecer la directiva de acceso, ejecute el comando az keyvault set-policy. Reemplace Your-Key-Vault-Name por el nombre del almacén de claves. Reemplace user@domain.com por su nombre de usuario de Microsoft Entra.

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

Creación de una aplicación Node.js

Cree una aplicación Node.js que use el almacén de claves.

En un terminal, cree una carpeta con el nombre key-vault-js-example y cámbiela a esa carpeta:

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

Inicialice el proyecto de Node.js:

npm init -y

Instalación de paquetes de servicio de lenguaje y Key Vault

  1. Con el terminal, instale la biblioteca de secretos de Azure Key Vault, @azure/keyvault-secrets para Node.js.

    npm install @azure/keyvault-secrets

  2. Instale la biblioteca de identidades de Azure, @azure/identity para autenticarse en un almacén de claves.

    npm install @azure/identity

Importación del ejemplo de código

Agregue el siguiente código de ejemplo al archivo denominado index.js. Reemplace Your-Key-Secret-Name y Your-Endpoint-Secret-Name por los nombres de secretos que establezca en el almacén de claves.

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

Ejecutar la aplicación de ejemplo

Use el siguiente comando para ejecutar la aplicación. Los secretos de la clave y del punto de conexión se recuperarán del almacén de claves.

node index.js

Envío de una llamada de servicio de lenguaje de prueba (opcional)

Si usa un recurso de varios servicios o de lenguaje, puede actualizar la aplicación al seguir estos pasos con el fin de enviar una llamada de Reconocimiento de entidades con nombre de ejemplo mediante la recuperación de una clave y un punto de conexión desde el almacén de claves.

  1. Instale la biblioteca de lenguaje de servicios de Azure AI, @azure/ai-text-analytics para enviar solicitudes de API al servicio del lenguaje.

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

  2. Agregue el siguiente código a su aplicación:

    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. Ejecute la aplicación.

Pasos siguientes