Vývoj aplikací služeb Azure AI pomocí služby Key Vault

Naučte se bezpečně vyvíjet aplikace služeb Azure AI pomocí služby Azure Key Vault.

Key Vault snižuje riziko náhodného úniku tajných kódů, protože se vyhnete ukládání bezpečnostních informací ve vaší aplikaci.

Požadavky

Poznámka:

Projděte si dokumentaci a články rychlého startu pro službu Azure AI, kterou používáte k pochopení těchto informací:

  • Přihlašovací údaje a další informace, které budete potřebovat k odesílání volání rozhraní API.
  • Balíčky a kód, které budete potřebovat ke spuštění aplikace.

Získání přihlašovacích údajů z prostředku služeb Azure AI

Před přidáním přihlašovacích údajů do trezoru klíčů Azure je potřeba je načíst z prostředku služeb Azure AI. Pokud například vaše služba potřebuje klíč a koncový bod, najdete ho pomocí následujícího postupu:

  1. Na webu Azure Portal přejděte k prostředku Azure.

  2. V sbalitelné nabídce vlevo vyberte Klíče a koncový bod.

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

Některé služby Azure AI vyžadují k ověřování volání rozhraní API různé informace, jako je klíč a oblast. Než budete pokračovat, nezapomeňte tyto informace načíst.

Přidání přihlašovacích údajů do trezoru klíčů

Aby vaše aplikace načetla a používala vaše přihlašovací údaje k ověřování volání rozhraní API, budete je muset přidat do tajných kódů trezoru klíčů.

Opakujte tento postup a vygenerujte tajný kód pro každé požadované přihlašovací údaje prostředku. Například klíč a koncový bod. Tyto názvy tajných kódů se později použijí k ověření vaší aplikace.

  1. Otevřete novou kartu nebo okno prohlížeče. Na webu Azure Portal přejděte ke svému trezoru klíčů.

  2. V sbalitelné nabídce vlevo vyberte Tajné kódy> objektů.

  3. Vyberte Generovat/importovat.

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

  4. Na obrazovce Vytvořit tajný kód zadejte následující hodnoty:

    Jméno Hodnota
    Možnosti nahrání Ruční
    Název Název tajného klíče nebo koncového bodu Příklad: CognitiveServicesKey nebo CognitiveServicesEndpoint
    Hodnota Váš klíč prostředku nebo koncový bod služby Azure AI

    Později bude vaše aplikace používat tajný kód Name k bezpečnému přístupu k hodnotě.

  5. U ostatních hodnot ponechte výchozí hodnoty. Vyberte Vytvořit.

    Tip

    Nezapomeňte si zapamatovat názvy, které jste nastavili pro tajné kódy, protože je použijete později v aplikaci.

Teď byste měli mít pojmenované tajné kódy pro informace o prostředcích.

Vytvoření proměnné prostředí pro název trezoru klíčů

Doporučujeme vytvořit proměnnou prostředí pro název trezoru klíčů Azure. Aplikace přečte tuto proměnnou prostředí za běhu, aby načetla informace o klíči a koncovém bodu.

K nastavení proměnných prostředí použijte jeden z následujících příkazů. KEY_VAULT_NAME nahraďte názvem proměnné prostředí a nahraďte Your-Key-Vault-Name názvem vašeho trezoru klíčů, který bude uložen v proměnné prostředí.

Vytvořte a přiřaďte trvalou proměnnou prostředí vzhledem k hodnotě.

setx KEY_VAULT_NAME "Your-Key-Vault-Name"

V nové instanci příkazového řádku načtěte proměnnou prostředí.

echo %KEY_VAULT_NAME%

Ověřování v Azure pomocí sady Visual Studio

Vývojáři používající Visual Studio 2017 nebo novější můžou ověřit účet Microsoft Entra prostřednictvím sady Visual Studio. To umožňuje přístup k tajným kódům ve vašem trezoru klíčů přihlášením k předplatnému Azure z integrovaného vývojového prostředí (IDE).

Pokud se chcete ověřit v sadě Visual Studio, vyberte Nástroje v horní navigační nabídce a vyberte Možnosti. Přejděte na možnost Ověřování služby Azure a přihlaste se pomocí svého uživatelského jména a hesla.

Ověřování pomocí příkazového řádku

Než budete moct udělit přístup k trezoru klíčů, musíte se ověřit pomocí uživatelského jména a hesla Microsoft Entra.

Pokud se chcete ověřit pomocí Azure CLI, spusťte az login příkaz.

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč, který se má ověřit. Pro systémy bez az login výchozího webového prohlížeče použije příkaz tok ověřování kódu zařízení. Azure CLI můžete také vynutit, aby místo spuštění prohlížeče používalo tok kódu zařízení, a to tak --use-device-code , že zadáte argument.

Pokud máte více předplatných, nezapomeňte vybrat předplatné Azure, které obsahuje váš trezor klíčů.

Udělení přístupu k trezoru klíčů

Vytvořte zásadu přístupu pro váš trezor klíčů, která uděluje oprávnění k tajným kódům vašemu uživatelskému účtu.

Pokud chcete nastavit zásady přístupu, spusťte příkaz az keyvault set-policy . Nahraďte Your-Key-Vault-Name názvem trezoru klíčů. Nahraďte user@domain.com svým uživatelským jménem Microsoft Entra.

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

Vytvoření nové aplikace jazyka C#

Pomocí integrovaného vývojového prostředí (IDE) sady Visual Studio vytvořte novou aplikaci konzoly .NET Core. Tím se vytvoří projekt "Hello World" s jedním zdrojovým souborem jazyka C#: program.cs.

Nainstalujte následující klientské knihovny tak, že kliknete pravým tlačítkem na řešení v Průzkumník řešení a vyberete Spravovat balíčky NuGet. Ve správci balíčků, který se otevře, vyberte Procházet a vyhledejte následující knihovny a vyberte Nainstalovat pro každý z nich:

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

Import ukázkového kódu

Zkopírujte do souboru následující ukázkový kód program.cs . Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name nahraďte názvy tajných kódů, které jste nastavili v trezoru klíčů.

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

        }
    }
}

Spuštění aplikace

Spusťte aplikaci výběrem tlačítka Ladit v horní části sady Visual Studio. Tajné kódy vašeho klíče a koncového bodu se načtou z trezoru klíčů.

Odeslání volání služby testovacího jazyka (volitelné)

Pokud používáte prostředek s více službami nebo prostředek jazyka, můžete aplikaci aktualizovat pomocí následujícího postupu a odeslat příklad volání Rozpoznávání pojmenovaných entit načtením klíče a koncového bodu z trezoru klíčů.

  1. Nainstalujte knihovnu Azure.AI.TextAnalytics tak, že kliknete pravým tlačítkem na řešení v Průzkumník řešení a vyberete Spravovat balíčky NuGet. Ve správci balíčků, který se otevře, vyberte Procházet a vyhledejte následující knihovny a vyberte Nainstalovat pro každý z nich:

  2. Na začátek souboru přidejte následující direktivu program.cs .

    using Azure.AI.TextAnalytics;
    
  3. Do aplikace přidejte následující ukázku kódu.

    // 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. Přidejte následující kód pro volání EntityRecognitionExample() z hlavní metody s hodnotami klíče a koncového bodu.

    EntityRecognitionExample(keySecret.Value.Value, endpointSecret.Value.Value);
    
  5. Aplikaci spusťte.

Ověření vaší aplikace

Než budete moct udělit přístup k trezoru klíčů, musíte se ověřit pomocí uživatelského jména a hesla Microsoft Entra.

Pokud se chcete ověřit pomocí Azure CLI, spusťte az login příkaz.

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč, který se má ověřit. Pro systémy bez az login výchozího webového prohlížeče použije příkaz tok ověřování kódu zařízení. Azure CLI můžete také vynutit, aby místo spuštění prohlížeče používalo tok kódu zařízení, a to tak --use-device-code , že zadáte argument.

Pokud máte více předplatných, nezapomeňte vybrat předplatné Azure, které obsahuje váš trezor klíčů.

Udělení přístupu k trezoru klíčů

Vytvořte zásadu přístupu pro váš trezor klíčů, která uděluje oprávnění k tajným kódům vašemu uživatelskému účtu.

Pokud chcete nastavit zásady přístupu, spusťte příkaz az keyvault set-policy . Nahraďte Your-Key-Vault-Name názvem trezoru klíčů. Nahraďte user@domain.com svým uživatelským jménem Microsoft Entra.

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

Vytvoření aplikace v Pythonu

Vytvořte novou složku s názvem keyVaultExample. Pak pomocí preferovaného editoru kódu vytvořte soubor s názvem program.py uvnitř nově vytvořené složky.

Instalace balíčků služby Key Vault a jazykových služeb

  1. V terminálu nebo příkazovém řádku přejděte do složky projektu a nainstalujte knihovnu identit Microsoft Entra:

    pip install azure-identity
    
  2. Nainstalujte knihovnu tajných kódů služby Key Vault:

    pip install azure-keyvault-secrets
    

Import ukázkového kódu

Do souboru s názvem program.pypřidejte následující vzorový kód . Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name nahraďte názvy tajných kódů, které jste nastavili v trezoru klíčů.

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

Spuštění aplikace

Ke spuštění aplikace použijte následující příkaz. Tajné kódy vašeho klíče a koncového bodu se načtou z trezoru klíčů.

python ./program.py

Odeslání volání služby testovacího jazyka (volitelné)

Pokud používáte prostředek s více službami nebo prostředek jazyka, můžete aplikaci aktualizovat pomocí následujícího postupu a odeslat příklad volání Rozpoznávání pojmenovaných entit načtením klíče a koncového bodu z trezoru klíčů.

  1. Nainstalujte knihovnu jazykových služeb:

    pip install azure-ai-textanalytics==5.1.0
    
  2. Do aplikace přidejte následující kód.

    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. Aplikaci spusťte.

Ověření vaší aplikace

Než budete moct udělit přístup k trezoru klíčů, musíte se ověřit pomocí uživatelského jména a hesla Microsoft Entra.

Pokud se chcete ověřit pomocí Azure CLI, spusťte az login příkaz.

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč, který se má ověřit. Pro systémy bez az login výchozího webového prohlížeče použije příkaz tok ověřování kódu zařízení. Azure CLI můžete také vynutit, aby místo spuštění prohlížeče používalo tok kódu zařízení, a to tak --use-device-code , že zadáte argument.

Pokud máte více předplatných, nezapomeňte vybrat předplatné Azure, které obsahuje váš trezor klíčů.

Udělení přístupu k trezoru klíčů

Vytvořte zásadu přístupu pro váš trezor klíčů, která uděluje oprávnění k tajným kódům vašemu uživatelskému účtu.

Pokud chcete nastavit zásady přístupu, spusťte příkaz az keyvault set-policy . Nahraďte Your-Key-Vault-Name názvem trezoru klíčů. Nahraďte user@domain.com svým uživatelským jménem Microsoft Entra.

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

Vytvoření aplikace v Javě

V preferovaném integrovaném vývojovém prostředí vytvořte nový projekt konzolové aplikace Java a vytvořte třídu s názvem Example.

Přidání závislostí

V projektu přidejte do pom.xml souboru následující závislosti.

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

Import ukázkového kódu

Zkopírujte následující kód do souboru s názvem Example.java. Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name nahraďte názvy tajných kódů, které jste nastavili v trezoru klíčů.

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

Odeslání volání služby testovacího jazyka (volitelné)

Pokud používáte prostředek s více službami nebo prostředek jazyka, můžete aplikaci aktualizovat pomocí následujícího postupu a odeslat příklad volání Rozpoznávání pojmenovaných entit načtením klíče a koncového bodu z trezoru klíčů.

  1. Do aplikace přidejte následující závislost:

    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-textanalytics</artifactId>
        <version>5.1.12</version>
    </dependency>
    
  2. do souboru přidejte následující příkazy importu.

    import com.azure.ai.textanalytics.models.*;
    import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
    import com.azure.ai.textanalytics.TextAnalyticsClient;
    
  3. Do metody v aplikaci přidejte následující kód main() :

    
    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. Spusťte aplikaci

Ověření vaší aplikace

Než budete moct udělit přístup k trezoru klíčů, musíte se ověřit pomocí uživatelského jména a hesla Microsoft Entra.

Pokud se chcete ověřit pomocí Azure CLI, spusťte az login příkaz.

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč, který se má ověřit. Pro systémy bez az login výchozího webového prohlížeče použije příkaz tok ověřování kódu zařízení. Azure CLI můžete také vynutit, aby místo spuštění prohlížeče používalo tok kódu zařízení, a to tak --use-device-code , že zadáte argument.

Pokud máte více předplatných, nezapomeňte vybrat předplatné Azure, které obsahuje váš trezor klíčů.

Udělení přístupu k trezoru klíčů

Vytvořte zásadu přístupu pro váš trezor klíčů, která uděluje oprávnění k tajným kódům vašemu uživatelskému účtu.

Pokud chcete nastavit zásady přístupu, spusťte příkaz az keyvault set-policy . Nahraďte Your-Key-Vault-Name názvem trezoru klíčů. Nahraďte user@domain.com svým uživatelským jménem Microsoft Entra.

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

Vytvoření nové aplikace Node.js

Vytvořte Node.js aplikaci, která používá váš trezor klíčů.

V terminálu vytvořte složku s názvem key-vault-js-example a změňte ji do této složky:

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

Inicializace projektu Node.js:

npm init -y

Instalace balíčků služby Key Vault a jazykových služeb

  1. Pomocí terminálu nainstalujte knihovnu tajných kódů služby Azure Key Vault @azure/keyvault-secrets pro Node.js.

    npm install @azure/keyvault-secrets
    
  2. Nainstalujte knihovnu identit Azure, @azure/balíček identity pro ověření ve službě Key Vault.

    npm install @azure/identity
    

Import ukázky kódu

Přidejte následující vzorový kód do souboru s názvem index.js. Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name nahraďte názvy tajných kódů, které jste nastavili v trezoru klíčů.

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

Spuštění ukázkové aplikace

Ke spuštění aplikace použijte následující příkaz. Tajné kódy vašeho klíče a koncového bodu se načtou z trezoru klíčů.

node index.js

Odeslání volání služby testovacího jazyka (volitelné)

Pokud používáte prostředek s více službami nebo prostředek jazyka, můžete aplikaci aktualizovat pomocí následujícího postupu a odeslat příklad volání Rozpoznávání pojmenovaných entit načtením klíče a koncového bodu z trezoru klíčů.

  1. Nainstalujte službu Azure AI pro knihovnu jazyků, @azure/ai-text-analytics pro odesílání požadavků rozhraní API do služby Language.

    npm install @azure/ai-text-analytics@5.1.0
    
  2. Do aplikace přidejte následující kód:

    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. Aplikaci spusťte.

Další kroky