키를 사용하여 Azure AI Search에 연결
Azure AI Search는 검색 서비스에 연결하기 위한 키 기반 인증을 제공합니다. API 키는 임의로 생성된 52개의 숫자와 문자로 구성된 고유한 문자열입니다. 소스 코드에서 환경 변수 또는 프로젝트에서 앱 설정으로 지정한 다음 요청에서 변수를 참조할 수 있습니다. 검색 서비스 엔드포인트에 대한 요청은 요청과 API 키가 모두 유효한 경우 수락됩니다.
키 기반 인증이 기본값입니다.
이를 코드베이스에서 하드 코딩된 키가 필요하지 않은 역할 기반 액세스로 대체할 수 있습니다.
API 키 형식
요청을 인증하는 데 사용되는 두 종류의 키가 있습니다.
| Type | 권한 수준 | 최대 | 만든 방법 |
|---|---|---|---|
| 관리자 | 모든 콘텐츠 작업에 대한 모든 권한(읽기-쓰기) | 2 1 | 포털에서 기본 및 보조 키라고 하는 두 개의 관리자 키는 서비스를 만들 때 생성되고 요청 시 개별적으로 다시 생성할 수 있습니다. |
| 쿼리 | 검색 인덱스의 문서 컬렉션으로 범위가 지정된 읽기 전용 액세스 | 50 | 하나의 쿼리 키가 서비스와 함께 생성됩니다. 검색 서비스 관리자가 필요에 따라 더 많이 만들 수 있습니다. |
1 두 개이면 서비스에 대해 액세스를 지속하는 데 하나의 키를 사용하는 동안 다른 키를 롤오버할 수 있습니다.
시각적으로는 관리자 키 및 쿼리 키 간의 구분이 없습니다. 두 키는 임의로 생성된 52개의 영숫자 문자로 구성된 문자열입니다. 애플리케이션에서 지정된 키의 형식을 잃어버린 경우 포털에서 키 값을 확인할 수 있습니다.
연결에 API 키 사용
API 키는 인덱스 만들기 또는 액세스 또는 검색 REST API에 표시되는 기타 요청과 같은 데이터 평면(콘텐츠) 요청에 사용됩니다. 서비스를 만들 때 API 키는 데이터 평면 작업을 위한 유일한 인증 메커니즘이지만, 코드에서 하드 코딩된 키를 사용할 수 없는 경우 키 인증을 Azure 역할로 바꾸거나 보완할 수 있습니다.
관리자 키는 개체를 만들거나 수정하거나 삭제하는 데 사용됩니다. 관리자 키는 개체 정의 및 시스템 정보를 가져오는 데도 사용됩니다.
쿼리 키는 일반적으로 쿼리를 실행하는 클라이언트 애플리케이션에 배포됩니다.
REST 호출에서 API 키가 사용되는 방식:
요청 헤더에서 관리자 키를 설정합니다. URI 또는 요청 본문에는 관리자 키를 전달할 수 없습니다. 관리자 키는 create-read-update-delete 작업 및 검색 서비스 자체에 발급된 요청(예: LIST 인덱스 또는 GET 서비스 통계)에 사용됩니다.
다음은 인덱스 만들기 요청에 관리자 API 키를 사용하는 예입니다.
### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{adminApiKey}}
{
"name": "my-new-index",
"fields": [
{"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "Name", "type": "Edm.String", "searchable": true }
]
}
POST에 대한 요청 헤더 또는 GET에 대한 URI에서 쿼리 키를 설정합니다. 쿼리 키는 다음과 같이 index/docs 컬렉션을 대상으로 하는 작업에 사용됩니다. 문서 검색, 자동 완성, 제안 또는 GET 문서.
다음은 검색 문서(GET) 요청에 쿼리 API 키를 사용하는 예입니다.
### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}
참고 항목
요청 URI에서 api-key와 같은 중요한 데이터를 전달하는 낮은 수준의 보안 사례로 간주됩니다. 이러한 이유로 Azure AI Search는 쿼리 키를 쿼리 문자열의 api-key로만 허용합니다. 일반적으로 api-key를 요청 헤더로 전달하는 것이 좋습니다.
API 키를 보거나 관리할 수 있는 권한
API 키 보기 및 관리 권한은 역할 할당을 통해 전달됩니다. 소유자,
- 소유자
- 기여자
- Search 서비스 기여자
- 관리자 및 공동 관리자(클래식)
다음 역할은 API 키에 대한 액세스 권한이 없습니다.
- 판독기
- 검색 인덱스 데이터 기여자
- 검색 인덱스 데이터 읽기 권한자
기존 키 찾기
Azure Portal에서 또는 PowerShell, Azure CLI나 REST API를 통해 API 키를 보고 관리할 수 있습니다.
Azure Portal에 로그인하고 검색 서비스를 찾습니다.
설정에서 키를 선택하여 관리자 및 쿼리 키를 봅니다.
쿼리 키 만들기
쿼리 키는 문서 컬렉션을 대상으로 하는 작업의 인덱스 내 문서에 대한 읽기 전용 액세스에 사용됩니다. 검색, 필터 및 제안 쿼리는 쿼리 키를 사용하는 모든 작업입니다. 인덱스 정의나 인덱서 상태와 같은 시스템 데이터 또는 개체 정의를 반환하는 모든 읽기 전용 작업에는 관리자 키가 필요합니다.
클라이언트 앱의 액세스 및 작업을 제한하는 것은 서비스의 검색 자산을 보호하는 데 필수적입니다. 클라이언트 앱에서 시작하는 모든 쿼리에 대해 항상 관리자 키 대신 쿼리 키를 사용하세요.
Azure Portal에 로그인하고 검색 서비스를 찾습니다.
설정에서 키를 선택하여 API 키를 봅니다.
쿼리 키 관리에서 서비스에 대해 이미 만들어진 쿼리 키를 사용하거나 새 쿼리 키를 만듭니다. 기본 쿼리 키에는 이름이 지정되지 않지만 관리 용이성을 위해 생성된 다른 쿼리 키에 이름을 지정할 수 있습니다.
관리자 키 다시 생성
두 개의 관리자 키는 비즈니스 연속성에 대한 보조 키를 사용하는 동안 기본 키를 회전할 수 있도록 각 서비스에 대해 생성됩니다.
설정에서 키를 선택한 다음 보조 키를 복사합니다.
모든 애플리케이션의 경우 보조 키를 사용하도록 API 키 설정을 업데이트합니다.
기본 키를 다시 생성합니다.
새 기본 키를 사용하도록 모든 애플리케이션을 업데이트합니다.
실수로 두 키를 동시에 다시 생성하면 해당 키를 사용하는 모든 클라이언트 요청이 HTTP 403 금지됨 오류와 함께 실패합니다. 그러나 콘텐츠는 삭제되지 않으며 영구적으로 잠기지 않습니다.
포털을 통해 또는 프로그래밍 방식으로 서비스에 계속 액세스할 수 있습니다. 관리 기능은 서비스 API 키가 아닌 구독 ID를 통해 작동하므로 가용 API 키가 없는 경우에도 계속 이용할 수 있습니다.
포털 또는 관리 계층을 통해 새 키를 만든 후 요청에 해당 키를 제공하면 콘텐츠(인덱스, 인덱서, 데이터 원본, 동의어 맵)에 대한 액세스가 복원됩니다.
API 키 보안
역할 할당을 사용하여 API 키에 대한 액세스를 제한합니다.
고객 관리형 키 암호화를 사용하여 API 키를 암호화하는 것은 불가능합니다. 검색 서비스 자체 내의 중요한 데이터(예: 데이터 원본 개체 정의의 인덱스 콘텐츠 또는 연결 문자열)만 CMK로 암호화할 수 있습니다.
Azure Portal의 검색 서비스 페이지로 이동합니다.
왼쪽 탐색 창에서 액세스 제어(IAM), 역할 할당 탭을 차례로 선택합니다.
역할 필터에서 키를 보거나 관리할 권한이 있는 역할(소유자, 기여자, 검색 서비스 기여자)을 선택합니다. 이러한 역할에 할당된 결과 보안 주체는 검색 서비스에 대한 주요 권한을 가집니다.
예방 조치로 클래식 관리자 탭을 확인하여 관리자와 공동 관리자에게 액세스 권한이 있는지 확인합니다.
모범 사례
데이터 공개가 위험하지 않고(예: 샘플 데이터를 사용하는 경우) 방화벽 뒤에서 작업하는 경우에만 API 키를 사용합니다. API 키가 노출되면 데이터와 검색 서비스의 무단 사용 모두에 대한 위험이 있습니다.
게시하기 전에 항상 코드, 샘플 및 학습 자료를 확인하여 유효한 API 키를 숨기지 않았는지 확인합니다.
프로덕션 워크로드의 경우 Microsoft Entra ID 및 역할 기반 액세스로 전환합니다. 또는 API 키를 계속 사용하려면 API 키에 액세스할 수 있는 사용자를 항상 모니터링하고 정기적으로 API 키를 다시 생성해야 합니다.