PowerShell을 사용하여 Azure AI 검색 서비스 관리
Windows, Linux 또는 Azure Cloud Shell에서 PowerShell cmdlet과 스크립트를 실행하여 Azure AI 검색을 만들고 구성할 수 있습니다.
다음 작업을 수행하려면 Az.Search 모듈을 사용합니다.
경우에 따라 위의 목록에 없는 작업에 대한 질문을 받게 됩니다.
프로그래밍 방식으로 또는 포털에서 서버 이름, 지역 또는 계층을 변경할 수 없습니다. 서비스를 만들 때 전용 리소스가 할당됩니다. 따라서 기본 하드웨어(위치 또는 노드 형식)를 변경하려면 새 서비스가 필요합니다.
도구 또는 API를 사용하여 인덱스와 같은 콘텐츠를 한 서비스에서 다른 서비스로 전송할 수 없습니다. 서비스 내에서 프로그래밍 방식으로 콘텐츠를 만드는 것은 Search 서비스 REST API 또는 .NET용 Azure SDK와 같은 SDK를 통해 수행됩니다. 콘텐츠 마이그레이션을 위한 전용 명령은 없지만 REST API 또는 클라이언트 라이브러리를 호출하는 스크립트를 작성하여 새 서비스에서 인덱스를 만들고 로드할 수 있습니다.
미리 보기 관리 기능은 일반적으로 Az.search 모듈에서 사용할 수 없습니다. 미리 보기 기능을 사용하려면 관리 REST API 및 미리 보기 API 버전을 사용합니다.
Az.Search 모듈은 Azure PowerShell을 Search Management REST API의 안정적인 버전과 완전히 동일하게 확장합니다.
버전 확인 및 모듈 로드
이 문서의 예제는 대화형이며 관리자 권한이 필요합니다. 로컬 PowerShell 및 Azure PowerShell(Az 모듈)이 필요합니다.
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 검색을 위한 프라이빗 엔드포인트는 가상 네트워크의 클라이언트가 Private Link를 통해 검색 인덱스의 데이터에 안전하게 액세스할 수 있도록 합니다. 프라이빗 엔드포인트는 검색 서비스에 가상 네트워크 주소 공간의 IP 주소를 사용합니다. 클라이언트와 검색 서비스 간의 네트워크 트래픽은 가상 네트워크와 Microsoft 백본 네트워크의 프라이빗 링크를 통과하여 퍼블릭 인터넷에서 공개되지 않도록 합니다. 자세한 내용은 Azure AI 검색용 프라이빗 엔드포인트 만들기를 참조하세요.
다음 예제에서는 프라이빗 엔드포인트를 사용하여 검색 서비스를 만드는 방법을 보여 줍니다.
먼저 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에서 프라이빗 엔드포인트를 만드는 방법에 대한 자세한 내용은 이 프라이빗 링크 빠른 시작을 참조하세요.
프라이빗 엔드포인트 연결 관리
프라이빗 엔드포인트 연결을 만드는 것 외에도 연결에 대해 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 키를 롤오버하는 데 사용됩니다. 각 서비스에서 인증된 액세스에 대해 두 개의 관리자 키가 생성됩니다. 모든 요청에 키가 필요합니다. 두 개의 관리자 키는 기능적으로 동일하며, 정보를 검색하거나 개체를 만들고 삭제할 수 있도록 검색 서비스에 완전한 쓰기 권한을 부여합니다. 다른 키를 대체할 때 사용할 수 있도록 두 개의 키가 있습니다.
primary 또는 secondary로 지정된 키를 한 번에 하나씩만 다시 생성할 수 있습니다. 중단 없는 서비스의 경우 기본 키를 교체하는 동안 보조 키를 사용하도록 모든 클라이언트 코드를 업데이트해야 합니다. 작업이 진행되는 동안에는 키를 변경하지 마세요.
짐작할 수 있듯이 클라이언트 코드를 업데이트하지 않고 키를 다시 생성하면 이전 키를 사용하는 요청이 실패합니다. 새 키를 모두 다시 생성하더라도 서비스에 영구적으로 액세스하지 못하는 것은 아니며, 포털을 통해 서비스에 계속 액세스할 수 있습니다. 기본 및 보조 키를 다시 생성한 후 새 키를 사용하도록 클라이언트 코드를 업데이트할 수 있으며 그에 따라 작업이 다시 시작됩니다.
API 키 값은 서비스에 의해 생성됩니다. Azure AI 검색에 사용할 사용자 지정 키를 제공할 수 없습니다. 마찬가지로 관리 API 키에 대한 사용자 정의 이름은 없습니다. 키에 대한 참조는 primary 또는 secondary의 고정 문자열입니다.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
결과는 다음 출력과 비슷합니다. 한 번에 하나씩만 변경하더라도 두 키가 모두 반환됩니다.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
쿼리 키 만들기 또는 삭제
New-AzSearchQueryKey는 클라이언트 앱에서 Azure AI 검색 인덱스에 대한 읽기 전용 액세스를 위한 쿼리 API 키를 만드는 데 사용됩니다. 쿼리 키는 검색 결과를 검색하기 위해 특정 인덱스에 인증하는 데 사용됩니다. 쿼리 키는 인덱스, 데이터 원본 또는 인덱서와 같은 다른 서비스 항목에 대한 읽기 전용 액세스 권한을 부여하지 않습니다.
Azure AI 검색에 사용할 키를 제공할 수 없습니다. API 키는 서비스에 의해 생성됩니다.
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
복제본 및 파티션 스케일링
Set-AzSearchService는 서비스 내에서 청구 가능한 리소스를 다시 조정하기 위해 복제본과 파티션을 늘리거나 줄이는 데 사용됩니다. 복제본 또는 파티션을 늘리면 청구 요금이 증가하며, 이 요금에는 고정 요금과 변동 요금이 둘 다 포함되어 있습니다. 일시적으로 더 많은 처리 능력이 필요한 경우 복제본과 파티션을 늘려 워크로드를 처리할 수 있습니다. 개요 포털 페이지의 모니터링 영역에는 쿼리 대기 시간, 초당 쿼리 수 및 제한(현재 용량이 충분한지를 나타냄)에 대한 타일이 있습니다.
리소스를 추가하거나 제거하는 데 시간이 걸릴 수 있습니다. 용량에 대한 조정 작업은 백그라운드에서 발생하므로 기존 작업을 계속할 수 있습니다. 추가 구성이 필요 없이 들어오는 요청이 준비되는 즉시 추가 용량이 사용됩니다.
용량 제거로 인해 장애를 초래할 수 있습니다. 요청 실패를 방지하기 위해 용량을 줄이기 전, 모든 인덱싱 및 인덱서 작업을 중지하는 것이 좋습니다. 그렇게 할 수 없는 경우에는 새 대상 수준에 도달할 때까지 한 번에 하나의 복제본과 파티션을 증분 방식으로 용량을 줄이는 것이 좋습니다.
명령을 제출한 후에는 도중에 종료할 수 있는 방법이 없습니다. 개수를 수정하기 전에 명령이 완료될 때까지 기다려야 합니다.
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/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
공유 프라이빗 링크 리소스 만들기
Azure AI 검색 API를 통해 만들어진 보안 리소스의 프라이빗 엔드포인트를 공유 프라이빗 링크 리소스라고 합니다. 이는 Azure Private Link 서비스와 통합된 스토리지 계정과 같이, 리소스에 대한 액세스를 “공유”하는 것이기 때문입니다.
인덱서를 사용하여 Azure AI 검색에서 데이터를 인덱싱하는 경우 데이터 원본이 개인 네트워크에 있으면 아웃바운드 프라이빗 엔드포인트 연결을 만들어 데이터에 연결할 수 있습니다.
Azure AI 검색에서 아웃바운드 프라이빗 엔드포인트를 만들 수 있는 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
공유 프라이빗 링크 리소스를 설정하는 방법에 대한 자세한 내용은 프라이빗 엔드포인트를 통한 인덱서 연결 만들기에 대한 설명서를 참조하세요.