Azure Key Vault を使用して Azure AI サービス アプリケーションを開発する

Azure Key Vault を使用して Azure AI サービス アプリケーションを安全に開発する方法について説明します。

Key Vault を使うと、アプリケーションにセキュリティ情報を格納せずにすむため、シークレットが誤って漏洩するリスクが軽減されます。

前提条件

Note

お使いの Azure AI サービスのドキュメントとクイックスタート記事を確認して、以下の内容を理解してください。

  • API 呼び出しを送信するために必要な資格情報と他の情報。
  • アプリケーションを実行するために必要なパッケージとコード。

Azure AI サービス リソースから資格情報を取得する

資格情報を Azure キー コンテナーに追加する前に、Azure AI サービス リソースから資格情報を取得する必要があります。 たとえば、お使いのサービスでキーとエンドポイントが必要な場合は、次の手順のようにして確認します。

  1. Azure portal で Azure リソースに移動します。

  2. 左側の折りたたみ可能なメニューから、[キーとエンドポイント] を選びます。

    Azure portal のキーとエンドポイントのページを示すスクリーンショット。

一部の Azure AI サービスでは、キーやリージョンなど、API 呼び出しの認証に必要な情報が異なります。 続ける前に、必ずこの情報を取得してください。

資格情報をキー コンテナーに追加する

アプリケーションで資格情報を取得し、それを使って API 呼び出しの認証を行うには、キー コンテナーのシークレットにそれを追加する必要があります。

次の手順を繰り返して、必要なリソース資格情報ごとにシークレットを生成します。 たとえば、キーとエンドポイントなどです。 これらのシークレット名は、後でアプリケーションの認証に使われます。

  1. ブラウザーの新しいタブまたはウィンドウを開きます。 Azure portal で、キー コンテナーに移動します。

  2. 左側の折りたたみ可能なメニューから、[オブジェクト]>[シークレット] を選びます。

  3. [Generate/Import](生成/インポート) を選択します。

    Azure portal のキー コンテナーのキー ページを示すスクリーンショット。

  4. [シークレットの作成] 画面で、次の値を入力します。

    名前
    Upload options 手動
    名前 キーまたはエンドポイントのシークレット名。 例: "CognitiveServicesKey" または "CognitiveServicesEndpoint"
    Azure AI サービス リソースのキーまたはエンドポイント。

    後で、アプリケーションでシークレットの "名前" を使って "値" に安全にアクセスします。

  5. 他の値は既定値のままにしておきます。 [作成]を選択します

    ヒント

    後でアプリケーションで使うので、シークレットに設定した名前を必ず覚えておいてください。

これで、リソース情報用のシークレットに名前を付けました。

キー コンテナーの名前用の環境変数を作成する

お使いの Azure キー コンテナーの名前用に環境変数を作ることをお勧めします。 アプリケーションで実行時にこの環境変数を読み取って、キーとエンドポイントの情報を取得します。

環境変数を設定するには、次のいずれかのコマンドを使います。 KEY_VAULT_NAME は環境変数の名前で、Your-Key-Vault-Name はキー コンテナーの名前に置き換えます。これが環境変数に格納されます。

永続化された環境変数を作成して割り当て、値を指定します。

setx KEY_VAULT_NAME "Your-Key-Vault-Name"

コマンド プロンプトの新しいインスタンスで、環境変数を読み取ります。

echo %KEY_VAULT_NAME%

Visual Studio を使用して Azure に対する認証を行う

Visual Studio 2017 以降を使っている開発者は、Visual Studio で Microsoft Entra アカウントの認証を行うことができます。 これにより、IDE 内から Azure サブスクリプションにサインインすることで、キー コンテナー内のシークレットにアクセスできます。

Visual Studio で認証を行うには、上部のナビゲーション メニューから [ツール] を選んで、[オプション] を選びます。 [Azure サービス認証] オプションに移動し、ユーザー名とパスワードでサインインします。

コマンド ラインを使用して認証を行う

キー コンテナーへのアクセスを許可する前に、Microsoft Entra のユーザー名とパスワードで認証を行う必要があります。

Azure CLI で認証を行うには、az login コマンドを実行します。

az login

既定の Web ブラウザーを使っているシステムでは、Azure CLI によって認証のためにブラウザーが起動されます。 既定の Web ブラウザーがないシステムの場合は、az login コマンドでデバイス コード認証フローを使用します。 --use-device-code 引数を指定してブラウザーを起動するのではなく、デバイス コード フローを使うよう Azure CLI に強制することもできます。

複数のサブスクリプションがある場合は、必ずキー コンテナーが含まれる Azure サブスクリプションを選択してください。

キー コンテナーへのアクセス許可を付与する

自分のユーザー アカウントにシークレットのアクセス許可を付与するアクセス ポリシーをキー コンテナーに対して作成します。

アクセス ポリシーを設定するには、az keyvault set-policy コマンドを実行します。 Your-Key-Vault-Name は、実際のキー コンテナーの名前に置き換えます。 user@domain.com をお使いの Microsoft Entra ユーザー名に置き換えます。

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

新しい C# アプリケーションを作成する

Visual Studio IDE を使用して新しい .NET Core コンソール アプリを作成します。 1 つの C# ソース ファイル (program.cs) を含んだ "Hello World" プロジェクトが作成されます。

ソリューション エクスプローラーでソリューションを右クリックし、[NuGet パッケージの管理] を選んで、次のクライアント ライブラリをインストールします。 開いたパッケージ マネージャーで [参照] を選び、次のライブラリを検索して、[インストール] を選びます。

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

コード例をインポートする

program.cs ファイルに次のコード例をコピーします。 Your-Key-Secret-NameYour-Endpoint-Secret-Name は、自分のキー コンテナーに設定したシークレット名に置き換えます。

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

        }
    }
}

アプリケーションの実行

アプリケーションを実行するには、Visual studio の上部にある [デバッグ] ボタンを選択します。 キーとエンドポイントのシークレットが、キー コンテナーから取得されます。

言語サービスのテスト呼び出しを送信する (省略可能)

マルチサービス リソースまたは言語リソースを使っている場合は、次の手順のようにして、キー コンテナーからキーとエンドポイントを取得することで固有表現認識の呼び出し例を送信するように、アプリケーションを更新できます。

  1. ソリューション エクスプローラーでソリューションを右クリックし、[NuGet パッケージの管理] を選んで、Azure.AI.TextAnalytics ライブラリをインストールします。 開いたパッケージ マネージャーで [参照] を選び、次のライブラリを検索して、[インストール] を選びます。

  2. 次のディレクティブを自分の program.cs ファイルの先頭に追加します。

    using Azure.AI.TextAnalytics;
    
  3. 次のコード サンプルをアプリケーションに追加します。

    // 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. キーとエンドポイントの値を使って、main メソッドから EntityRecognitionExample() を呼び出す次のコードを追加します。

    EntityRecognitionExample(keySecret.Value.Value, endpointSecret.Value.Value);
    
  5. アプリケーションを実行します。

アプリケーションの認証

キー コンテナーへのアクセスを許可する前に、Microsoft Entra のユーザー名とパスワードで認証を行う必要があります。

Azure CLI で認証を行うには、az login コマンドを実行します。

az login

既定の Web ブラウザーを使っているシステムでは、Azure CLI によって認証のためにブラウザーが起動されます。 既定の Web ブラウザーがないシステムの場合は、az login コマンドでデバイス コード認証フローを使用します。 --use-device-code 引数を指定してブラウザーを起動するのではなく、デバイス コード フローを使うよう Azure CLI に強制することもできます。

複数のサブスクリプションがある場合は、必ずキー コンテナーが含まれる Azure サブスクリプションを選択してください。

キー コンテナーへのアクセス許可を付与する

自分のユーザー アカウントにシークレットのアクセス許可を付与するアクセス ポリシーをキー コンテナーに対して作成します。

アクセス ポリシーを設定するには、az keyvault set-policy コマンドを実行します。 Your-Key-Vault-Name は、実際のキー コンテナーの名前に置き換えます。 user@domain.com をお使いの Microsoft Entra ユーザー名に置き換えます。

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

Python アプリケーションを作成する

keyVaultExample という名前の新しいフォルダーを作成します。 次に、好みのコード エディターを使って、新しく作成したフォルダー内に program.py という名前のファイルを作成します。

Key Vault と言語サービスのパッケージをインストールする

  1. ターミナルまたはコマンド プロンプトで、自分のプロジェクト フォルダーに移動し、Microsoft Entra ID ライブラリをインストールします。

    pip install azure-identity
    
  2. Key Vault シークレット ライブラリをインストールします。

    pip install azure-keyvault-secrets
    

コード例をインポートする

次のコード サンプルを program.py という名前のファイルに追加します。 Your-Key-Secret-NameYour-Endpoint-Secret-Name は、自分のキー コンテナーに設定したシークレット名に置き換えます。

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

アプリケーションの実行

次のコマンドを使って、アプリケーションを実行します。 キーとエンドポイントのシークレットが、キー コンテナーから取得されます。

python ./program.py

言語サービスのテスト呼び出しを送信する (省略可能)

マルチサービス リソースまたは言語リソースを使っている場合は、次の手順のようにして、キー コンテナーからキーとエンドポイントを取得することで固有表現認識の呼び出し例を送信するように、アプリケーションを更新できます。

  1. 言語サービス ライブラリをインストールします。

    pip install azure-ai-textanalytics==5.1.0
    
  2. 次のコードをアプリケーションに追加します

    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. アプリケーションを実行します。

アプリケーションの認証

キー コンテナーへのアクセスを許可する前に、Microsoft Entra のユーザー名とパスワードで認証を行う必要があります。

Azure CLI で認証を行うには、az login コマンドを実行します。

az login

既定の Web ブラウザーを使っているシステムでは、Azure CLI によって認証のためにブラウザーが起動されます。 既定の Web ブラウザーがないシステムの場合は、az login コマンドでデバイス コード認証フローを使用します。 --use-device-code 引数を指定してブラウザーを起動するのではなく、デバイス コード フローを使うよう Azure CLI に強制することもできます。

複数のサブスクリプションがある場合は、必ずキー コンテナーが含まれる Azure サブスクリプションを選択してください。

キー コンテナーへのアクセス許可を付与する

自分のユーザー アカウントにシークレットのアクセス許可を付与するアクセス ポリシーをキー コンテナーに対して作成します。

アクセス ポリシーを設定するには、az keyvault set-policy コマンドを実行します。 Your-Key-Vault-Name は、実際のキー コンテナーの名前に置き換えます。 user@domain.com をお使いの Microsoft Entra ユーザー名に置き換えます。

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

Java アプリケーションを作成する

好みの IDE で、新しい Java コンソール アプリケーション プロジェクトを作成し、Example という名前のクラスを作成します。

依存関係を追加する

プロジェクトで、次の依存関係を 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>

コード例をインポートする

次のコードを Example.java という名前のファイルにコピーします。 Your-Key-Secret-NameYour-Endpoint-Secret-Name は、自分のキー コンテナーに設定したシークレット名に置き換えます。

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

言語サービスのテスト呼び出しを送信する (省略可能)

マルチサービス リソースまたは言語リソースを使っている場合は、次の手順のようにして、キー コンテナーからキーとエンドポイントを取得することで固有表現認識の呼び出し例を送信するように、アプリケーションを更新できます。

  1. アプリケーションで、次の依存関係を追加します。

    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-textanalytics</artifactId>
        <version>5.1.12</version>
    </dependency>
    
  2. 次の import ステートメントをファイルに追加します。

    import com.azure.ai.textanalytics.models.*;
    import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
    import com.azure.ai.textanalytics.TextAnalyticsClient;
    
  3. 次のコードをアプリケーションの 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. アプリケーションを実行する

アプリケーションの認証

キー コンテナーへのアクセスを許可する前に、Microsoft Entra のユーザー名とパスワードで認証を行う必要があります。

Azure CLI で認証を行うには、az login コマンドを実行します。

az login

既定の Web ブラウザーを使っているシステムでは、Azure CLI によって認証のためにブラウザーが起動されます。 既定の Web ブラウザーがないシステムの場合は、az login コマンドでデバイス コード認証フローを使用します。 --use-device-code 引数を指定してブラウザーを起動するのではなく、デバイス コード フローを使うよう Azure CLI に強制することもできます。

複数のサブスクリプションがある場合は、必ずキー コンテナーが含まれる Azure サブスクリプションを選択してください。

キー コンテナーへのアクセス許可を付与する

自分のユーザー アカウントにシークレットのアクセス許可を付与するアクセス ポリシーをキー コンテナーに対して作成します。

アクセス ポリシーを設定するには、az keyvault set-policy コマンドを実行します。 Your-Key-Vault-Name は、実際のキー コンテナーの名前に置き換えます。 user@domain.com をお使いの Microsoft Entra ユーザー名に置き換えます。

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

新しい Node.js アプリケーションを作成する

キー コンテナーを使用する Node.js アプリケーションを作成します。

ターミナルで、key-vault-js-example という名前のフォルダーを作成し、そのフォルダーに移動します。

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

Node.js プロジェクトを初期化します。

npm init -y

Key Vault と言語サービスのパッケージをインストールする

  1. ターミナルを使用して、Node.js 用の Azure Key Vault シークレット ライブラリ、@azure/keyvault-secrets をインストールします。

    npm install @azure/keyvault-secrets
    
  2. Key Vault の認証を行うために、Azure ID ライブラリ @azure/identity パッケージをインストールします。

    npm install @azure/identity
    

コード サンプルをインポートする

次のコード サンプルを index.js という名前のファイルに追加します。 Your-Key-Secret-NameYour-Endpoint-Secret-Name は、自分のキー コンテナーに設定したシークレット名に置き換えます。

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

サンプル アプリケーションの実行

次のコマンドを使って、アプリケーションを実行します。 キーとエンドポイントのシークレットが、キー コンテナーから取得されます。

node index.js

言語サービスのテスト呼び出しを送信する (省略可能)

マルチサービス リソースまたは言語リソースを使っている場合は、次の手順のようにして、キー コンテナーからキーとエンドポイントを取得することで固有表現認識の呼び出し例を送信するように、アプリケーションを更新できます。

  1. Language サービスに API 要求を送信するため、Language 用 Azure AI サービス ライブラリ @azure/ai-text-analytics をインストールします。

    npm install @azure/ai-text-analytics@5.1.0
    
  2. 次のコードをアプリケーションに追加します。

    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. アプリケーションを実行します。

次のステップ