역할을 사용하여 Azure AI Search에 연결

1. Azure Portal에 로그인합니다.

2. 다음 역할을 할당합니다.

   • 소유자(쿼리 권한을 제외한 모든 데이터 평면 및 컨트롤 플레인 작업에 대한 모든 액세스 권한)
   • 기여자(역할 할당 권한을 제외하면 소유자와 동일)
   • 읽기 권한자(메트릭 모니터링 및 보기 가능)

PowerShell을 사용하여 역할을 할당하는 경우, New-AzRoleAssignment를 호출하여 Azure 사용자나 그룹 이름을 제공하는 동시에 해당 할당의 범위를 제공합니다.

이 예에서는 Search Service로 범위가 할당된 역할 할당을 만듭니다.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

1. Azure Portal에 로그인합니다.

2. 다음 역할을 할당합니다.

   • Search Service 기여자(인덱스, 인덱서, 기술 세트 및 기타 최상위 개체에 대한 만들기, 읽기, 업데이트 및 삭제 작업)
   • 검색 인덱스 데이터 기여자(문서 로드 및 인덱싱 작업 실행)
   • 검색 인덱스 데이터 읽기 권한자(인덱스 쿼리)

PowerShell을 사용하여 역할을 할당하는 경우, New-AzRoleAssignment를 호출하여 Azure 사용자나 그룹 이름을 제공하는 동시에 해당 할당의 범위를 제공합니다.

이 예에서는 Search Service로 범위가 할당된 역할 할당을 만듭니다.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

이 예에서는 특정 인덱스로 범위가 할당된 역할 할당을 만듭니다.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

1. Azure Portal에 로그인합니다.

2. 검색 인덱스 데이터 읽기 권한자 역할을 할당합니다.

PowerShell을 사용하여 역할을 할당하면 New-AzRoleAssignment를 호출하여 Azure 사용자 또는 그룹 이름과 할당 범위를 제공합니다.

1. 구독 ID, 검색 서비스 리소스 그룹, 검색 서비스 이름을 가져옵니다.

2. Azure OpenAI 등 Azure 서비스의 개체 식별자를 가져옵니다.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. 역할 정의를 가져와 사용 권한을 검토함으로써 이 역할을 원하는지 확인합니다.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. 자리 표시자에 유효한 값을 대체하여 역할 할당을 만듭니다.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. 이 예에서는 특정 인덱스로 범위가 지정된 역할 할당을 보여줍니다.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

1. Azure Portal에 로그인합니다.

2. 검색 서비스로 이동합니다.

3. 개요 페이지에서 인덱스 탭을 선택합니다.

   • 검색 서비스 기여자는 모든 개체를 보고 만들 수 있지만 문서를 로드하거나 인덱스를 쿼리할 수는 없습니다. 권한을 확인하려면 검색 인덱스를 만듭니다.

   • 검색 인덱스 데이터 기여자는 문서를 로드할 수 있습니다. 데이터 가져오기 마법사 외부의 Azure Portal에는 문서 로드 옵션이 없지만 인덱서 재설정 후 실행을 통해 문서 로드 권한을 확인할 수 있습니다.

   • 검색 인덱스 데이터 읽기 권한자는 인덱스를 쿼리할 수 있습니다. 권한을 확인하려면 검색 탐색기를 사용합니다. 쿼리를 보내고 결과를 볼 수 있어야 하지만 인덱스 정의를 보거나 만들 수는 없습니다.

이 방법은 REST 클라이언트 확장이 있는 Visual Studio Code를 가정합니다.

1. Azure CLI에 대한 명령 셸을 열고 Azure 구독에 로그인합니다.

   az login
   

2. 테넌트 ID와 구독 ID를 가져옵니다. 이후 단계에서 ID를 변수로 사용합니다.

   az account show
   

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

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

4. Visual Studio Code의 새 텍스트 파일에서 이러한 변수를 붙여넣습니다.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. 지정한 변수를 사용하는 요청을 붙여넣은 다음 보냅니다. "검색 인덱스 데이터 읽기 권한자" 역할의 경우 쿼리를 보낼 수 있습니다. 지원되는 모든 API 버전을 사용할 수 있습니다.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2025-09-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

특정 환경에 대한 토큰을 획득하는 방법에 대한 자세한 내용은 REST를 사용하여 Azure AI 검색 서비스 관리 및 Microsoft ID 플랫폼 인증 라이브러리를 참조하세요.

1. Azure.Search.Documents 패키지를 사용합니다.

2. 토큰 인증에는 .NET용 Azure.Identity를 사용합니다. Microsoft는 대부분의 시나리오에 DefaultAzureCredential()을 권장합니다.

3. 클라이언트 연결의 예시는 DefaultAzureCredential()을 사용하는 것입니다.

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. 다음은 클라이언트 암호 자격 증명을 사용하는 또 다른 예입니다.

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

1. azure.search.documents(Python용 Azure SDK)를 사용합니다.

2. 토큰 인증에는 Python용 Azure.Identity를 사용합니다.

3. Python 클라이언트가 서버 쪽을 실행하는 애플리케이션인 경우 DefaultAzureCredential을 사용합니다. 앱이 브라우저에서 실행되는 경우 대화형 인증을 사용하도록 설정합니다.

4. 예를 들면 다음과 같습니다.

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

1. @azure/search-documents(JavaScript용 Azure SDK) 버전 11.3을 사용합니다.

2. 토큰 인증에는 JavaScript용 Azure.Identity를 사용합니다.

3. React를 사용하는 경우 검색에 대한 Microsoft Entra 인증을 위해 InteractiveBrowserCredential을 사용합니다. 자세한 내용은 사용 시기@azure/identity를 참조하세요.

1. azure-search-documents(Java용 Azure SDK)를 사용합니다.

2. 토큰 인증에는 Java용 Azure.Identity를 사용합니다.

3. Azure에서 실행되는 앱에는 DefaultAzureCredential 을 사용합니다.

이러한 단계는 Azure Portal을 사용하여 사용자 지정 역할 만들기 또는 업데이트에서 파생됩니다. 검색 서비스 페이지에서 기존 역할의 복제를 지원합니다.

이러한 단계에서는 이름별로 인덱스 나열을 포함하도록 검색 쿼리 권한을 보강하는 사용자 지정 역할을 만듭니다. 일반적으로 인덱스 나열은 관리 기능으로 간주됩니다.

1. Azure Portal에서 검색 서비스로 이동합니다.

2. 왼쪽 탐색 창에서 액세스 제어(IAM)를 선택합니다.

3. 작업 모음에서 역할을 선택합니다.

4. 검색 인덱스 데이터 읽기 권한자(또는 다른 역할)를 마우스 오른쪽 단추로 클릭하고 복제를 선택하여 사용자 지정 역할 만들기 마법사를 엽니다.

5. 기본 탭에서 “검색 인덱스 데이터 탐색기”와 같은 사용자 지정 역할의 이름을 입력하고 다음을 선택합니다.

6. 사용 권한 탭에서 사용 권한 추가를 선택합니다.

7. 사용 권한 추가 탭에서 Microsoft Search 타일을 검색한 다음, 선택합니다.

8. 사용자 지정 역할의 사용 권한을 설정합니다. 페이지 맨 위에서 기본 작업 선택을 사용합니다.

   • Microsoft.Search/operations에서 읽기: 사용 가능한 모든 작업 나열을 선택합니다.
   • Microsoft.Search/searchServices/indexes에서 읽기: 인덱스 읽기를 선택합니다.

9. 동일한 페이지에서 데이터 작업으로 전환하고 Microsoft.Search/searchServices/indexes/documents에서 읽기: 문서 읽기를 선택합니다.

   JSON 정의는 다음 예제와 유사합니다.

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. 검토 + 만들기를 선택하여 역할을 만듭니다. 이제 역할에 사용자 및 그룹을 할당할 수 있습니다.

PowerShell 예제에서는 검색 인덱스 데이터 판독기의 복제본이지만 이름으로 모든 인덱스를 나열하는 기능을 사용하는 사용자 지정 역할을 만들기 위한 JSON 구문을 보여 있습니다.

1. 원자성 사용 권한 목록을 검토하여 필요한 사용 권한을 확인합니다. 이 예제에서는 다음 권한이 필요합니다.

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. PowerShell 세션을 설정하여 사용자 지정 역할을 만듭니다. 자세한 지침은 Azure PowerShell을 참조하세요.

3. 역할 정의를 JSON 문서로 제공합니다. 다음 예제에서는 PowerShell을 사용하여 사용자 지정 역할을 만들기 위한 구문을 보여 줍니다.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

1. 원자성 사용 권한 목록을 검토하여 필요한 사용 권한을 확인합니다.

2. 단계는 REST API를 사용하여 Azure 사용자 지정 역할을 만들거나 업데이트하기를 참조하세요.

3. 역할을 복사하거나 만들거나 JSON을 사용하여 사용자 지정 역할을 지정합니다(JSON 구문에 대한 PowerShell 탭 참조).

1. 원자성 사용 권한 목록을 검토하여 필요한 사용 권한을 확인합니다.

2. 단계는 Azure CLI를 사용하여 Azure 사용자 지정 역할을 만들거나 업데이트하기를 참조하세요.

3. JSON 구문은 PowerShell 탭을 참조하세요.