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

메모

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

REST API 관리 사용하여 Azure AI 검색 서비스를 만들고 구성하는 방법을 알아봅니다. 관리 REST API만 미리 보기 기능에 대한 초기 액세스를 제공하도록 보장됩니다.

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

서비스 만들기 또는 업데이트
서비스 업그레이드
가격 책정 계층 변경
데이터 평면에 대한 역할 기반 액세스 제어 구성
기밀 컴퓨팅 구성
데이터 평면에 대한 Azure 역할 기반 액세스 제어 활성화
고객 관리형 키 정책 적용
외부 리소스에 데이터를 푸시하는 워크로드 사용 안 함
쿼리 키 만들기
관리 키 다시 생성
프라이빗 엔드포인트 연결 나열
검색 작업 나열
검색 서비스 삭제

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

팁

CURL을 사용하여 관리 REST API를 호출하는 경우 콘텐츠 형식 헤더를 application/json -H "Content-Type: application/json"으로 설정해야 합니다. 또는 JSON을 포함하려면 --JSON 플래그를 사용할 수 있습니다.

필수 구성 요소

활성 구독이 있는 Azure 계정입니다. 무료로 계정을 만듭니다.
Visual Studio Code와 REST 클라이언트.
Azure CLI 다음 단계에 설명된 대로 액세스 토큰을 가져옵니다. Azure 구독의 소유자 또는 관리자여야 합니다.

관리 REST API 호출은 Microsoft Entra ID 통해 인증됩니다. 리소스를 만들고 구성하려면 요청에 대한 액세스 토큰과 권한을 제공해야 합니다. Azure CLI 외에도 Azure PowerShell 사용하여 액세스 토큰 만들 수 있습니다.
1. Azure CLI 명령 셸을 엽니다.
2. Azure 구독에 로그인합니다. 테넌트 또는 구독이 여러 개 있는 경우 올바른 테넌트 또는 구독을 선택해야 합니다.
```
az login
```
3. 테넌트 ID 및 구독 ID를 가져옵니다.
```
az account show
```
4. 액세스 토큰을 가져옵니다.
```
az account get-access-token --query accessToken --output tsv
```
  테넌트 ID, 구독 ID 및 전달자 토큰이 있어야 합니다. 다음 단계에서 만드는 .rest 파일 또는 .http 파일에 이러한 값을 붙여넣습니다.

Visual Studio Code 설정

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

Visual Studio Code 시작하고 Extensions 타일을 선택합니다.
REST 클라이언트를 검색하고 설치를 선택합니다.
.rest 또는 .http 파일 확장자로 새 파일을 열거나 생성하세요.

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

@tenant-id = PUT-YOUR-TENANT-ID-HERE
@subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
@token = PUT-YOUR-TOKEN-HERE

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

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
      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 = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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"
        }
      }

서비스 업그레이드

일부 Azure AI 검색 기능은 새 서비스에서만 사용할 수 있습니다. 서비스 재현을 방지하고 이러한 기능을 기존 서비스로 가져오려면 서비스를 업그레이드할 수 있습니다.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

가격 책정 계층 변경

용량이 더 많거나 적게 필요한 경우 다른 가격 책정 계층으로 전환할 수 있습니다. 현재 기본 계층과 표준(S1, S2 및 S3) 계층 간에만 전환할 수 있습니다. 속성을 sku 사용하여 새 계층을 지정합니다.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

S3HD 서비스 만들기

S3HD 서비스를 생성하려면 sku 및 hostingMode 속성을 조합하여 사용하십시오. sku를 standard3로 설정하고, "hostingMode"를 HighDensity로 설정합니다.

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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로 설정한 후 요청을 보냅니다.

역할 기반 액세스 제어를 단독으로 사용하려면, 다음 요청에서는 를 true로 설정하여 disableLocalAuth합니다.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

기밀 컴퓨팅 구성

기밀 컴퓨팅 은 사용 중인 데이터 보호를 위한 선택적 컴퓨팅 유형입니다. 구성되면 검색 서비스는 표준 VM 대신 기밀 VM(DCasv5 또는 DCesv5)에 배포됩니다. 또한 이 컴퓨팅 유형은 청구 가능 계층에 대해 10개의% 추가 요금이 발생합니다. 자세한 내용은 가격 책정 페이지를 참조하세요.

매일 사용하는 경우 기밀 컴퓨팅이 필요하지 않습니다. 엄격한 규정, 규정 준수 또는 보안 요구 사항에 대해서만 이 컴퓨팅 유형을 사용하는 것이 좋습니다. 자세한 내용은 기밀 컴퓨팅 사용 사례를 참조하세요.

컴퓨팅 유형은 검색 서비스의 수명 동안 고정됩니다. 기밀 컴퓨팅을 영구적으로 구성하려면 새 서비스에 computeType 속성을 confidential로 설정합니다.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

고객 관리형 키 정책 적용

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

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

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

검색 서비스 삭제

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

관리자 API 키 나열

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

관리자 API 키 다시 생성

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

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

쿼리 API 키 만들기

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

검색 작업 나열

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

다음 단계

검색 서비스를 구성한 후 다음 단계에는 Azure 포털, REST API 또는 Azure SDK 사용하여 인덱스 만들기 또는 쿼리가 포함됩니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-05-12