Azure Table Storage에서 데이터 인덱싱

이 문서에서는 Azure Table Storage에서 콘텐츠를 가져오고 Azure AI Search에서 검색할 수 있도록 만드는 인덱서를 구성하는 방법에 대해 알아봅니다. 인덱서에 대한 입력은 단일 테이블의 엔터티입니다. 출력은 개별 필드에 저장된 검색 가능한 콘텐츠 및 메타데이터가 포함된 검색 인덱스입니다.

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

필수 조건

• Azure Table Storage

• 텍스트를 포함하는 테이블. 이진 파일 데이터가 있는 경우 이미지 분석을 위해 AI 보강을 고려합니다.

• Azure Storage에 대한 읽기 권한. "모든 권한" 연결 문자열에는 콘텐츠에 대한 액세스 권한을 부여하는 키가 포함되지만 Azure 역할을 사용하는 경우 검색 서비스 관리 ID에 데이터 및 읽기 권한자 권한이 있는지 확인합니다.

• 이 문서에 표시된 것과 유사한 REST 호출을 작성하려면 REST 클라이언트를 사용합니다.

데이터 원본 정의

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

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

    POST https://[service name].search.windows.net/datasources?api-version=2023-11-01 
    {
        "name": "my-table-storage-ds",
        "description": null,
        "type": "azuretable",
        "subtype": null,
        "credentials": {
           "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
        },
        "container": {
           "name": "my-table-in-azure-storage",
           "query": ""
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null,
        "encryptionKey": null,
        "identity": null
    }
   

2. "type"을 "azuretable"(필수)으로 설정합니다.

3. “credentials”를 Azure Storage 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.

4. "container"를 테이블 이름으로 설정합니다.

5. 필요에 따라 "query"를 PartitionKey의 필터로 설정합니다. 이 속성을 설정하는 것은 성능을 향상시키는 모범 사례입니다. “query”가 null인 경우 인덱서는 전체 테이블 검사를 실행하므로 테이블이 큰 경우 성능이 저하될 수 있습니다.

원본 문서가 삭제 플래그가 지정되었을 때 인덱서가 검색 문서를 삭제하도록 하려면 데이터 원본 정의에 일시 삭제 정책도 포함될 수 있습니다.

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

인덱서는 다음 연결을 사용하여 테이블에 연결할 수 있습니다.

전체 액세스 스토리지 계정 연결 문자열
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
왼쪽 탐색 창에서 액세스 키를 선택하여 Azure Portal의 스토리지 계정 페이지에서 연결 문자열을 가져올 수 있습니다. 키 외에도 전체 연결 문자열을 선택해야 합니다.

관리 ID 연결 문자열
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
이 연결 문자열에는 계정 키가 필요하지 않지만 이전에 관리 ID를 사용하여 연결하도록 검색 서비스를 구성해야 합니다.

스토리지 계정 공유 액세스 서명**(SAS) 연결 문자열
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }
SAS에는 테이블 및 엔터티에 대한 목록 및 읽기 권한이 있어야 합니다.

컨테이너 공유 액세스 서명
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }
SAS에 컨테이너에 대한 읽기 권한 및 목록이 있어야 합니다. 자세한 내용은 공유 액세스 서명 사용을 참조하세요.

참고 항목

SAS 자격 증명을 사용하는 경우 자격 증명이 만료되는 것을 방지하기 위해 갱신된 서명을 사용하여 데이터 원본 자격 증명을 주기적으로 업데이트해야 합니다. SAS 자격 증명이 만료되면 “연결 문자열에 제공된 사용자 자격 증명이 잘못되었거나 만료되었습니다.”와 유사한 오류 메시지와 함께 인덱서가 실패합니다.

성능 개선을 위한 파티션

기본적으로 Azure AI 검색은 다음 내부 쿼리 필터를 사용하여 마지막 실행(Timestamp >= HighWaterMarkValue) 이후 업데이트된 원본 엔터티를 추적합니다. Azure 테이블의 Timestamp 필드에는 보조 인덱스가 없으므로 이러한 유형의 쿼리는 전체 테이블 검색을 요구합니다. 따라서 대형 테이블에서 속도가 느려집니다.

전체 검사를 방지하려면 테이블 파티션을 사용하여 각 인덱서 작업의 범위를 좁힐 수 있습니다.

• 데이터가 기본적으로 여러 파티션 범위로 분할될 수 있으면 각 파티션 범위에 대한 데이터 원본 및 해당 인덱서를 만듭니다. 이제 각 인덱서는 특정 파티션 범위만 처리하면 되므로 쿼리 성능이 개선됩니다. 인덱싱해야 하는 데이터에 작은 수의 고정 파티션이 있으면 각 인덱서는 파티션 검색만 수행하면 됩니다.

  예를 들어 000에서 100 사이의 키를 갖는 파티션 범위를 처리하는 데이터 원본을 만들려면 다음과 같은 쿼리를 사용합니다. "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }

• 데이터는 시간별으로 분할하는 경우(예를 들어 새 파티션을 매일 또는 매주 만드는 경우) 다음과 같은 접근 방식을 고려해 보세요.

  • 데이터 원본 정의에서 다음 예와 유사한 조회를 지정합니다. (PartitionKey ge <TimeStamp>) and (other filters).

  • 인덱서 상태 가져오기 API를 사용하여 인덱서 진행률을 모니터링하고 최근의 성공적인 상위 워터 마크 값을 기준으로 쿼리의 <TimeStamp> 상태를 정기적으로 업데이트합니다.

  • 이 방법을 사용할 경우 전체 다시 인덱싱을 트리거해야 할 때 인덱서를 다시 설정하는 것 외에도 데이터 원본 쿼리를 다시 설정해야 합니다.

인덱스에 검색 필드 추가

검색 인덱스에서 테이블 엔터티의 콘텐츠와 메타데이터를 허용하는 필드를 추가합니다.

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

   POST https://[service name].search.windows.net/indexes?api-version=2023-11-01 
   {
     "name" : "my-search-index",
     "fields": [
       { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
       { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
     ]
   }
   

2. 문서 키 필드("key": true)를 만들지만 인덱서가 자동으로 채우도록 허용합니다. 테이블 인덱서는 테이블의 연결된 파티션과 행 키로 키 필드를 채웁니다. 예를 들어, 행의 PartitionKey가 1이고 RowKey가 1_123이면 키 값은 11_123입니다. 파티션 키가 null이면 행 키만 사용됩니다.

   데이터 가져오기 마법사를 사용하여 인덱스를 만드는 경우 포털은 검색 인덱스에 대한 “키” 필드를 유추하고 암시적 필드 매핑을 사용하여 원본 및 대상 필드를 연결합니다. 필드를 직접 추가할 필요가 없으며 필드 매핑을 설정할 필요가 없습니다.

   REST API를 사용하고 암시적 필드 매핑을 원하는 경우 이전 단계({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false })와 같이 검색 인덱스 정의에서 문서 키 필드 “키”를 만들고 이름을 지정합니다. 인덱서는 필드 매핑 없이 키 필드를 자동으로 채웁니다.

   검색 인덱스에서 “키”라는 필드를 사용하지 않으려면 원본 필드를 “키”로 설정하여 원하는 필드 이름으로 인덱서 정의에 명시적 필드 매핑을 추가합니다.

    "fieldMappings" : [
      {
        "sourceFieldName" : "Key",
        "targetFieldName" : "MyDocumentKeyFieldName"
      }
   ]
   

3. 이제 인덱스에서 원하는 다른 엔터티 필드를 추가합니다. 예를 들어, 엔터티가 다음 예와 같은 경우 검색 인덱스에 해당 값을 수신할 HotelName, Description, Category 필드가 있어야 합니다.

   

   동일한 이름과 호환되는 데이터 형식을 사용하면 필드 매핑의 필요성이 최소화됩니다. 이름과 형식이 같으면 인덱서는 데이터 경로를 자동으로 확인할 수 있습니다.

테이블 인덱서 구성 및 실행

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

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

   POST https://[service name].search.windows.net/indexers?api-version=2023-11-01
   {
       "name" : "my-table-indexer",
       "dataSourceName" : "my-table-storage-ds",
       "targetIndexName" : "my-search-index",
       "disabled": null,
       "schedule": null,
       "parameters" : {
           "batchSize" : null,
           "maxFailedItems" : null,
           "maxFailedItemsPerBatch" : null,
           "base64EncodeKeys" : null,
           "configuration" : { }
       },
       "fieldMappings" : [ ],
       "cache": null,
       "encryptionKey": null
   }
   

2. 필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다. 대상 필드는 검색 인덱스의 필드 이름입니다.

    "fieldMappings" : [
      {
        "sourceFieldName" : "Description",
        "targetFieldName" : "HotelDescription"
      }
   ]
   

3. 다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요.

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

인덱서 상태 확인

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

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

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

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

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

다음 단계

인덱서를 실행하거나, 상태를 모니터링하거나, 인덱서 실행을 예약하는 방법에 대해 자세히 알아봅니다. 다음 문서는 Azure Storage에서 콘텐츠를 가져오는 인덱서에 적용됩니다.

• 자습서: Azure Storage에서 JSON Blob 인덱싱
• 자습서: Azure Storage에서 암호화된 Blob 인덱싱