Azure CLI を使用して Azure AI Search Serviceを管理する
Azure CLI コマンドとスクリプトは、Windows、macOS、Linux、または Azure Cloud Shell で実行して、Azure AI Search を作成して構成できます。
az search モジュール を使用して、以下のタスクを実行します。
場合によっては、上記の一覧には "ない" タスクについて質問されることがあります。
プログラムまたはポータルでサーバー名、リージョン、またはレベルを変更することはできません。 サービスの作成時に専用のリソースが割り当てられます。 そのため、基になるハードウェア (場所またはノードの種類) を変更するには、新しいサービスが必要です。
ツールまたは API を使用して、サービス間でインデックスなどのコンテンツを転送することはできません。 サービス内では、プログラムによるコンテンツの作成は、Search サービス REST API または Azure SDK for .NET などの SDK を介して行われます。 コンテンツ移行用の専用コマンドはありませんが、REST API またはクライアント ライブラリを呼び出して、新しいサービスにインデックスを作成して読み込むためのスクリプトを作成できます。
プレビュー管理機能は、通常、az search モジュールでは使用できません。 プレビュー機能を使用する場合は、Management REST API とプレビュー API バージョンを使用します。
前提条件
Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。
初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。
Azure CLI のバージョンの一覧が GitHub に掲載されています。
az search モジュールは、完全なパリティを含む Azure CLI を安定バージョンの Search Management REST API に拡張します。
サブスクリプション内のサービスを一覧表示する
次のコマンドは、az resource から、サブスクリプションで既にプロビジョニングされている既存のリソースとサービスに関する情報を返します。 既に作成されている検索サービスの数がわからない場合は、これらのコマンドがその情報を返して、ポータルに移動する手間を省きます。
最初のコマンドは、すべての検索サービスを返します。
az resource list --resource-type Microsoft.Search/searchServices --output table
サービスの一覧からは、特定のリソースに関する情報を返します。
az resource list --name <search-service-name>
すべての az search コマンドの一覧表示
CLI を使用して、az search で使用できるサブグループとコマンドに関する情報を表示できます。 それ以外に関しては、ドキュメントを参照してください。
az search で利用可能なサブグループを表示するには、次のコマンドを実行します。
az search --help
応答は、次の出力のようになります。
Group
az search : Manage Azure Search services, admin keys and query keys.
WARNING: This command group is in preview and under development. Reference and support
levels: https://aka.ms/CLI_refstatus
Subgroups:
admin-key : Manage Azure Search admin keys.
private-endpoint-connection : Manage Azure Search private endpoint connections.
private-link-resource : Manage Azure Search private link resources.
query-key : Manage Azure Search query keys.
service : Manage Azure Search services.
shared-private-link-resource : Manage Azure Search shared private link resources.
For more specific examples, use: az find "az search"
各サブグループごとに、複数の利用可能なコマンドが用意されています。 次の行を実行すると、service サブグループ内の使用可能なコマンドを確認できます。
az search service --help
また、特定のコマンドに使用できる引数を確認することもできます。
az search service create --help
検索サービス情報の取得
検索サービスが含まれているリソース グループを把握している場合は、az search service show を実行すると、名前、リージョン、レベル、レプリカとパーティションの数などのサービス定義が返されます。 このコマンドでは、検索サービスを含むリソース グループを指定します。
az search service show --name <service-name> --resource-group <search-service-resource-group-name>
サービスの作成または削除
新しい検索サービスを作成するには、az search service create コマンドを使用します。
az search service create \
--name <service-name> \
--resource-group <search-service-resource-group-name> \
--sku Standard \
--partition-count 1 \
--replica-count 1
結果は次の出力のようになります。
{
"hostingMode": "default",
"id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
"identity": null,
"location": "West US",
"name": "my-demo-searchapp",
"networkRuleSet": {
"bypass": "None",
"ipRules": []
},
"partitionCount": 1,
"privateEndpointConnections": [],
"provisioningState": "succeeded",
"publicNetworkAccess": "Enabled",
"replicaCount": 1,
"resourceGroup": "demo-westus",
"sharedPrivateLinkResources": [],
"sku": {
"name": "standard"
},
"status": "running",
"statusDetails": "",
"tags": null,
"type": "Microsoft.Search/searchServices"
}
az search service delete は、サービスとそのデータを削除します。
az search service delete --name <service-name> \
--resource-group <search-service-resource-group-name> \
IP 規則を使用してサービスを作成する
セキュリティ要件によっては、IP ファイアウォールが構成された検索サービスを作成したい場合があります。 そのためには、下に示すように、パブリック IP (v4) アドレスまたは CIDR 範囲を ip-rules 引数に渡します。 規則はコンマ (,) またはセミコロン (;) で区切る必要があります。
az search service create \
--name <search-service-name> \
--resource-group <search-service-resource-group-name> \
--sku Standard \
--partition-count 1 \
--replica-count 1 \
--ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"
システム割り当てマネージド ID を使用してサービスを作成する
場合によっては、たとえばマネージド ID を使用してデータ ソースに接続するときなど、システム割り当てマネージド ID を有効にする必要が生じることがあります。 これを行うには、--identity-type SystemAssigned をコマンドに追加します。
az search service create \
--name <search-service-name> \
--resource-group <search-service-resource-group-name> \
--sku Standard \
--partition-count 1 \
--replica-count 1 \
--identity-type SystemAssigned
プライベート エンドポイントを使用してサービスを作成する
Azure AI Search のプライベート エンドポイントは、仮想ネットワーク上のクライアントは、 Private Link経由で検索インデックス内のデータに安全にアクセスできます。 プライベート エンドポイントは、検索サービスのために仮想ネットワークのアドレス空間の IP アドレスを使用します。 クライアントと検索サービス間のネットワーク トラフィックは、仮想ネットワークおよび Microsoft バックボーン ネットワーク上のプライベートリンクを経由することで、パブリック インターネット上での露出を排除します。 詳細については、Azure AI Search のプライベート エンドポイントの作成に関するドキュメントを参照してください。
次の例では、プライベート エンドポイントを使用して検索サービスを作成する方法を示します。
最初に、PublicNetworkAccess を Disabled に設定した検索サービスをデプロイします。
az search service create \
--name <search-service-name> \
--resource-group <search-service-resource-group-name> \
--sku Standard \
--partition-count 1 \
--replica-count 1 \
--public-access Disabled
次に、仮想ネットワークとプライベート エンドポイントを作成します。
# Create the virtual network
az network vnet create \
--resource-group <vnet-resource-group-name> \
--location "West US" \
--name <virtual-network-name> \
--address-prefixes 10.1.0.0/16 \
--subnet-name <subnet-name> \
--subnet-prefixes 10.1.0.0/24
# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
--name <subnet-name> \
--resource-group <vnet-resource-group-name> \
--vnet-name <virtual-network-name> \
--disable-private-endpoint-network-policies true
# Get the id of the search service
id=$(az search service show \
--resource-group <search-service-resource-group-name> \
--name <search-service-name> \
--query [id] \
--output tsv)
# Create the private endpoint
az network private-endpoint create \
--name <private-endpoint-name> \
--resource-group <private-endpoint-resource-group-name> \
--vnet-name <virtual-network-name> \
--subnet <subnet-name> \
--private-connection-resource-id $id \
--group-id searchService \
--connection-name <private-link-connection-name>
最後に、プライベート DNS ゾーンを作成します。
## Create private DNS zone
az network private-dns zone create \
--resource-group <private-dns-resource-group-name> \
--name "privatelink.search.windows.net"
## Create DNS network link
az network private-dns link vnet create \
--resource-group <private-dns-resource-group-name> \
--zone-name "privatelink.search.windows.net" \
--name "myLink" \
--virtual-network <virtual-network-name> \
--registration-enabled false
## Create DNS zone group
az network private-endpoint dns-zone-group create \
--resource-group <private-endpoint-resource-group-name>\
--endpoint-name <private-endpoint-name> \
--name "myZoneGroup" \
--private-dns-zone "privatelink.search.windows.net" \
--zone-name "searchServiceZone"
プライベート エンドポイントを Azure CLI で作成する場合の詳細については、こちらの Private Link のクイックスタートに関する記事を参照してください。
プライベート エンドポイント接続を管理する
プライベー ト エンドポイント接続を作成するだけでなく、接続を show、update、delete することもできます。
プライベート エンドポイント接続を取得し、その状態を確認するには、az search private-endpoint-connection show を使用します。
az search private-endpoint-connection show \
--name <pe-connection-name> \
--service-name <search-service-name> \
--resource-group <search-service-resource-group-name>
接続を更新するには、az search private-endpoint-connection update を使用します。 次の例では、プライベート エンドポイント接続を拒否に設定します。
az search private-endpoint-connection update \
--name <pe-connection-name> \
--service-name <search-service-name> \
--resource-group <search-service-resource-group-name>
--status Rejected \
--description "Rejected" \
--actions-required "Please fix XYZ"
プライベート エンドポイント接続を削除するには、az search private-endpoint-connection delete を使用します。
az search private-endpoint-connection delete \
--name <pe-connection-name> \
--service-name <search-service-name> \
--resource-group <search-service-resource-group-name>
管理者キーを再生成する
管理者 API キーをロール オーバーするには、az search admin-key renew を使用します。 認証済みのアクセス用に各サービスで 2 つの管理者キーが作成されます。 キーは要求ごとに必要です。 どちらの管理者キーも機能的に同等で、検索サービスに完全な書き込みアクセス権を付与して、情報を取得したり、オブジェクトを作成または削除したりできるようにします。 2 つのキーが存在しているため、1 つを使いながら、もう 1 つを置き換えることができます。
一度に再生成できるのは、primary または secondary キーのいずれかとして指定された 1 つのキーのみです。 中断のないサービスの場合は、必ずすべてのクライアント コードを更新して、プライマリ キーのロール オーバー中はセカンダリ キーを使用するようにしてください。 操作の実行中はキーを変更しないでください。
ご想像のとおり、クライアント コードを更新せずにキーを再生成すると、古いキーを使用する要求は失敗します。 すべての新しいキーを再生成しても完全にサービスを利用できなくなるわけではなく、ポータルで引き続きサービスにアクセスできます。 プライマリ キーとセカンダリ キーを再生成した後、新しいキーを使用するようにクライアント コードを更新することができ、操作がそれに応じて再開されます。
API キーの値は、サービスによって生成されます。 Azure AI Search で使用するカスタム キーを指定することはできません。 同様に、管理者 API キーにユーザー定義の名前はありません。 キーへの参照は、primary または secondary のいずれかの文字列に固定されます。
az search admin-key renew \
--resource-group <search-service-resource-group-name> \
--service-name <search-service-name> \
--key-kind primary
結果は次の出力のようになります。 一度に 1 つのキーしか変更しない場合でも、両方のキーが返されます。
{
"primaryKey": <alphanumeric-guid>,
"secondaryKey": <alphanumeric-guid>
}
クエリ キーの作成または削除
クライアント アプリから Azure AI Search インデックスへの読み取り専用アクセスのクエリAPI キー を作成するには、az 検索クエリキー作成 を使用します。 クエリ キーは、検索結果を取得するために特定のインデックスを認証するために使用します。 クエリ キーは、インデックス、データ ソース、インデクサーなど、サービス上の他の項目への読み取り専用アクセスを付与しません。
Azure AI Search で使用するキーを指定することはできません。 API キーは、サービスによって生成されます。
az search query-key create \
--name myQueryKey \
--resource-group <search-service-resource-group-name> \
--service-name <search-service-name>
レプリカとパーティションのスケーリング
レプリカとパーティションを増減するには、az search service update を使用します。 レプリカまたはパーティションを増やすと、請求書 (固定料金と変動料金の両方が含まれます) に加算されます。 追加の処理能力が一時的に必要になる場合は、レプリカとパーティションを増やしてワークロードを処理することができます。 ポータルの [概要] ページの監視領域には、クエリの待機時間、1 秒あたりのクエリ数、および調整に関するタイルがあり、現在の容量が適切かどうかが表示されます。
リソース割り当ての追加または削除には時間がかかることがあります。 容量の調整は、既存のワークロードを続行できるように、バックグラウンドで行われます。 追加の容量は準備ができるとすぐに受信要求に使用され、追加の構成は必要ありません。
容量の削除には中断を伴うことがあります。 要求が破棄されないようにするため、容量を減らす前にすべてのインデックス作成およびインデクサー ジョブを停止することをお勧めします。 それができない場合は、新しいターゲット レベルに達するまでレプリカやパーティションを一度に 1 つずつ減らして、容量を段階的に減らすことを検討してください。
一度コマンドを送信したら、それを途中で終了する方法はありません。 数を変更するには、コマンドが終了するまで待つ必要があります。
az search service update \
--name <search-service-name> \
--resource-group <search-service-resource-group-name> \
--partition-count 6 \
--replica-count 6
レプリカとパーティション数だけでなく、ip-rules、public-access、および identity-type も更新することができます。
共有プライベート リンク リソースを作成する
Azure AI Search API を使用して作成されるセキュリティで保護されたリソースのプライベート エンドポイントは、 共有プライベート リンク リソースと呼ばれます。 これは、Azure Private Link サービスと統合されているストレージ アカウントなどのリソースへのアクセスを "共有" しているためです。
インデクサーを使用して Azure AI Search のインデックスデータを作成していて、データ ソースがプライベート ネットワーク上にある場合は、送信 プライベート エンドポイント接続 を作成してデータに到達できます。
Azure AI Search から送信プライベート エンドポイントを作成できる Azure リソースの完全なリストについては、 ここにある 関連する グループ ID 値を参照してください。
共有プライベート リンク リソースを作成するには、az search shared-private-link-resource create を使用します。 このコマンドを実行する前にデータ ソースでいくつかの構成が必要になる場合がある点に注意してください。
az search shared-private-link-resource create \
--name <spl-name> \
--service-name <search-service-name> \
--resource-group <search-service-resource-group-name> \
--group-id blob \
--resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage" \
--request-message "Please approve"
共有プライベート リンク リソースを取得し、その状態を表示するには、az search shared-private-link-resource list を使用します。
az search shared-private-link-resource list \
--service-name <search-service-name> \
--resource-group <search-service-resource-group-name>
これを使用する前に、次のコマンドで接続を承認する必要があります。 プライベート エンドポイント接続の ID は、子リソースから取得する必要があります。 この例では、az storage から接続 ID を取得します。
id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")
az network private-endpoint-connection approve --id $id
共有プライベート リンク リソースを削除するには、az search shared-private-link-resource delete を使用します。
az search shared-private-link-resource delete \
--name <spl-name> \
--service-name <search-service-name> \
--resource-group <search-service-resource-group-name>
共有プライベート リンク リソースの設定の詳細については、プライベート エンドポイント経由でのインデクサー接続の作成に関する記事を参照してください。
次のステップ
ポータル、REST API、または .NET SDK を使用して、インデックスを作成し、インデックスのクエリを実行します。