Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
重要
Azure Cosmos DB for MongoDB 索引器目前處於公開預覽階段,並受 Microsoft Azure 預覽補充使用條款的約束。
有關此功能專屬的預覽條款,請參閱 預覽功能。
Azure Cosmos DB for MongoDB 索引器(預覽版)會從 Azure Cosmos DB for MongoDB 匯入內容,並使其可於 Foundry IQ 中搜尋。
本文補充建立索引子,並提供 Cosmos DB 專屬資訊。 它使用 REST API 展示所有索引器共有的三步驟工作流程:建立資料來源、建立索引、建立索引器。 資料擷取發生在你提交建立索引器請求時。
由於術語容易令人困惑,值得一提的是,Azure Cosmos DB 索引與 Foundry IQ 索引是不同的操作。 Foundry IQ 中的索引作業會在您的 Foundry IQ 服務中建立並載入搜尋索引。
先決條件
請填寫 索引預覽註冊表單。 報名會自動通過。
一個Azure Cosmos DB帳戶、資料庫、收藏及文件。 同時使用相同區域來使用Foundry IQ和Azure Cosmos DB,以降低延遲並避免頻寬費用。
Azure Cosmos DB 集合上的 自動索引政策,設定為 Consistent。 此設定為預設配置。 不建議懶惰地編入索引,可能會導致資料遺失。
閱讀權限。 「完全存取」連接字串 包含可授與內容存取權的金鑰,但如果您使用 Azure 角色,請確保 Foundry IQ 服務受控識別具有 Cosmos DB 帳戶讀取者角色權限。
一個 REST 客戶端 用來建立資料來源、索引和索引器。
限制
以下是此功能的限制:
不支援自訂查詢來指定資料集。
專欄名稱
_ts為保留詞。 如果你需要這個欄位,可以考慮其他填入索引的解決方案。MongoDB 屬性
$ref是一個保留詞。 如果你需要在 MongoDB 集合中使用它,可以考慮其他填入索引的解決方案。
作為這個連接器的替代方案,如果你的情境有上述任何一項需求,你可以使用 Push API/SDK,或考慮使用 Azure Data Factory,並以 Foundry IQ 索引作為接收端。
定義資料來源
資料來源定義指定了索引資料、憑證及識別資料變更的政策。 資料來源被定義為獨立的資源,以便多個索引器都能使用。
此呼叫時,指定預覽版 REST API 以建立可透過 MongoDB API 連接的資料來源。 你可以用 2020-06-30-preview ,也可以以後再用。 我們推薦 使用最新的預覽版 REST API。
建立或更新資料來源 以設定其定義:
POST https://[service name].search.windows.net/datasources?api-version=2026-11-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]" }, "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」。
避免在端點網址中顯示埠號。 如果您包含連接埠號碼,連線將會失敗。
| 完整存取連接字串 |
|---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" } |
| 你可以從Azure入口網站的Azure Cosmos DB帳戶頁面選擇左側窗格的Connection String取得Cosmos DB 認證金鑰。 記得複製 主密碼 ,並替換 Cosmos DB 認證金鑰 值。 |
| 管理身份連接字串 |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" } |
| 此 連接字串 不需要帳戶金鑰,但您必須先設定 Foundry IQ 服務使用受控識別進行連線,並建立角色指派,授與 Cosmos DB 帳戶讀取者角色 權限。 更多資訊請參見 使用受控身分識別設定索引器連接至 Azure Cosmos DB 資料庫。 |
在索引中新增搜尋欄位
在 搜尋索引中,新增欄位以接受原始 JSON 文件或自訂查詢投影的輸出。 確保搜尋索引結構與來源資料相容。 對於Azure Cosmos DB內容,你的搜尋索引結構應該對應於資料來源中的Azure Cosmos DB項目。
建立或更新索引 以定義儲存資料的搜尋欄位:
POST https://[service name].search.windows.net/indexes?api-version=2026-11-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 }] }建立文件鍵欄位(「鍵」:真)。 對於基於 MongoDB 集合的搜尋索引,文件鍵可以是「doc_id」、「rid」或其他包含唯一值的字串欄位。 只要雙方欄位名稱與資料類型相同,就不需要欄位映射。
「doc_id」代表物件識別碼的「_id」。 如果你在索引中指定「doc_id」欄位,索引器會用物件識別碼的值填充該欄位。
「rid」是 Azure Cosmos DB 中的一個系統屬性。 如果你在索引中指定「rid」欄位,索引器會用 base64 編碼的「rid」屬性值填充該欄位。
對於其他欄位,你的搜尋欄位應該與集合中定義的名稱相同。
新增欄位以提供更多可搜尋的內容。 詳情請參見 建立索引 。
映射資料類型
| JSON 資料型別 | Foundry IQ 欄位類型 |
|---|---|
| Bool | Edm.Boolean、Edm.String |
| 看起來像整數的數字 | Edm.Int32、Edm.Int64、Edm.String |
| 看起來像浮點數的數字 | Edm.Double、Edm.String |
| 弦 | 埃德姆·斯特林 |
| 原始型態陣列如 [“a”、“b”、“c”] | Collection(Edm.String) |
| 看起來像日期的字串 | Edm.DateTimeOffset, Edm.String |
| GeoJSON 物件如 { “type”: “Point”, “coordinates”: [long, lat] } | Edm.GeographyPoint |
| 其他 JSON 物件 | 無 |
設定和執行 Azure Cosmos DB 的 MongoDB 索引器
一旦索引和資料來源建立完成,你就可以開始建立索引器了。 索引器配置指定控制執行時行為的輸入、參數與屬性。
透過命名索引器並參考資料來源與目標索引,建立或更新它:
POST https://[service name].search.windows.net/indexers?api-version=2026-11-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 }如果欄位名稱或類型有差異,或在搜尋索引中需要多個來源欄位版本,請指定欄位對應。
請參閱 建立索引器 以了解更多其他屬性的資訊。
索引器在建立時會自動執行。 你可以把「停用」設為 true,來避免這種情況。 要控制索引器的執行,請按 需求執行索引器 或 將其列入排程。
檢查索引器狀態
要監控索引器狀態與執行歷史,請發送 「取得索引器狀態 」請求:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-11-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 索引子,唯一支援的原則是 HighWaterMarkChangeDetectionPolicy,並使用 Azure Cosmos DB 提供的 _ts (時間戳記) 屬性。
以下範例展示了帶有變更偵測政策的資料 來源定義 :
"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=2026-11-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 擷取內容的索引器: