PowerShell を使用して Azure AI Search Serviceを管理する
PowerShell コマンドレットとスクリプトは、Windows、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 バージョンを使用します。
Az.Search モジュールは、完全なパリティを含む Azure PowerShell を安定バージョンの Search Management REST API に拡張します。
バージョンの確認とモジュールの読み込み
この記事の例は対話形式で、昇格された権限が必要です。 ローカル PowerShell と Azure PowerShell (Az モジュール) が必要です。
PowerShell バージョンのチェック
PowerShell がない場合は、最新バージョンの PowerShell をインストールします。
$PSVersionTable.PSVersion
Azure PowerShell の読み込み
Az がインストールされているかどうか不明な場合は、検証手順として次のコマンドを実行します。
Get-InstalledModule -Name Az
一部のシステムでは、モジュールが自動読み込みされません。 上記のコマンドでエラーが発生する場合は、モジュールを読み込んでみてください。これが失敗した場合は、Azure PowerShell のインストール手順に戻って、手順を飛ばしていなかったかどうかを確認してください。
Import-Module -Name Az
ブラウザーでサインイン トークンを使用して Azure に接続する
ポータルのサインイン資格情報を使用して、PowerShell でサブスクリプションに接続することができます。 または、サービス プリンシパルを使用して非対話的に認証することができます。
Connect-AzAccount
複数の Azure サブスクリプションを保持している場合は、使用する Azure サブスクリプションを設定します。 現在のサブスクリプションを一覧表示するには、次のコマンドを実行します。
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
サブスクリプションを指定するには、次のコマンドを実行します。 次の例では、サブスクリプション名は ContosoSubscriptionです。
Select-AzSubscription -SubscriptionName ContosoSubscription
サブスクリプション内のサービスを一覧表示する
次のコマンドは、Az.Resources から、サブスクリプションで既にプロビジョニングされている既存のリソースとサービスに関する情報を返します。 既に作成されている検索サービスの数がわからない場合は、これらのコマンドがその情報を返して、ポータルに移動する手間を省きます。
最初のコマンドは、すべての検索サービスを返します。
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
サービスの一覧からは、特定のリソースに関する情報を返します。
Get-AzResource -ResourceName <service-name>
結果は次の出力のようになります。
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : westus
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Az.Search をインポートする
Az.Search からのコマンドは、モジュールを読み込むまで使用できません。
Install-Module -Name Az.Search -Scope CurrentUser
すべての Az.Search コマンドを一覧表示する
検証手順として、モジュールで提供されるコマンドの一覧を返します。
Get-Command -Module Az.Search
結果は次の出力のようになります。
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet Get-AzSearchAdminKeyPair 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateLinkResource 0.10.0 Az.Search
Cmdlet Get-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Get-AzSearchService 0.10.0 Az.Search
Cmdlet Get-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet New-AzSearchAdminKey 0.10.0 Az.Search
Cmdlet New-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet New-AzSearchService 0.10.0 Az.Search
Cmdlet New-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Remove-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Remove-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Remove-AzSearchService 0.10.0 Az.Search
Cmdlet Remove-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Set-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Set-AzSearchService 0.10.0 Az.Search
Cmdlet Set-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
古いバージョンのパッケージがある場合は、モジュールを更新して最新の機能を取得してください。
Update-Module -Name Az.Search
検索サービス情報の取得
Az.Search がインポートされ、検索サービスが含まれているリソース グループがわかったら、Get-AzSearchService を実行して、名前、リージョン、レベル、レプリカとパーティションの数などのサービス定義を返します。 このコマンドでは、検索サービスを含むリソース グループを指定します。
Get-AzSearchService -ResourceGroupName <resource-group-name>
結果は次の出力のようになります。
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : West US
Sku : Standard
ReplicaCount : 1
PartitionCount : 1
HostingMode : Default
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
サービスの作成または削除
New-AzSearchService は新しい検索サービスの作成に使用されます。
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
結果は次の出力のようになります。
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Id : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 3
PartitionCount : 3
HostingMode : Default
Tags
Remove-AzSearchService は、サービスとそのデータの削除に使用されます。
Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>
アクションを確認するように求められます。
Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
IP 規則を使用してサービスを作成する
セキュリティ要件によっては、IP ファイアウォールが構成された検索サービスを作成することが必要な場合があります。 そのためには、下に示すように、最初に IP 規則を定義して、それらを IPRuleList パラメーターに渡します。
$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
[pscustomobject]@{Value="52.228.215.197"},
[pscustomobject]@{Value="101.37.221.205"})
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IPRuleList $ipRules
システム割り当てマネージド ID を使用してサービスを作成する
場合によっては (マネージド ID を使用してデータ ソースに接続する場合など)、システム割り当てマネージド ID を有効にする必要が生じることがあります。 これを行うには、-IdentityType SystemAssigned をコマンドに追加します。
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
S3HD サービスを作成する
S3HD サービスを作成するには、-Sku と -HostingMode の組合せを使用します。 [-Sku] を [Standard3] に、[-HostingMode] を [HighDensity] に設定します。
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
プライベート エンドポイントを使用してサービスを作成する
Azure AI Search のプライベート エンドポイントは、仮想ネットワーク上のクライアントは、 Private Link経由で検索インデックス内のデータに安全にアクセスできます。 プライベート エンドポイントは、検索サービスのために仮想ネットワークのアドレス空間の IP アドレスを使用します。 クライアントと検索サービス間のネットワーク トラフィックは、仮想ネットワークおよび Microsoft バックボーン ネットワーク上のプライベートリンクを経由することで、パブリック インターネット上での露出を排除します。 詳細については、Azure AI Search のプライベート エンドポイントの作成に関する記事を参照してください。
次の例では、プライベート エンドポイントを使用して検索サービスを作成する方法を示します。
最初に、PublicNetworkAccess を Disabled に設定した検索サービスをデプロイします。
$searchService = New-AzSearchService `
-ResourceGroupName <search-service-resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 1 `
-HostingMode Default `
-PublicNetworkAccess Disabled
次に、仮想ネットワーク、プライベート ネットワーク接続、プライベート エンドポイントを作成します。
# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
-Name <subnet-name> `
-AddressPrefix 10.1.0.0/24 `
-PrivateEndpointNetworkPolicies Disabled
# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
-ResourceGroupName <vm-resource-group-name> `
-Location "West US" `
-Name <virtual-network-name> `
-AddressPrefix 10.1.0.0/16 `
-Subnet $subnetConfig
# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
-Name <private-link-name> `
-PrivateLinkServiceId $searchService.Id `
-GroupId searchService
# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
-Name <private-endpoint-name> `
-ResourceGroupName <private-endpoint-resource-group-name> `
-Location "West US" `
-Subnet $virtualNetwork.subnets[0] `
-PrivateLinkServiceConnection $privateLinkConnection
最後に、プライベート DNS ゾーンを作成します。
## Create private dns zone
$zone = New-AzPrivateDnsZone `
-ResourceGroupName <private-dns-resource-group-name> `
-Name "privatelink.search.windows.net"
## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName <private-dns-link-resource-group-name> `
-ZoneName "privatelink.search.windows.net" `
-Name "myLink" `
-VirtualNetworkId $virtualNetwork.Id
## Create DNS configuration
$config = New-AzPrivateDnsZoneConfig `
-Name "privatelink.search.windows.net" `
-PrivateDnsZoneId $zone.ResourceId
## Create DNS zone group
New-AzPrivateDnsZoneGroup `
-ResourceGroupName <private-dns-zone-resource-group-name> `
-PrivateEndpointName <private-endpoint-name> `
-Name 'myZoneGroup' `
-PrivateDnsZoneConfig $config
プライベート エンドポイントを PowerShell で作成する場合の詳細については、こちらの Private Link のクイックスタートに関する記事を参照してください。
プライベート エンドポイント接続を管理する
プライベー ト エンドポイント接続を作成するだけでなく、接続を Get、Set、Remove することもできます。
Get-AzSearchPrivateEndpointConnection は、プライベート エンドポイント接続を取得するためと、その状態を確認するために使用します。
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Set-AzSearchPrivateEndpointConnection は、接続を更新するために使用します。 次の例では、プライベート エンドポイント接続を拒否に設定します。
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpointConnection は、プライベート エンドポイント接続を削除するために使用します。
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
管理者キーを再生成する
New-AzSearchAdminKey は、管理者 API キーをロール オーバーするために使用されます。 認証済みのアクセス用に各サービスで 2 つの管理者キーが作成されます。 キーは要求ごとに必要です。 どちらの管理者キーも機能的に同等で、検索サービスに完全な書き込みアクセス権を付与して、情報を取得したり、オブジェクトを作成または削除したりできるようにします。 2 つのキーが存在しているため、1 つを使いながら、もう 1 つを置き換えることができます。
一度に再生成できるのは、primary または secondary キーのいずれかとして指定された 1 つのキーのみです。 中断のないサービスの場合は、必ずすべてのクライアント コードを更新して、プライマリ キーのロール オーバー中はセカンダリ キーを使用するようにしてください。 操作の実行中はキーを変更しないでください。
ご想像のとおり、クライアント コードを更新せずにキーを再生成すると、古いキーを使用する要求は失敗します。 すべての新しいキーを再生成してもサービスを完全に利用できなくなるわけではなく、ポータルから引き続きサービスにアクセスできます。 プライマリ キーとセカンダリ キーを再生成した後、新しいキーを使用するようにクライアント コードを更新することができ、操作がそれに応じて再開されます。
API キーの値は、サービスによって生成されます。 Azure AI Search で使用するカスタム キーを指定することはできません。 同様に、管理者 API キーにユーザー定義の名前はありません。 キーへの参照は、primary または secondary のいずれかの文字列に固定されます。
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
結果は次の出力のようになります。 一度に 1 つのキーしか変更しない場合でも、両方のキーが返されます。
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
クエリ キーの作成または削除
New-AzSearchQueryKey は、クライアント アプリから Azure AI Search インデックスへの読み取り専用アクセスに クエリAPI キーを作成するために使用されます。 クエリ キーは、検索結果を取得する目的で特定のインデックスを認証するために使用されます。 クエリ キーによって、インデックス、データ ソース、インデクサーなど、サービス上の他の項目への読み取り専用アクセスは付与されません。
Azure AI Search で使用するキーを指定することはできません。 API キーは、サービスによって生成されます。
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
レプリカとパーティションのスケーリング
Set-AzSearchService は、レプリカとパーティションを増減させてサービス内での課金対象のリソースを再調整するために使用します。 レプリカまたはパーティションを増やすと、請求書 (固定料金と変動料金の両方が含まれます) に加算されます。 追加の処理能力が一時的に必要になる場合は、レプリカとパーティションを増やしてワークロードを処理することができます。 ポータルの [概要] ページの監視領域には、クエリの待機時間、1 秒あたりのクエリ数、および調整に関するタイルがあり、現在の容量が適切かどうかが表示されます。
リソース割り当ての追加または削除には時間がかかることがあります。 容量の調整は、既存のワークロードを続行できるように、バックグラウンドで行われます。 追加の容量は準備ができるとすぐに受信要求に使用され、追加の構成は必要ありません。
容量の削除には中断を伴うことがあります。 要求が破棄されないようにするため、容量を減らす前にすべてのインデックス作成およびインデクサー ジョブを停止することをお勧めします。 それができない場合は、新しいターゲット レベルに達するまでレプリカやパーティションを一度に 1 つずつ減らして、容量を段階的に減らすことを検討してください。
コマンドを送信すると、それを途中で終了する方法はありません。 カウントを変更するには、コマンドが終了するまで待つ必要があります。
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
結果は次の出力のようになります。
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
共有プライベート リンク リソースを作成する
Azure AI Search API を使用して作成されるセキュリティで保護されたリソースのプライベート エンドポイントは、 共有プライベート リンク リソースと呼ばれます。 これは、Azure Private Link サービスと統合されているストレージ アカウントなどのリソースへのアクセスを "共有" しているためです。
インデクサーを使用して Azure AI Search のインデックスデータを作成していて、データ ソースがプライベート ネットワーク上にある場合は、送信 プライベート エンドポイント接続 を作成してデータに到達できます。
Azure AI Search から送信プライベート エンドポイントを作成できる Azure リソースの完全なリストについては、 ここにある 関連する グループ ID 値を参照してください。
New-AzSearchSharedPrivateLinkResource は、共有プライベート リンク リソースを作成するために使用します。 このコマンドを実行する前にデータ ソースで何らかの構成が必要になる場合があることに注意してください。
New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"
Get-AzSearchSharedPrivateLinkResource を使用すると、共有プライベート リンク リソースを取得し、それらの状態を表示することができます。
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
これを使用する前に、次のコマンドを使用して接続を承認する必要があります。
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
Remove-AzSearchSharedPrivateLinkResource は、共有プライベート リンク リソースを削除するために使用します。
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
共有プライベート リンク リソースの設定の詳細については、プライベート エンドポイント経由でのインデクサー接続の作成に関するドキュメントを参照してください。
次のステップ
ポータル、REST API、または .NET SDK を使用して、インデックスを作成し、インデックスのクエリを実行します。