빠른 시작: 키 없이 연결

아티클
12/20/2024

Jupyter Notebook 또는 REST 클라이언트를 사용하여 검색 서비스와 상호 작용할 수 있도록 API 키 없이 로컬 시스템에서 연결할 수 있도록 Microsoft Entra ID 인증 및 RBAC(역할 기반 액세스 제어)를 사용하도록 Azure AI Search를 구성합니다.

API 키를 사용하여 연결하는 다른 빠른 시작을 진행한 경우 이 빠른 시작에서는 예제 코드에서 하드 코딩된 키를 방지할 수 있도록 ID 기반 인증으로 전환하는 방법을 보여 줍니다.

필수 구성 요소

Azure 구독 체험 계정 만들기
Azure AI Search, 모든 지역 또는 계층이지만 Azure AI Search에 대한 관리 ID를 구성하려면 기본 이상이 필요합니다.
명령줄 도구(예: PowerShell 또는 Bash) 및 Azure CLI

1단계: Azure 구독 및 테넌트 ID 가져오기

둘 이상의 구독 또는 테넌트가 있는 경우 이 단계가 필요합니다.

검색 서비스에 대한 Azure 구독 및 테넌트 가져오기:
1. Azure Portal에 로그인하고 검색 서비스로 이동합니다.
2. Overview>Essentials의 구독 이름 및 ID를 확인합니다.
3. 이제 구독 이름을 선택하여 다음 페이지에 부모 관리 그룹(테넌트 ID)을 표시합니다.
이제 어떤 구독 및 테넌트 Azure AI Search가 아래에 있는지 알 수 있습니다. 로컬 디바이스 및 명령 프롬프트로 전환하고 디바이스에서 활성 Azure 구독 및 테넌트를 식별합니다.
```
az account show
```
활성 구독 및 테넌트가 이전 단계에서 얻은 정보와 다른 경우 구독 ID를 변경합니다. 다음으로, 이전 단계에서 찾은 테넌트 ID를 사용하여 Azure에 로그인합니다.
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

2단계: RBAC에 대한 Azure AI Search 구성

Azure Portal에 로그인하고 Azure AI Search 서비스로 이동합니다.
RBAC(역할 기반 액세스 제어) 사용:
1. 설정>키로 이동합니다.
2. 역할 기반 컨트롤을 선택하거나 클라이언트를 역할 기반 액세스 제어로 전환할 시간이 필요한 경우 둘 다 선택합니다.
  
  역할 기반 컨트롤을 선택하는 경우 다음 지침에 명명된 모든 역할을 자신에게 할당하거나 Azure Portal 또는 로컬 클라이언트를 통해 작업을 완료할 수 없는지 확인합니다.
Azure Portal에서 역할 할당:
1. 검색 서비스로 이동합니다.
2. 왼쪽 탐색 창에서 액세스 제어(IAM)를 선택합니다.
3. 추가>역할 할당 추가를 선택합니다.
4. 역할(Search Service 기여자, 검색 인덱스 데이터 기여자, 검색 인덱스 데이터 판독기)을 선택하고 Microsoft Entra 사용자 또는 그룹 ID에 할당합니다.
  
  각 역할에 대해 반복합니다.
  
  Azure AI Search에서 개체를 만들고, 로드하고, 쿼리하려면 Search Service 기여자와 Search Index 데이터 기여자가 필요합니다. 자세한 내용은 역할을 사용하여 연결을 참조 하세요.

팁

나중에 인증 실패 오류가 발생하면 이 섹션의 설정을 다시 확인합니다. 구독 또는 리소스 그룹 수준에서 지정한 API 설정을 재정의하는 정책이 있을 수 있습니다.

3단계: 로컬 시스템에서 연결

Azure에 아직 로그인하지 않은 경우:

az login

Python 및 Jupyter Notebook 사용

Azure ID 및 Azure Search 라이브러리를 설치합니다.
```
pip install azure-identity azure-search-documents
```

Azure AI Search 인증 및 연결:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

REST 클라이언트 사용

몇 가지 빠른 시작 및 자습서에서는 REST 확장이 있는 Visual Studio Code와 같은 REST 클라이언트를 사용합니다. Visual Studio Code에서 Azure AI Search에 연결하는 방법은 다음과 같습니다.

빠른 시작: 벡터 검색에 설명된 것과 유사한 파일 또는 .http 파일이 있어야 합니다.rest.

액세스 토큰을 생성합니다.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

파일 맨 위에서 연결에 사용되는 변수를 설정하고, 이전 단계에서 가져온 전체 검색 서비스 엔드포인트 및 액세스 토큰을 붙여넣습니다. 변수는 다음 예제와 유사하게 표시됩니다. 값은 따옴표로 묶지 않습니다.
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

REST 호출에서 권한 부여 전달자 토큰을 지정합니다.

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

401 오류 문제 해결

활성 구독 및 테넌트(az account show)를 확인하고 검색 서비스에 유효한지 확인합니다.
Azure Portal에서 검색 서비스 설정>키 옵션을 확인하고 서비스가 둘 다에 대해 구성되었는지 확인합니다" 또는 역할 기반 액세스 제어.
REST 클라이언트에만 해당: 파일에 지정된 토큰 및 엔드포인트를 확인하고 주변 따옴표나 추가 공백이 없는지 확인합니다.

다른 모든 항목이 실패하면 디바이스를 다시 시작하여 캐시된 토큰을 제거한 다음 이 섹션 az login의 단계를 반복합니다.

추가 구성

아웃바운드 연결에 대한 관리 ID를 구성합니다.

검색 서비스에 대한 시스템 할당 또는 사용자 할당 관리 ID 를 구성합니다.
역할 할당을 사용하여 다른 Azure 리소스에 대한 액세스 권한을 부여합니다.

네트워크 액세스 구성:

IP 주소에 따라 Azure AI Search에 대한 요청을 수락하거나 거부하도록 인바운드 규칙을 설정합니다.

다음을 통해 공유