Vývoj aplikací Azure Cognitive Services s využitím Key Vault

V tomto článku se dozvíte, jak bezpečně vyvíjet aplikace služeb Cognitive Services pomocí Azure Key Vault.

Key Vault snižuje riziko náhodného úniku tajných kódů, protože do aplikace nebudete ukládat informace o zabezpečení.

Požadavky

Poznámka

Projděte si dokumentaci a články s rychlým startem pro službu Cognitive Services, které používáte, abyste porozuměli:

  • 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 Cognitive Services

Než do trezoru klíčů Azure přidáte informace o přihlašovacích údaji, musíte je načíst z prostředku služeb Cognitive Services. Pokud například vaše služba potřebuje klíč a koncový bod, najdete je pomocí následujícího postupu:

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

  2. Ve sbalitelné nabídce na levé straně vyberte Klíče a koncový bod.

    Snímek obrazovky zobrazující stránku klíče a koncového bodu v Azure Portal

Některé služby Cognitive Services vyžadují k ověřování volání rozhraní API různé informace, například 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íčů.

Opakováním těchto kroků 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. Přejděte do trezoru klíčů v Azure Portal.

  2. V sbalitelné nabídce na levé straně vyberteObjects Secrets (Tajné kódyobjektů>).

  3. Vyberte Vygenerovat/importovat.

    Snímek obrazovky zobrazující stránku klíče trezoru klíčů v Azure Portal

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

    Name Hodnota
    Možnosti nahrání Ruční
    Name Název tajného klíče nebo koncového bodu. Příklad: CognitiveServicesKey nebo CognitiveServicesEndpoint
    Hodnota Váš klíč prostředku nebo koncový bod služeb Azure Cognitive Services.

    Později bude vaše aplikace používat tajný kód Name pro zabezpečený přístup k hodnotě .

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

    Tip

    Nezapomeňte si zapamatovat názvy, které nastavíte pro tajné kódy, protože je budete používat později ve své 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. Vaše aplikace bude číst 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ý se uloží do proměnné prostředí.

Vytvořte a přiřaďte trvalou proměnnou prostředí s danou hodnotou.

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, kteří používají Visual Studio 2017 nebo novější, můžou ověřit účet Azure Active Directory prostřednictvím sady Visual Studio. To vám umožní přistupovat 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í .

Pokud chcete provést ověření v sadě Visual Studio, vyberte Nástroje v horní navigační nabídce a vyberte Možnosti. Přejděte k možnosti 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 Azure Active Directory.

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

az login

V systémech s výchozím webovým prohlížečem Azure CLI spustí prohlížeč pro ověření. V systémech bez výchozího webového az login prohlížeče bude příkaz používat tok ověřování kódu zařízení. Zadáním argumentu můžete také vynutit, aby Azure CLI místo spouštění prohlížeče --use-device-code používalo tok kódu zařízení.

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 trezor klíčů, která vašemu uživatelskému účtu udělí oprávnění k tajným kódům.

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

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

Vytvoření nové aplikace v jazyce C#

Pomocí integrovaného vývojového prostředí sady Visual Studio vytvořte novou konzolovou aplikaci .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 kliknutím pravým tlačítkem na řešení v Průzkumník řešení a výběrem možnosti Spravovat balíčky NuGet. Ve správci balíčků, který se otevře, vyberte Procházet a vyhledejte následující knihovny a pro každou z nich vyberte Nainstalovat :

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

Import ukázkového kódu

Zkopírujte do souboru program.cs následující ukázkový kód. Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name 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. Klíče a tajné kódy 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í těchto kroků 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. Knihovnu Azure.AI.TextAnalytics nainstalujte 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 pro každou z nich vyberte Nainstalovat :

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

    using Azure.AI.TextAnalytics;
    
  3. Přidejte do aplikace 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. 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 Azure Active Directory.

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

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč pro ověření. V systémech bez výchozího webového az login prohlížeče použije příkaz tok ověřování kódu zařízení. Zadáním argumentu můžete také vynutit, aby Azure CLI místo spuštění prohlížeče použilo --use-device-code tok kódu zařízení.

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 trezor klíčů, která vašemu uživatelskému účtu udělí oprávnění k tajným kódům.

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

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 Language

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

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

    pip install azure-keyvault-secrets
    

Import ukázkového kódu

Do souboru s názvem program.pypřidejte následující ukázku kódu. Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name 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. Klíče a tajné kódy 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í těchto kroků 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. Přidejte do aplikace 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. 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 Azure Active Directory.

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

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč pro ověření. V systémech bez výchozího webového az login prohlížeče použije příkaz tok ověřování kódu zařízení. Zadáním argumentu můžete také vynutit, aby Azure CLI místo spuštění prohlížeče použilo --use-device-code tok kódu zařízení.

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 trezor klíčů, která vašemu uživatelskému účtu udělí oprávnění k tajným kódům.

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

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 upřednostňovaném integrovaném vývojovém prostředí (IDE) 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 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í těchto kroků 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. přidejte do souboru 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 ve vaší 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 Azure Active Directory.

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

az login

V systémech s výchozím webovým prohlížečem azure CLI spustí prohlížeč pro ověření. V systémech bez výchozího webového az login prohlížeče použije příkaz tok ověřování kódu zařízení. Zadáním argumentu můžete také vynutit, aby Azure CLI místo spuštění prohlížeče použilo --use-device-code tok kódu zařízení.

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 trezor klíčů, která vašemu uživatelskému účtu udělí oprávnění k tajným kódům.

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

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 Language

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

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

    npm install @azure/identity
    

Import ukázky kódu

Do souboru s názvem index.jspřidejte následující ukázku kódu. Nahraďte Your-Key-Secret-Name a Your-Endpoint-Secret-Name 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. Klíče a tajné kódy 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í těchto kroků 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 Cognitive Service for Language @azure/ai-text-analytics , abyste mohli odesílat požadavky 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. Spusťte aplikaci.

Další kroky