在 Azure AI 搜尋服務 中為查詢將 Azure Cosmos DB for MongoDB 中的資料編製索引（預覽）

Azure Cosmos DB for MongoDB indexer（預覽版）會從 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 集合上的 自動索引政策，設定為 Consistent。 此設定為預設配置。 不建議懶惰地編入索引，可能會導致資料遺失。

• 閱讀權限。 「完整存取」連接字串包含授與內容存取權的金鑰，但如果您使用 Azure 角色，請確定搜尋服務受控識別具有 Cosmos DB Account Reader Role 權限。

• 一個 REST 客戶端 用來建立資料來源、索引和索引器。

限制

以下是此功能的限制：

• 不支援自訂查詢來指定資料集。

• 專欄名稱 _ts 為保留詞。 如果你需要這個欄位，可以考慮其他填入索引的解決方案。

• MongoDB 屬性 $ref 是一個保留詞。 如果你需要在 MongoDB 集合中使用它，可以考慮其他填入索引的解決方案。

作為此連接器的替代方案，如果你的情境有上述需求，可以考慮使用 Push API/SDK，或考慮使用 Azure Data Factory，並搭配 Azure AI 搜尋服務 index 作為匯入。

定義資料來源

資料來源定義指定了索引資料、憑證及識別資料變更的政策。 資料來源被定義為獨立的資源，以便多個索引器都能使用。

此呼叫時，指定預覽版 REST API 以建立可透過 MongoDB API 連接的資料來源。 你可以用 2020-06-30-preview ，也可以以後再用。 我們推薦 使用最新的預覽版 REST API。

1. 建立或更新資料來源 以設定其定義：

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

2. 將「type」設為 "cosmosdb" （必需）。

3. 將「credentials」設為連線字串。 下一節將介紹所支援的格式。

4. 將「container」添加到集合中。 「name」屬性是必填的，並指定要索引的資料庫集合的 ID。 對於 Azure Cosmos DB for MongoDB，「query」不被支援。

5. 如果資料是不穩定的，且你希望索引器在後續執行中只偵測新項目和更新項目，請設定「dataChangeDetectionPolicy」。

6. 如果你想在刪除來源項目時從搜尋索引中移除搜尋文件，請設定「dataDeletionDetectionPolicy」。

支援的憑證與連線字串

索引器可以透過以下連線連接到集合。 針對 MongoDB API 的連線，請務必在連接字串中加入「ApiKind」。

避免在端點網址中顯示埠號。 如果您包含連接埠號碼，連線將會失敗。

在索引中新增搜尋欄位

在 搜尋索引中，新增欄位以接受原始 JSON 文件或自訂查詢投影的輸出。 確保搜尋索引結構與來源資料相容。 對於Azure Cosmos DB內容，你的搜尋索引結構應該對應於資料來源中的Azure Cosmos DB項目。

1. 建立或更新索引，以定義儲存資料的搜尋欄位：

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

2. 建立文件鍵欄位（「鍵」：真）。 對於基於 MongoDB 集合的搜尋索引，文件鍵可以是「doc_id」、「rid」或其他包含唯一值的字串欄位。 只要雙方欄位名稱與資料類型相同，就不需要欄位映射。

   • 「doc_id」代表物件識別碼的「_id」。 如果你在索引中指定「doc_id」欄位，索引器會用物件識別碼的值填充該欄位。

   • 「rid」是 Azure Cosmos DB 中的一個系統屬性。 如果你在索引中指定「rid」欄位，索引器會用 base64 編碼的「rid」屬性值填充該欄位。

   • 對於其他欄位，你的搜尋欄位應該與集合中定義的名稱相同。

3. 新增欄位以提供更多可搜尋的內容。 詳情請參見 建立索引 。

映射資料類型

設定和執行 Azure Cosmos DB 的 MongoDB 索引器

一旦索引和資料來源建立完成，你就可以開始建立索引器了。 索引器配置指定控制執行時行為的輸入、參數與屬性。

1. 透過命名索引器並引用資料來源與目標索引，建立或更新它：

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

2. 如果欄位名稱或類型有差異，或搜尋索引中需要多個來源欄位版本，請指定欄位對應。

3. 請參閱 建立索引器 以了解更多其他屬性的資訊。

索引器在建立時會自動執行。 你可以把「停用」設為 true，來避免這種情況。 要控制索引器的執行，請按 需求執行索引器 或 將其列入排程。

檢查索引器狀態

要監控索引器狀態與執行歷史，請發送 「取得索引器狀態 」請求：

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-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-08-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 擷取內容的索引器：

• 利用 managed identity 設定索引器連線到 Azure Cosmos DB 資料庫
• 索引大型資料集
• 索引器存取受Azure網路安全功能保護的內容