將 Azure 表格儲存體中的資料編製索引
在本文中,了解如何設定索引子,以從 Azure 表格儲存體匯入內容,並將內容變成可在 Azure AI 搜尋服務中搜尋。 索引子的輸入是您在單一資料表中的實體。 輸出是搜尋索引,且各欄位中儲存可搜尋的內容和中繼資料。
本文提供從 Azure 表格儲存體編制索引的特定資訊,以補充建立索引子。 其中使用 REST API 來示範所有索引子通用的三部分工作流程:建立資料來源、建立索引、建立索引子。 提交建立索引子要求時會擷取資料。
必要條件
包含文字的資料表。 如果您使用二進位資料,請考慮使用影像分析的 AI 擴充。
Azure 儲存體的讀取權限。 「完整存取」連接字串包含存取內容所需的金鑰,但如果您使用 Azure 角色,請確定搜尋服務受控識別具有資料和讀者權限。
使用 REST 用戶端編寫接近於本文示範的 REST 呼叫。
定義資料來源
資料來源定義會指定要編製索引的資料、認證,以及變更偵測的原則。 資料來源是獨立的資源,可供多個索引子使用。
建立或更新資料來源以設定其定義:
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 儲存體連接字串。 下一節說明支援的格式。
將 "container" 設定為資料表的名稱。
選擇性地將 "query" 設定為 PartitionKey 上的篩選條件。 設定此屬性是改善效能的最佳做法。 如果 "query" 為 null,索引子會執行完整資料表掃描,如果資料表很大,則會導致效能不佳。
如果您希望索引子在來源文件標幟為刪除時,刪除時刪除搜尋文件,資料來源定義也可以包含虛刪除原則。
支援的認證和連接字串
索引子可以使用下列連線來連線到資料表。
完整存取儲存體帳戶連接字串 |
---|
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" } |
您可以在 Azure 入口網站中,從 [儲存體帳戶] 頁面的左側瀏覽窗格,選取 [存取金鑰] 取得連接字串。 請務必選取完整的連接字串,而不只是金鑰。 |
受控識別連接字串 |
---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" } |
此連接字串不需要帳戶金鑰,但您之前必須將搜尋服務設為使用受控識別連線。 |
儲存體帳戶共用存取簽章** (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)
。使用 Get Indexer Status 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,則只會使用資料列索引鍵。如果您使用「匯入資料精靈」建立索引,入口網站會推斷搜尋索引的 [Key] 欄位,並使用隱含欄位對應以連線來源和目的地欄位。 您不必自行新增欄位,也無需設定欄位對應。
如果您是使用 REST API 且想要隱含欄位對應,請在搜尋索引定義中建立名為 [Key] 文件索引鍵欄位,如同先前步驟所示 (
{ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }
)。 索引子會自動填入 [Key] 欄位,無需欄位對應。如果您不希望搜尋索引中有個名為 [Key] 的欄位,請在索引子定義中新增所需欄位名稱的明確欄位對應,並將來源欄位設為 [Key]:
"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" } ]
如需其他屬性的詳細資訊,請參閱建立索引子。
索引子建立後會自動執行。 您可以將「停用」設為 true 避免此情況。 若要控制索引子執行,請視需要執行索引子或排程執行索引子。
檢查索引子狀態
若要監視索引子狀態和執行歷程記錄,請傳送取得索引子狀態要求:
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 個最近完成的執行,以顛倒的時序排序,因此最後的執行最先出現。