Azure Table Storage에서 데이터 인덱싱

아티클
11/23/2024

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

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

필수 조건

Azure Table Storage
텍스트를 포함하는 테이블. 이진 파일 데이터가 있는 경우 이미지 분석을 위해 AI 보강을 고려합니다.
Azure Storage에 대한 읽기 권한. "모든 액세스" 연결 문자열 콘텐츠에 대한 액세스를 제공하는 키가 포함되어 있지만 Azure 역할을 사용하는 경우 검색 서비스 관리 ID에 읽기 권한자 및 데이터 액세스 권한이 있는지 확인합니다.

이 문서의 예제를 진행하려면 Azure Portal 또는 REST 클라이언트가 필요합니다. Azure Portal을 사용하는 경우 모든 공용 네트워크에 대한 액세스가 사용하도록 설정되어 있는지 확인합니다. Azure Table Indexer를 만들기 위한 다른 방법은 Azure SDK를 포함합니다.

샘플 데이터 사용해 보기

다음 지침을 사용하여 테스트 목적으로 Azure Storage에서 테이블을 만듭니다.

Azure Portal에 로그인하고, 스토리지 계정으로 이동하고, 호텔이라는 테이블을 만듭니다.
Azure Storage Explorer를 설치합니다.
GitHub에서 HotelsData_toAzureSearch.csv 다운로드합니다. 이 파일은 기본 제공 호텔 샘플 데이터 세트의 하위 집합입니다. 객실 컬렉션, 번역된 설명 및 지리 좌표를 생략합니다.
Azure Storage Explorer에서 Azure에 로그인하고, 구독을 선택한 다음, 스토리지 계정을 선택합니다.
테이블을 열고 호텔을 선택합니다.
명령 모음에서 가져오기를 선택한 다음, HotelsData_toAzureSearch.csv 파일을 선택합니다.
기본값을 그대로 적용합니다. 가져오기를 선택하여 데이터를 로드합니다.

테이블에 자동 생성된 partitionKey, rowKey 및 타임스탬프가 있는 50개의 호텔 레코드가 있어야 합니다. 이제 이 콘텐츠를 Azure Portal, REST 클라이언트 또는 Azure SDK에서 인덱싱에 사용할 수 있습니다.

설명 필드는 가장 자세한 내용을 제공합니다. 전체 텍스트 검색 및 선택적 벡터 쿼리에 대해 이 필드를 대상으로 지정해야 합니다.

Azure Portal 사용

데이터 가져오기 마법사 또는 데이터 가져오기 및 벡터화 마법사를 사용하여 SQL 데이터베이스 테이블 또는 뷰에서 인덱싱을 자동화할 수 있습니다. 데이터 원본 구성은 두 마법사 모두에 대해 유사합니다.

마법사 시작.
데이터에 연결 시 데이터 원본 형식이 Azure Table Storage인지 또는 데이터 선택 필드가 테이블에 대한 프롬프트인지를 선택하거나 확인합니다.

데이터 원본 이름은 Azure AI Search의 데이터 원본 연결 개체를 나타냅니다. 벡터 마법사를 사용하는 경우 마법사 워크플로의 끝에 지정된 사용자 지정 접두사를 사용하여 데이터 원본 이름이 자동으로 생성됩니다.
스토리지 계정 및 테이블 이름을 지정합니다. 쿼리는 선택 사항입니다. 가져오려는 특정 열이 있는 경우 유용합니다.
인증 방법(관리 ID 또는 기본 제공 API 키)을 지정합니다. 관리 ID 연결을 지정하지 않으면 Azure Portal에서 키를 사용합니다.

관리 ID를 사용하도록 Azure AI Search를 구성하고 Id에 대한 읽기 권한자 및 데이터 액세스 권한을 부여하는 Azure Storage에서 역할 할당을 만드는 경우 인덱서는 Microsoft Entra ID 및 역할을 사용하여 테이블 스토리지에 연결할 수 있습니다.
데이터 가져오기 및 벡터화 마법사의 경우 삭제 검색 옵션을 지정할 수 있습니다.

삭제 검색을 수행하려면 테이블에 일시 삭제 플래그로 사용할 수 있는 기존 필드가 있어야 합니다. 부울 필드여야 합니다(IsDeleted로 이름을 지정할 수 있음). 일시 삭제 값으로 지정 true 합니다. 검색 인덱스에서 검색 가능하고 필터링 가능한 IsDeleted 집합이라는 해당 검색 필드를 추가합니다.
나머지 단계를 계속 진행하여 마법사를 완료합니다.
- 빠른 시작: 데이터 가져오기 마법사
- 빠른 시작: 데이터 가져오기 및 벡터화 마법사

REST API 사용

이 섹션에서는 데이터 원본, 인덱스 및 인덱터를 만드는 REST API 호출을 보여 줍니다.

데이터 원본 정의

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

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

 POST https://[service name].search.windows.net/datasources?api-version=2024-07-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
 }

"type"을 "azuretable"(필수)으로 설정합니다.
“credentials”를 Azure Storage 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.
"container"를 테이블 이름으로 설정합니다.
필요에 따라 "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> 상태를 정기적으로 업데이트합니다.
- 이 방법을 사용할 경우 전체 다시 인덱싱을 트리거해야 할 때 인덱서를 다시 설정하는 것 외에도 데이터 원본 쿼리를 다시 설정해야 합니다.

인덱스에 검색 필드 추가

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

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

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

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

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

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

검색 인덱스에서 “키”라는 필드를 사용하지 않으려면 원본 필드를 “키”로 설정하여 원하는 필드 이름으로 인덱서 정의에 명시적 필드 매핑을 추가합니다.
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]
```
이제 인덱스에서 원하는 다른 엔터티 필드를 추가합니다. 예를 들어, 엔터티가 다음 예와 같은 경우 검색 인덱스에 해당 값을 수신할 HotelName, Description, Category 필드가 있어야 합니다.

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

테이블 인덱서 구성 및 실행

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

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

POST https://[service name].search.windows.net/indexers?api-version=2024-07-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,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다. 대상 필드는 검색 인덱스의 필드 이름입니다.
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]
```
다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요.

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

인덱서 상태 확인

인덱서 상태 및 실행 기록을 모니터링하려면 Azure Portal에서 인덱서 실행 기록을 확인하거나 인덱서 상태 REST APIrequest 가져오기를 보냅니다.

포털
REST (영문)

검색 서비스 페이지에서 검색 관리>인덱서를 엽니다.
구성 및 실행 기록에 액세스할 인덱서 선택
세부 정보, 경고 및 오류를 보려면 특정 인덱서 작업을 선택합니다.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-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에서 콘텐츠를 가져오는 인덱서에 적용됩니다.

다음을 통해 공유