Azure CLI를 사용하여 Azure AI 검색 서비스 관리

아티클
04/15/2024

Windows, macOS, Linux 또는 Azure Cloud Shell에서 Azure CLI 명령 및 스크립트를 실행하여 Azure AI 검색을 만들고 구성할 수 있습니다.

az search 모듈을 사용하여 다음 작업을 수행합니다.

구독에서 검색 서비스 나열
서비스 정보 반환
서비스 만들기 또는 삭제
프라이빗 엔드포인트를 사용하여 서비스 만들기
관리자 API 키 다시 생성
쿼리 API 키 만들기 또는 삭제
복제본 및 파티션을 사용하여 확장 또는 축소
공유 프라이빗 링크 리소스 만들기

경우에 따라 위의 목록에 없는 작업에 대한 질문을 받게 됩니다.

프로그래밍 방식으로 또는 포털에서 서버 이름, 지역 또는 계층을 변경할 수 없습니다. 서비스를 만들 때 전용 리소스가 할당됩니다. 따라서 기본 하드웨어(위치 또는 노드 형식)를 변경하려면 새 서비스가 필요합니다.

도구 또는 API를 사용하여 인덱스와 같은 콘텐츠를 한 서비스에서 다른 서비스로 전송할 수 없습니다. 서비스 내에서 프로그래밍 방식으로 콘텐츠를 만드는 것은 Search 서비스 REST API 또는 .NET용 Azure SDK와 같은 SDK를 통해 수행됩니다. 콘텐츠 마이그레이션을 위한 전용 명령은 없지만 REST API 또는 클라이언트 라이브러리를 호출하는 스크립트를 작성하여 새 서비스에서 인덱스를 만들고 로드할 수 있습니다.

미리 보기 관리 기능은 일반적으로 az search 모듈에서 사용할 수 없습니다. 미리 보기 기능을 사용하려면 관리 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 검색을 위한 프라이빗 엔드포인트는 가상 네트워크의 클라이언트가 Private Link를 통해 검색 인덱스의 데이터에 안전하게 액세스할 수 있도록 합니다. 프라이빗 엔드포인트는 검색 서비스에 가상 네트워크 주소 공간의 IP 주소를 사용합니다. 클라이언트와 검색 서비스 간의 네트워크 트래픽은 가상 네트워크와 Microsoft 백본 네트워크의 프라이빗 링크를 통과하여 퍼블릭 인터넷에서 공개되지 않도록 합니다. 자세한 내용은 Azure AI 검색용 프라이빗 엔드포인트 만들기 설명서를 참조하세요.

다음 예제에서는 프라이빗 엔드포인트를 사용하여 검색 서비스를 만드는 방법을 보여 줍니다.

먼저 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에서 프라이빗 엔드포인트를 만드는 방법에 대한 자세한 내용은 이 프라이빗 링크 빠른 시작을 참조하세요.

프라이빗 엔드포인트 연결 관리

프라이빗 엔드포인트 연결을 만드는 것 외에도 연결에 대해 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를 사용합니다. 각 서비스에서 인증된 액세스에 대해 두 개의 관리 키가 생성됩니다. 모든 요청에 키가 필요합니다. 두 개의 관리자 키는 기능적으로 동일하며, 정보를 검색하거나 개체를 만들고 삭제할 수 있도록 검색 서비스에 완전한 쓰기 권한을 부여합니다. 다른 키를 대체할 때 사용할 수 있도록 두 개의 키가 있습니다.

primary 또는 secondary로 지정된 키를 한 번에 하나씩만 다시 생성할 수 있습니다. 중단 없는 서비스의 경우 기본 키를 교체하는 동안 보조 키를 사용하도록 모든 클라이언트 코드를 업데이트해야 합니다. 작업이 진행되는 동안에는 키를 변경하지 마세요.

짐작할 수 있듯이 클라이언트 코드를 업데이트하지 않고 키를 다시 생성하면 이전 키를 사용하는 요청이 실패합니다. 새 키를 모두 다시 생성하더라도 서비스에 영구적으로 액세스하지 못하는 것은 아니며, 포털을 통해 서비스에 계속 액세스할 수 있습니다. 기본 및 보조 키를 다시 생성한 후 새 키를 사용하도록 클라이언트 코드를 업데이트할 수 있으며 그에 따라 작업이 다시 시작됩니다.

API 키 값은 서비스에 의해 생성됩니다. Azure AI 검색에 사용할 사용자 지정 키를 제공할 수 없습니다. 마찬가지로 관리 API 키에 대한 사용자 정의 이름은 없습니다. 키에 대한 참조는 primary 또는 secondary의 고정 문자열입니다.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

결과는 다음 출력과 비슷합니다. 한 번에 하나씩만 변경하더라도 두 키가 모두 반환됩니다.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

쿼리 키 만들기 또는 삭제

클라이언트 앱에서 Azure AI 검색 인덱스에 대한 읽기 전용 액세스를 위한 쿼리 API 키를 만들려면 az search query-key create를 사용합니다. 쿼리 키는 검색 결과를 검색하기 위해 특정 인덱스에 인증하는 데 사용됩니다. 쿼리 키는 인덱스, 데이터 원본 또는 인덱서와 같은 다른 서비스 항목에 대한 읽기 전용 액세스 권한을 부여하지 않습니다.

Azure AI 검색에 사용할 키를 제공할 수 없습니다. API 키는 서비스에 의해 생성됩니다.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

복제본 및 파티션 스케일링

복제본 및 파티션을 늘리거나 줄이려면 az search service update를 사용합니다. 복제본 또는 파티션을 늘리면 청구 요금이 증가하며, 이 요금에는 고정 요금과 변동 요금이 둘 다 포함되어 있습니다. 일시적으로 더 많은 처리 능력이 필요한 경우 복제본과 파티션을 늘려 워크로드를 처리할 수 있습니다. 개요 포털 페이지의 모니터링 영역에는 쿼리 대기 시간, 초당 쿼리 수 및 제한(현재 용량이 충분한지를 나타냄)에 대한 타일이 있습니다.

리소스를 추가하거나 제거하는 데 시간이 걸릴 수 있습니다. 용량에 대한 조정 작업은 백그라운드에서 발생하므로 기존 작업을 계속할 수 있습니다. 추가 구성이 필요 없이 들어오는 요청이 준비되는 즉시 추가 용량이 사용됩니다.

용량 제거로 인해 장애를 초래할 수 있습니다. 요청 실패를 방지하기 위해 용량을 줄이기 전, 모든 인덱싱 및 인덱서 작업을 중지하는 것이 좋습니다. 그렇게 할 수 없는 경우에는 새 대상 수준에 도달할 때까지 한 번에 하나의 복제본과 파티션을 증분 방식으로 용량을 줄이는 것이 좋습니다.

명령을 제출한 후에는 도중에 종료할 수 있는 방법이 없습니다. 개수를 수정하기 전에 명령이 완료될 때까지 기다려야 합니다.

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 검색 API를 통해 만들어진 보안 리소스의 프라이빗 엔드포인트를 공유 프라이빗 링크 리소스라고 합니다. 이는 Azure Private Link 서비스와 통합된 스토리지 계정과 같이, 리소스에 대한 액세스를 “공유”하는 것이기 때문입니다.

인덱서를 사용하여 Azure AI 검색에서 데이터를 인덱싱하는 경우 데이터 원본이 개인 네트워크에 있으면 아웃바운드 프라이빗 엔드포인트 연결을 만들어 데이터에 연결할 수 있습니다.

Azure AI 검색에서 아웃바운드 프라이빗 엔드포인트를 만들 수 있는 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를 사용하여 인덱스를 쿼리합니다.