관리 ID를 사용하여 Azure SQL에 대한 인덱서 연결 설정

아티클
02/23/2024

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

시스템이 할당한 관리 ID나 사용자가 할당한 관리 ID(미리 보기)를 사용할 수 있습니다. 관리 ID는 Microsoft Entra 로그인이며 Azure SQL의 데이터에 액세스하려면 Azure 역할 할당이 필요합니다.

필수 조건

검색 서비스를 위한 관리 ID를 만듭니다.
SQL에서 Azure 관리자 역할을 할당합니다. 인덱서 연결에 사용되는 ID에는 읽기 권한이 필요합니다. 데이터베이스에 대한 읽기 권한을 부여하려면 SQL Database 또는 SQL Managed Instance에 서버가 있는 Microsoft Entra 관리자여야 합니다.
인덱서 개념과 구성을 잘 알고 있어야 합니다.

1 - 데이터베이스를 읽을 수 있는 권한 할당

아래 단계에 따라 데이터베이스를 읽을 수 있는 권한을 검색 서비스 또는 사용자 할당 관리 ID에 할당합니다.

Visual Studio에 연결
Microsoft Entra 계정으로 인증합니다.

다음 명령을 실행합니다.

검색 서비스 이름 또는 사용자 할당 관리 ID 이름 주위에 대괄호를 포함합니다.

CREATE USER [insert your search service name here or user-assigned managed identity name] FROM EXTERNAL PROVIDER;
EXEC sp_addrolemember 'db_datareader', [insert your search service name here or user-assigned managed identity name];

나중에 권한을 할당한 후 검색 서비스 ID 또는 사용자 할당 ID를 변경하는 경우 역할 멤버 자격을 제거하고 SQL 데이터베이스에서 사용자를 제거한 다음 권한 할당을 반복해야 합니다. 다음 명령을 실행하면 역할 멤버 자격 및 사용자를 제거할 수 있습니다.

sp_droprolemember 'db_datareader', [insert your search service name or user-assigned managed identity name];

DROP USER IF EXISTS [insert your search service name or user-assigned managed identity name];

2 - 역할 할당 추가

이 섹션에서는 Azure AI Search Service에 SQL Server에서 데이터를 읽을 수 있는 권한을 부여합니다. 세부 단계에 대해서는 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요.

Azure Portal에서 Azure SQL Server 페이지로 이동합니다.
액세스 제어(IAM) 를 선택합니다.
추가 > 역할 할당 추가를 선택합니다.
역할 탭에서 적절한 읽기 권한자 역할을 선택합니다.
멤버 탭에서 관리 ID를 선택한 다음, 멤버 선택을 선택합니다.
Azure 구독을 선택합니다.
시스템 할당 관리 ID를 사용하는 경우 시스템 할당 관리 ID를 선택하고 검색 서비스를 검색한 다음 선택합니다.
또는 사용자 할당 관리 ID를 사용 중인 경우 사용자 할당 관리 ID를 선택하고 사용자 할당 관리 ID의 이름을 검색한 다음 선택합니다.
검토 + 할당 탭에서 검토 + 할당을 선택하여 역할을 할당합니다.

3 - 데이터 원본 만들기

데이터 원본을 만들고 시스템이 할당한 관리 ID나 사용자가 할당한 관리 ID(미리 보기)를 제공합니다.

시스템 할당 관리 ID

REST API, Azure Portal, .NET SDK는 시스템 할당 관리 ID를 지원합니다.

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

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

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sql-datasource",
    "type" : "azuresql",
    "credentials" : { 
        "connectionString" : "Database=[SQL database name];ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Sql/servers/[SQL Server name];Connection Timeout=30;"
    },
    "container" : { 
        "name" : "my-table" 
    }
}

사용자가 할당한 관리 ID(미리 보기)

2021-04-30-preview REST API는 사용자 할당 관리 ID를 기반으로 연결을 지원합니다. 사용자 할당 관리 ID로 연결하는 경우 데이터 원본 정의에 두 가지 변경 내용이 있습니다.

먼저 "credentials" 속성의 형식은 계정 키나 암호가 없는 데이터베이스 이름과 ResourceId입니다. ResourceID에는 Azure SQL 데이터베이스의 구독 ID, SQL 데이터베이스의 리소스 그룹 및 SQL 데이터베이스의 이름이 포함되어야 합니다. 이는 시스템 할당 관리 ID와 동일한 형식입니다.
둘째, 사용자가 할당한 관리 ID의 컬렉션을 포함하는 ‘ID’ 속성을 추가합니다. 데이터 원본을 만들 때는 사용자가 할당한 관리 ID를 하나만 제공해야 합니다. "userAssignedIdentities" 형식으로 설정합니다.

다음은 미리 보기 데이터 원본 만들기 또는 업데이트 REST API를 사용하여 인덱서 데이터 원본 개체를 만드는 방법의 예제입니다.

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sql-datasource",
    "type" : "azuresql",
    "credentials" : { 
        "connectionString" : "Database=[SQL database name];ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Sql/servers/[SQL Server name];Connection Timeout=30;"
    },
    "container" : { 
        "name" : "my-table" 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
    }
}

4 - 인덱스 만들기

인덱스는 문서의 필드, 특성 및 검색 경험을 형성하는 기타 항목을 지정합니다.

다음은 검색 가능한 booktitle 필드가 있는 인덱스 만들기 REST API 호출입니다.

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

5 - 인덱서 만들기

인덱서는 데이터 원본을 대상 검색 인덱스와 연결하고 데이터 새로 고침을 자동화하는 일정을 제공합니다. 인덱스와 데이터 원본이 만들어지면 인덱서를 만들 준비가 된 것입니다. 인덱서가 성공하면 연결 구문과 역할 할당이 유효합니다.

다음은 Azure SQL 인덱서 정의가 있는 인덱서 만들기 REST API 호출입니다. 요청을 제출하면 인덱서가 실행됩니다.

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sql-indexer",
    "dataSourceName" : "sql-datasource",
    "targetIndexName" : "my-target-index"

문제 해결

인덱서가 클라이언트에서 서버에 액세스할 수 없다고 표시하는 데이터 원본에 연결하려고 할 때 오류가 발생하는 경우 일반적인 인덱서 오류를 살펴봅니다.

제한이 있거나 없는 연결을 시도하여 방화벽 문제를 배제할 수도 있습니다.

참고 항목

Azure SQL 인덱서