관리 ID를 사용하여 Azure Cosmos DB에 연결(Azure AI Search)

아티클
01/14/2025

이 문서에서는 연결 문자열에 자격 증명을 제공하는 대신 관리 ID를 사용하여 Azure Cosmos DB 데이터베이스에 대한 인덱서 연결을 설정하는 방법을 설명합니다.'

시스템 할당 관리 ID 또는 사용자 할당 관리 ID를 사용할 수 있습니다. 관리 ID는 Microsoft Entra 로그인이며 Azure Cosmos DB의 데이터에 액세스하려면 Azure 역할 할당이 필요합니다. 필요에 따라 NoSQL용 Azure Cosmos DB 계정으로 설정 disableLocalAuth 하여 데이터 연결에 대한 유일한 인증 방법으로 역할 기반 액세스를 적용할 true 수 있습니다.

필수 조건

검색 서비스를 위한 관리 ID를 만듭니다.

관리 ID 인증에 지원되는 접근 방식

Azure AI Search는 관리 ID를 사용하여 Azure Cosmos DB에 연결하는 두 가지 메커니즘을 지원합니다.

레거시 접근 방식을 사용하려면 관리 ID를 구성하여 대상 Azure Cosmos DB 계정의 제어 평면에 대한 판독기 권한을 갖도록 해야 합니다. Azure AI Search는 해당 ID를 활용하여 Cosmos DB 계정의 계정 키를 백그라운드에서 가져와 데이터에 액세스합니다. Cosmos DB 계정에 "disableLocalAuth": true.
최신 접근 방식을 사용하려면 대상 Azure Cosmos DB 계정의 컨트롤 및 데이터 평면에서 관리 ID에 적절한 역할을 구성해야 합니다. 그러면 Azure AI Search에서 Cosmos DB 계정의 데이터에 액세스하기 위한 액세스 토큰을 요청합니다. 이 방법은 Cosmos DB 계정에 "disableLocalAuth": true.

Azure Cosmos DB for NoSQL에 연결하는 인덱서는 레거시 및 최신 접근 방식을 모두 지원합니다. 최신 접근 방식을 사용하는 것이 좋습니다.

제한 사항

Azure Cosmos DB for Gremlin 및 MongoDB(현재 미리 보기 상태)에 연결하는 인덱서는 레거시 접근 방식만 지원합니다.

Azure Cosmos DB for NoSQL에 연결

이 섹션에서는 최신 접근 방식을 통해 NoSQL용 Azure Cosmos DB에 대한 연결을 구성하는 단계를 간략하게 설명합니다.

컨트롤 플레인 역할 할당 구성

Azure Portal에 로그인하고 Cosmos DB for NoSQL 계정을 찾습니다.
액세스 제어(IAM) 를 선택합니다.
추가를 선택한 다음, 역할 할당을 선택합니다.
작업 함수 역할 목록에서 Cosmos DB 계정 읽기 권한자를 선택합니다.
다음을 선택합니다.
관리 ID를 선택한 다음 멤버를 선택합니다.
시스템 할당 관리 ID 또는 사용자 할당 관리 ID별로 필터링합니다. 검색 서비스에 대해 이전에 만든 관리 ID가 표시됩니다. 없는 경우 관리 ID를 사용하도록 검색 구성을 참조하세요. 이미 설정했지만 사용할 수 없는 경우 몇 분 정도 주세요.
ID를 선택하고 역할 할당을 저장합니다.

자세한 내용은 NoSQL용 Azure Cosmos DB에서 컨트롤 플레인 역할 기반 액세스 제어 사용을 참조하세요.

데이터 평면 역할 할당 구성

관리 ID는 Cosmos DB 계정의 데이터 평면에서 읽을 역할을 할당해야 합니다. 검색 서비스의 시스템/사용자 할당 ID에 대한 개체(보안 주체) ID는 검색 서비스의 "ID" 탭에서 찾을 수 있습니다. 이 단계는 현재 Azure CLI를 통해서만 수행할 수 있습니다.

변수를 설정합니다.

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

시스템 할당 ID에 대한 역할 할당을 정의합니다.

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

자세한 내용은 Azure Cosmos DB for NoSQL에서 데이터 평면 역할 기반 액세스 제어 사용을 참조 하세요.

데이터 원본 정의 구성

NoSQL용 Azure Cosmos DB 계정에서 컨트롤 플레인 및 데이터 평면 역할 할당을 모두 구성한 후에는 해당 역할에서 작동하는 연결이 설정됩니다.

인덱서는 외부 데이터 원본에 대한 연결에 데이터 원본 개체를 사용합니다. 이 섹션에서는 데이터 원본 연결 문자열에서 시스템 할당 관리 ID 또는 사용자 할당 관리 ID를 지정하는 방법을 설명합니다. 관리 ID 문서에서 더 많은 연결 문자열 예제를 찾을 수 있습니다.

팁

Azure Portal에서 Cosmos DB에 대한 데이터 원본 연결을 만들고 시스템 또는 사용자가 할당한 관리 ID를 지정한 다음 JSON 정의를 확인하여 연결 문자열 어떻게 작성되는지 확인할 수 있습니다.

REST API, Azure Portal 및 .NET SDK는 시스템 할당 또는 사용자 할당 관리 ID를 사용하여 지원합니다.

시스템 할당 ID를 통해 연결

시스템이 할당한 관리 ID와 연결하는 경우 데이터 원본 정의에 유일한 변경 내용은 ‘자격 증명’ 속성의 형식입니다. 계정 키 또는 암호가 없는 데이터베이스 이름 및 ResourceId를 제공합니다. ResourceId에는 Azure Cosmos DB의 구독 ID, 리소스 그룹 및 Azure Cosmos DB 계정 이름이 포함되어야 합니다.

다음은 최신 접근 방식을 연습하는 데이터 원본 REST API 만들기를 사용하는 예제입니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

참고 항목

속성이 IdentityAuthType 연결 문자열 일부가 아닌 경우 Azure AI Search는 이전 버전과의 호환성을 보장하기 위해 기본적으로 레거시 접근 방식을 사용합니다.

사용자 할당 ID를 통해 연결

데이터 원본 정의에 Azure Cosmos DB 계정에 연결하는 데 사용할 특정 ID(검색 서비스에 할당할 수 있는 여러 ID 중에서)를 지정하는 "ID" 속성을 추가해야 합니다.

다음은 최신 접근 방식을 통해 사용자 할당 ID를 사용하는 예제입니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Gremlin/MongoDB용 Azure Cosmos DB에 연결(미리 보기)

이 섹션에서는 레거시 접근 방식을 통해 Gremlin/Mongo용 Azure Cosmos DB에 대한 연결을 구성하는 단계를 간략하게 설명합니다 .

컨트롤 플레인 역할 할당 구성

이전과 동일한 단계를 수행하여 Gremlin/MongoDB용 Azure Cosmos DB의 제어 평면에 적절한 역할을 할당합니다.

연결 문자열 설정

MongoDB 컬렉션의 경우 연결 문자열에 "ApiKind=MongoDb"를 추가하고 미리 보기 REST API를 사용합니다.
Gremlin 그래프의 경우 연결 문자열에 "ApiKind=Gremlin"을 추가하고 미리 보기 REST API를 사용합니다.
어느 종류의 경우든 레거시 접근 방식만 지원됩니다. 즉, IdentityAuthType=AccountKey 완전히 생략하는 것이 유일한 유효한 연결 문자열.

REST API를 통해 시스템 할당 ID를 사용하여 MongoDB 컬렉션에 연결하는 예제는 다음과 같습니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

다음은 사용자 할당 ID를 사용하여 Gremlin 그래프에 연결하는 예제입니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

인덱서를 실행하여 사용 권한 확인

원격 서비스에 대한 연결 정보 및 권한은 인덱서를 실행하는 동안 런타임에 유효성을 검사합니다. 인덱서가 성공하면 연결 구문과 역할 할당이 유효합니다. 자세한 내용은 인덱서, 기술 또는 문서 실행 또는 다시 설정을 참조하세요.

연결 문제 해결

Azure Cosmos DB for NoSQL의 경우 계정에 선택한 네트워크로 제한된 액세스 권한이 있는지 확인합니다. 제한 없이 연결을 시도하여 방화벽 문제를 배제할 수 있습니다. 자세한 내용은 Azure 네트워크 보안으로 보호되는 콘텐츠에 대한 인덱서 액세스를 참조하세요.
NoSQL용 Azure Cosmos DB의 경우 인증 문제로 인해 인덱서가 실패하는 경우 Cosmos DB 계정의 컨트롤 플레인과 데이터 평면 모두에서 역할 할당이 수행 되었는지 확인합니다.
Gremlin 또는 MongoDB의 경우 최근에 Azure Cosmos DB 계정 키를 회전했다면 관리 ID 연결 문자열이 작동할 때까지 최대 15분 정도 기다려야 합니다.

다음을 통해 공유

관리 ID를 사용하여 Azure Cosmos DB에 연결(Azure AI Search)

필수 조건

관리 ID 인증에 지원되는 접근 방식

제한 사항

Azure Cosmos DB for NoSQL에 연결

컨트롤 플레인 역할 할당 구성

데이터 평면 역할 할당 구성

데이터 원본 정의 구성

시스템 할당 ID를 통해 연결

사용자 할당 ID를 통해 연결

Gremlin/MongoDB용 Azure Cosmos DB에 연결(미리 보기)

컨트롤 플레인 역할 할당 구성

연결 문자열 설정

인덱서를 실행하여 사용 권한 확인

연결 문제 해결

참고 항목

피드백

추가 리소스