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

아티클
09/27/2024

이 문서에서는 관리 REST API를 사용하여 Azure AI 검색 서비스를 만들고 구성하는 방법에 대해 알아봅니다. Management REST API에서만 미리 보기 기능에 대한 조기 액세스를 제공합니다.

Management REST API는 안정적인 미리 보기 버전에서 사용할 수 있습니다. 미리 보기 기능에 액세스하는 경우 미리 보기 API 버전을 설정해야 합니다.

서비스 만들기 또는 업데이트
데이터 평면에 대한 Azure 역할 기반 액세스 제어 사용
고객 관리형 키 정책 적용
의미 순위매기기 사용 안 함
외부 리소스에 데이터를 푸시하는 워크로드 사용 안 함
쿼리 키 만들기
관리자 키 다시 생성
프라이빗 엔드포인트 연결 나열
검색 작업 나열
검색 서비스 삭제

모든 관리 REST API에는 예가 있습니다. 이 문서에서 다루지 않은 작업은 대신 API 참조를 참조하세요.

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
Visual Studio Code와 REST 클라이언트.
액세스 토큰을 가져오는 데 사용되는 Azure CLI입니다. Azure 구독의 소유자 또는 관리자여야 합니다.

액세스 토큰 가져오기

관리 REST API 호출은 Microsoft Entra ID를 통해 인증됩니다. 리소스를 만들고 구성할 수 있는 권한과 함께 요청에 대한 액세스 토큰을 제공해야 합니다.

Azure CLI 또는 Azure PowerShell을 사용하여 액세스 토큰을 생성할 수 있습니다.

Azure CLI에 대한 명령 셸을 엽니다.
Azure 구독에 로그인합니다.
```
az login
```
테넌트 ID 및 구독 ID를 가져옵니다. 테넌트 또는 구독이 여러 개 있는 경우 올바른 테넌트 또는 구독을 사용해야 합니다.
```
az account show
```

액세스 토큰을 가져옵니다.

az account get-access-token --query accessToken --output tsv

테넌트 ID, 구독 ID 및 전달자 토큰이 있어야 합니다. 다음 단계에서 만든 .rest 또는 .http 파일에 이러한 값을 붙여넣습니다.

Visual Studio Code 설정

Visual Studio Code용 REST 클라이언트에 익숙하지 않은 경우 이 섹션에는 이 빠른 시작의 작업을 완료할 수 있도록 설정이 포함되어 있습니다.

Visual Studio Code를 시작하고 확장 타일을 선택합니다.
REST 클라이언트를 검색하고 설치를 선택합니다.
.rest 또는 .http 파일 확장자를 사용하여 명명된 새 파일을 열거나 만듭니다.

이전 단계에서 검색한 값에 대한 변수를 제공합니다.

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

구독에 검색 서비스를 나열하여 세션이 작동하는지 확인합니다.

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

요청 보내기를 선택합니다. 인접한 창에 응답이 표시됩니다. 기존 검색 서비스가 있는 경우 나열됩니다. 그렇지 않으면 목록이 비어 있지만 HTTP 코드가 200 OK인 경우 다음 단계를 수행할 준비가 된 것입니다.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

서비스 만들기 또는 업데이트

현재 구독에서 검색 서비스를 만들거나 업데이트합니다. 이 예제에서는 아직 정의되지 않은 검색 서비스 이름 및 지역에 변수를 사용합니다. 이름을 직접 제공하거나 컬렉션에 새 변수를 추가합니다.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

S3HD 서비스 만들기

S3HD 서비스를 만들려면 sku 및 hostingMode 속성의 조합을 사용합니다. sku를 standard3로 설정하고 "hostingMode"를 HighDensity로 설정합니다.

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

데이터 평면에 대한 역할 기반 액세스 구성

적용 대상: 검색 인덱스 데이터 기여자, 검색 인덱스 데이터 판독기, Search Service 기여자

이 단계에서는 OAuth2 액세스 토큰을 제공하는 데이터 요청에서 권한 부여 헤더를 인식하도록 검색 서비스를 구성합니다.

데이터 평면 작업에 역할 기반 액세스 제어를 사용하려면 authOptions를 aadOrApiKey로 설정한 후 요청을 보냅니다.

역할 기반 액세스 제어를 단독으로 사용하려면 두 번째 요청에 따라 API 키 인증을 해제하고, 이번에는 disableLocalAuth를 true로 설정합니다.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

고객 관리형 키 정책 적용

고객 관리 암호화를 사용하는 경우 검색 서비스가 규정 준수 상태를 보고하도록 하려면 "적용"을 "사용"으로 설정하고 "encryptionWithCMK"를 사용하도록 설정할 수 있습니다.

이 정책을 사용하도록 설정하면 암호화 키가 제공되지 않으면 데이터 원본 내의 연결 문자열과 같은 중요한 데이터를 포함하는 개체를 만드는 REST 호출이 실패합니다. "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

의미 순위매기기 사용 안 함

의미 순위매기기를 사용하도록 설정하지 않는 것이 기본값이지만 서비스 수준에서 기능을 잠그면 더 확실하게 사용할 수 없습니다.

### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

외부 리소스에 데이터를 푸시하는 워크로드 사용 안 함

Azure AI 검색은 지식 저장소를 업데이트하거나 디버그 세션 상태를 저장하거나 보강을 캐싱할 때 외부 데이터 원본에 씁니다. 다음 예에서는 서비스 수준에서 이러한 워크로드를 사용하지 않도록 설정합니다.

### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

검색 서비스 삭제

### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

관리자 API 키 나열

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

관리자 API 키 다시 생성

한 번에 하나의 관리자 API 키만 다시 생성할 수 있습니다.

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

쿼리 API 키 만들기

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

프라이빗 엔드포인트 연결 나열

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

검색 작업 나열

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

다음 단계

검색 서비스를 구성한 후 다음 단계에는 인덱스를 생성하거나 포털, REST API 또는 Azure SDK를 사용하여 인덱스를 쿼리하는 작업이 포함됩니다.

다음을 통해 공유