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

  • 아티클

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

시스템 할당 관리 ID 또는 사용자 할당 관리 ID를 사용할 수 있습니다. 관리 ID는 Microsoft Entra 로그인이며 Azure Cosmos DB의 데이터에 액세스하려면 Azure 역할 할당이 필요합니다.

필수 조건

제한 사항

Gremlin 및 MongoDB 컬렉션용 Azure Cosmos DB에 대한 인덱서 지원은 현재 미리 보기로 제공됩니다. 현재 미리 보기 제한 사항에 따라 Azure AI Search에서 키를 사용하여 연결해야 합니다. 관리 ID 및 역할 할당을 계속 설정할 수 있지만 Azure AI 검색은 역할 할당만 사용하여 연결에 대한 키를 가져옵니다. 이 제한은 인덱서가 Gremlin 또는 MongoDB에 연결하는 경우 역할 기반 접근 방식을 구성할 수 없음을 의미합니다.

Azure Cosmos DB에서 역할 할당 만들기

  1. Azure Portal에 로그인하고 Cosmos DB for NoSQL 계정을 찾습니다.

  2. 액세스 제어(IAM) 를 선택합니다.

  3. 추가를 선택한 다음, 역할 할당을 선택합니다.

  4. 작업 함수 역할 목록에서 Cosmos DB 계정 읽기 권한자를 선택합니다.

  5. 다음을 선택합니다.

  6. 관리 ID를 선택한 다음 멤버를 선택합니다.

  7. 시스템 할당 관리 ID 또는 사용자 할당 관리 ID별로 필터링합니다. 검색 서비스에 대해 이전에 만든 관리 ID가 표시됩니다. 없는 경우 관리 ID를 사용하도록 검색 구성을 참조하세요. 이미 설정했지만 사용할 수 없는 경우 몇 분 정도 주세요.

  8. ID를 선택하고 역할 할당을 저장합니다.

자세한 내용은 Azure Cosmos DB 계정에 대한 Microsoft Entra ID를 사용하여 역할 기반 액세스 제어 구성을 참조하세요.

연결 문자열에서 관리 ID 지정

역할 할당이 있으면 해당 역할에서 작동하는 Azure Cosmos DB for NoSQL에 대한 연결을 설정할 수 있습니다.

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

팁

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

시스템 할당 관리 ID

REST API, Azure Portal, .NET SDK는 시스템이 할당한 관리 ID 사용을 지원합니다.

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

  • SQL 컬렉션의 경우 연결 문자열에 "ApiKind"가 필요하지 않습니다.
  • SQL 컬렉션의 경우 역할 기반 액세스가 유일한 인증 방법으로 적용되는 경우 "IdentityAuthType=AccessToken"을 추가합니다. MongoDB 및 Gremlin 컬렉션에는 적용되지 않습니다.
  • MongoDB 컬렉션의 경우 연결 문자열에 "ApiKind=MongoDb"를 추가하고 미리 보기 REST API를 사용합니다.
  • Gremlin 그래프의 경우 연결 문자열에 "ApiKind=Gremlin"을 추가하고 미리 보기 REST API를 사용합니다.

다음은 데이터 원본 만들기 REST API 및 관리 ID 연결 문자열을 사용하여 Cosmos DB 계정의 데이터를 인덱싱하는 데이터 원본을 만드는 방법의 예입니다. 관리 ID 연결 문자열 형식은 REST API, .NET SDK 및 Azure Portal에 대해 동일합니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
{
    "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=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

사용자 할당 관리 ID

사용자 할당 관리 ID로 연결하는 경우 데이터 원본 정의에 두 가지 변경 내용이 있습니다.

  • 먼저 "credentials" 속성의 형식은 계정 키나 암호가 없는 데이터베이스 이름과 ResourceId입니다. ResourceId에는 Azure Cosmos DB의 구독 ID, 리소스 그룹 및 Azure Cosmos DB 계정 이름이 포함되어야 합니다.

    • SQL 컬렉션의 경우 연결 문자열에 "ApiKind"가 필요하지 않습니다.
    • SQL 컬렉션의 경우 역할 기반 액세스가 유일한 인증 방법으로 적용되는 경우 "IdentityAuthType=AccessToken"을 추가합니다. MongoDB 및 Gremlin 컬렉션에는 적용되지 않습니다.
    • MongoDB 컬렉션의 경우 "ApiKind=MongoDb"를 연결 문자열에 추가합니다.
    • Gremlin 그래프의 경우 연결 문자열에 "ApiKind=Gremlin"을 추가합니다.

  • 둘째, 사용자 할당 관리 ID 컬렉션을 포함하는 "ID" 속성을 추가합니다. 데이터 원본을 만들 때는 사용자가 할당한 관리 ID를 하나만 제공해야 합니다. "userAssignedIdentities" 형식으로 설정합니다.

REST API를 사용하여 인덱서 데이터 원본 개체를 만드는 방법의 예는 다음과 같습니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01

{
    "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=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

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

문제 해결

Azure Cosmos DB for NoSQL의 경우 계정에 선택한 네트워크로 제한된 액세스 권한이 있는지 확인합니다. 제한 없이 연결을 시도하여 방화벽 문제를 배제할 수 있습니다.

Gremlin 또는 MongoDB의 경우 최근에 Azure Cosmos DB 계정 키를 회전했다면 관리 ID 연결 문자열이 작동할 때까지 최대 15분 정도 기다려야 합니다.

참고 항목