Azure AI 검색의 쿼리를 위해 Azure Cosmos DB for MongoDB에서 데이터 인덱싱

아티클
09/03/2024

Important

MongoDB API 지원은 현재 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 현재 SDK는 지원되지 않습니다.

이 문서에서는 Azure Cosmos DB for MongoDB에서 콘텐츠를 가져오고 Azure AI 검색에서 검색할 수 있게 해 주는 인덱서를 구성하는 방법을 알아봅니다.

이 문서는 Cosmos DB와 관련된 정보로 인덱서 만들기를 보완합니다. REST API를 사용하여 모든 인덱서에 공통적인 세 부분으로 구성된 워크플로(데이터 원본 만들기, 인덱스 만들기, 인덱서 만들기)를 보여 줍니다. 데이터 추출은 인덱서 만들기 요청을 제출할 때 발생합니다.

용어가 혼동될 수 있으므로 Azure Cosmos DB 인덱싱과 Azure AI 검색 인덱싱은 서로 다른 작업임에 유의해야 합니다. Azure AI 검색의 인덱싱은 검색 서비스에서 검색 인덱스를 만들고 로드합니다.

필수 조건

시나리오 피드백을 제공하려면 미리 보기에 등록합니다. 양식 제출 후 자동으로 기능에 액세스할 수 있습니다.
Azure Cosmos DB 계정, 데이터베이스, 컬렉션 및 문서. 대기 시간을 줄이고 대역폭 요금이 부과되지 않도록 하려면 Azure AI 검색과 Azure Cosmos DB 모두에 동일한 지역을 사용합니다.
일관성 있음으로 설정된 Azure Cosmos DB 컬렉션의 자동 인덱싱 정책. 이것은 기본 구성입니다. 지연 인덱싱은 권장되지 않으며 데이터가 누락될 수 있습니다.
읽기 권한. "모든 권한" 연결 문자열에는 콘텐츠에 대한 액세스 권한을 부여하는 키가 포함되지만, Azure 역할을 사용하는 경우 검색 서비스 관리 ID에 Cosmos DB 계정 읽기 권한자 역할 권한이 있는지 확인합니다.
데이터 원본, 인덱스 및 인덱서를 만들기 위한 REST 클라이언트입니다.

제한 사항

이 기능의 제한 사항은 다음과 같습니다.

사용자 지정 쿼리는 데이터 세트를 지정하는 데 지원되지 않습니다.
_ts 열 이름은 예약어입니다. 이 필드가 필요한 경우 인덱스를 채우기 위한 대체 솔루션을 고려합니다.
MongoDB 특성 $ref는 예약어입니다. MongoDB 컬렉션에서 필요한 경우 인덱스를 채우기 위한 대체 솔루션을 고려합니다.

이 커넥터의 대안으로 시나리오에 이러한 요구 사항이 있는 경우 푸시 API/SDK를 사용하거나 Azure AI 검색 인덱스가 있는 Azure Data Factory를 싱크로 간주할 수 있습니다.

데이터 원본 정의

데이터 원본 정의는 인덱싱할 데이터, 자격 증명 및 데이터 변경 내용을 식별하기 위한 정책을 지정합니다. 데이터 원본은 여러 인덱서에서 사용할 수 있도록 독립적인 리소스로 정의됩니다.

이 호출의 경우 미리 보기 REST API 버전을 지정합니다. 2020-06-30-preview 이상을 사용하여 MongoDB API를 통해 연결하는 데이터 원본을 만들 수 있습니다. 최신 미리 보기 REST API를 사용하는 것이 좋습니다.

데이터 원본을 만들거나 업데이트하여 정의를 설정합니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
  "name": "[my-cosmosdb-mongodb-ds]",
  "type": "cosmosdb",
  "credentials": {
    "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
  },
  "container": {
    "name": "[cosmos-db-collection]",
    "query": null
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null,
  "identity": null
}

"type"을 "cosmosdb"(필수)으로 설정합니다.
"credentials"를 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.
"container"를 컬렉션으로 설정합니다. "name" 속성은 필요이며 인덱싱할 데이터베이스 컬렉션의 ID를 지정합니다. Azure Cosmos DB for MongoDB의 경우 "query"는 지원되지 않습니다.
데이터가 휘발성이고 후속 실행 시 인덱서에서 새 항목과 업데이트된 항목만 선택하도록 하려면 "dataChangeDetectionPolicy"를 설정합니다.
원본 항목이 삭제될 때 검색 인덱스에서 검색 문서를 제거하려면 "dataDeletionDetectionPolicy"를 설정합니다.

지원되는 자격 증명 및 연결 문자열

인덱서는 다음 연결을 사용하여 컬렉션에 연결할 수 있습니다. MongoDB API를 대상으로 하는 연결의 경우 "ApiKind"를 연결 문자열에 포함해야 합니다.

엔드포인트 URL에서 포트 번호를 사용하지 않습니다. 포트 번호가 포함되면 연결이 실패합니다.

모든 권한 연결 문자열
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }`
왼쪽 탐색 창에서 연결 문자열을 선택하여 Azure Portal의 Azure Cosmos DB 계정 페이지에서 Cosmos DB 인증 키를 가져올 수 있습니다. 주 암호를 복사하고 Cosmos DB 인증 키 값을 이 암호로 바꿔야 합니다.

관리 ID 연결 문자열
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }`
이 연결 문자열에는 계정 키가 필요하지 않지만, 이전에 관리 ID를 사용하여 연결하도록 검색 서비스를 구성하고 Cosmos DB 계정 읽기 권한자 역할 권한을 부여하는 역할 할당을 만들었어야 합니다. 자세한 내용은 관리 ID를 사용하여 Azure Cosmos DB 데이터베이스에 대한 인덱서 연결 설정을 참조하세요.

인덱스에 검색 필드 추가

검색 인덱스에서 원본 JSON 문서 또는 사용자 지정 쿼리 프로젝션의 출력을 허용하는 필드를 추가합니다. 검색 인덱스 스키마가 원본 데이터와 호환되는지 확인합니다. Azure Cosmos DB 콘텐츠의 경우 검색 인덱스 스키마는 데이터 원본의 Azure Cosmos DB 항목과 일치해야 합니다.

인덱스를 만들거나 업데이트하여 데이터를 저장할 검색 필드를 정의합니다.

POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "mysearchindex",
    "fields": [{
        "name": "doc_id",
        "type": "Edm.String",
        "key": true,
        "retrievable": true,
        "searchable": false
    }, {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }]
}

문서 키 필드("key": true)를 만듭니다. MongoDB 컬렉션을 기반으로 하는 검색 인덱스의 경우 문서 키는 "doc_id", "rid" 또는 고유한 값을 포함하는 다른 문자열 필드일 수 있습니다. 필드 이름과 데이터 형식이 양쪽에서 동일하면 필드 매핑이 필요하지 않습니다.
- "doc_id"는 개체 식별자에 대한 "_id"를 나타냅니다. 인덱스에서 "doc_id" 필드를 지정하면 인덱서에서 필드를 개체 식별자 값으로 채웁니다.
- "rid"는 Azure Cosmos DB의 시스템 속성입니다. 인덱스에서 "rid" 필드를 지정하면 인덱서에서 필드를 "rid" 속성의 base64로 인코딩된 값으로 채웁니다.
- 다른 필드의 경우 검색 필드는 컬렉션에 정의된 이름과 동일해야 합니다.
더 검색 가능한 콘텐츠를 위해 추가 필드를 만듭니다. 자세한 내용은 인덱스 만들기를 참조하세요.

데이터 형식 매핑

JSON 데이터 형식	Azure AI 검색 필드 형식
Bool	Edm.Boolean, Edm.String
정수와 같이 보이는 숫자	Edm.Int32, Edm.Int64, Edm.String
부동소수점처럼 보이는 숫자	Edm.Double, Edm.String
문자열	Edm.String
기본 형식의 배열(예: ["a", "b", "c"])	Collection(Edm.String)
날짜처럼 보이는 문자열	Edm.DateTimeOffset, Edm.String
GeoJSON 개체(예: { "type": "Point", "coordinates": [long, lat] })	Edm.GeographyPoint
기타 JSON 개체	해당 없음

Azure Cosmos DB for MongoDB 인덱서 구성 및 실행

인덱스와 데이터 원본이 만들어지면 인덱서를 만들 준비가 된 것입니다. 인덱서 구성은 런타임 동작을 제어하는 입력, 매개 변수 및 속성을 지정합니다.

이름을 지정하고 데이터 원본 및 대상 인덱스를 참조하여 인덱서를 만들거나 업데이트합니다.

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-mongodb-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.
다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요.

인덱서가 만들어지면 자동으로 실행됩니다. 이는 "disabled"를 true로 설정하여 방지할 수 있습니다. 인덱서 실행을 제어하려면 요청 시 인덱서를 실행하거나 일정에 배치합니다.

인덱서 상태 확인

인덱서 상태 및 실행 기록을 모니터링하려면 인덱서 상태 가져오기 요청을 보냅니다.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

응답에는 상태 및 처리된 항목 수가 포함됩니다. 다음 예와 유사해야 합니다.

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

실행 기록에는 최대 50개의 가장 최근에 완료된 실행이 포함되며, 가장 최근의 실행이 먼저 나오도록 시간 역순으로 정렬됩니다.

새 문서 및 변경된 문서 인덱싱

인덱서에서 검색 인덱스가 완전히 채워지면 후속 인덱서 실행에서 데이터베이스의 새 문서와 변경된 문서만 증분 방식으로 인덱싱할 수 있습니다.

증분 인덱싱을 사용하도록 설정하려면 데이터 원본 정의에서 "dataChangeDetectionPolicy" 속성을 설정합니다. 이 속성은 데이터에 사용되는 변경 내용 추적 메커니즘을 인덱서에 알려줍니다.

Azure Cosmos DB 인덱서의 경우 지원되는 유일한 정책은 Azure Cosmos DB에서 제공하는 _ts(타임스탬프) 속성을 사용하는 HighWaterMarkChangeDetectionPolicy입니다.

다음 예제에서는 변경 검색 정책이 있는 데이터 원본 정의를 보여 줍니다.

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

삭제된 문서 인덱싱

컬렉션에서 행이 삭제된 경우 일반적으로 검색 인덱스에서도 해당 행을 삭제하려고 할 것입니다. 데이터 삭제 감지 정책의 목적은 변경된 데이터 항목을 효율적으로 식별하는 것입니다. 현재 지원되는 유일한 정책은 다음과 같이 데이터 원본 정의에 지정된 Soft Delete 정책(삭제가 일종의 플래그로 표시됨)입니다.

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

사용자 지정 쿼리를 사용하는 경우 softDeleteColumnName에서 참조하는 속성이 쿼리에서 프로젝션되는지 확인합니다.

다음 예제에서는 일시 삭제 정책을 사용하여 데이터 원본을 만듭니다.

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": ["my-cosmosdb-mongodb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

다음 단계

이제 인덱서를 실행하거나, 상태를 모니터링하거나 인덱서 실행을 예약하는 방법을 제어할 수 있습니다. 다음 문서는 Azure Cosmos DB에서 콘텐츠를 가져오는 인덱서에 적용됩니다.

다음을 통해 공유