從 Azure Cosmos DB for MongoDB 索引資料，以在 Azure AI 搜尋服務中進行查詢

發行項
06/29/2024

重要

MongoDB API 支援目前處於公開預覽狀態，須遵守補充條款。目前沒有 SDK 支援。

在本文中，了解如何設定索引子，從 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 集合上的自動索引編製原則，已設定為一致。這是預設設定。不建議延遲索引編製，而且可能會導致資料遺失。
讀取權限。「完整存取」連接字串包含授權存取內容所需的金鑰，但如果您使用 Azure 角色，請確定搜尋服務受控識別具有 MySQL 上的 Cosmos DB 帳戶讀者角色權限。
用來建立資料源、索引和索引子的 REST 用戶端。

限制

這些是此功能的限制：

自訂查詢不支援指定資料集。
資料行名稱 _ts 是保留字。如果您需要此欄位，請考慮使用替代解決方案來填入索引。
MongoDB 屬性 $ref 是保留字。如果您在 MongoDB 集合中需要此保留字，請考慮使用替代解決方案來填入索引。

作為此連接器的替代方案，如果您的使用情況有上述任何需求，您可以使用推送 API/SDK，或考慮使用 Azure Data Factory 搭配 Azure AI 搜尋服務索引作為接收器。

定義資料來源

資料來源定義指定要編製索引的資料、認證，以及用於識別資料變更的原則。資料來源定義為獨立的資源，因此可供多個索引子使用。

針對此呼叫，請指定預覽 REST API 版本。您可以使用 2020-06-30-preview 或更新版本來建立透過 MongoDB API 連線的資料來源。我們建議最新的預覽版 REST API。

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

POST https://[service name].search.windows.net/datasources?api-version=2024-05-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]",
    "query": null
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null,
  "identity": null
}

將「type」設定為 "cosmosdb" (必要)。
將「credentials」設定為連接字串。下一節說明支援的格式。
將 "container" 設定為集合。需要 "name" 屬性，並指定要編製索引的資料庫集合識別碼。 Azure Cosmos DB for MongoDB 不支援 "query"。
如果資料具有變動性，而且您希望索引子在後續執行時只挑選最新和更新的項目，請設定 "dataChangeDetectionPolicy"。
如果希望來源項目刪除後從搜尋索引中移除搜尋檔，請設定 "dataDeletionDetectionPolicy"。

支援的認證和連接字串

索引子可以使用下列連線來連線到集合。針對以 MongoDB API為目標的連線，請務必在連接字串中包含 "ApiKind"。

請避免在端點 URL 中使用連接埠號碼。如果您包含埠號碼，連線將會失敗。

完整存取連接字串
`{ "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 帳戶頁面，選取左側瀏覽窗格中的 [連接字串]，以取得 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];)" }`
此連接字串不需要帳戶金鑰，但您先前必須設定搜尋服務以使用受控識別進行連線，並建立授與 Cosmos DB 帳戶讀取者角色許可權的角色指派。如需詳細資訊，請參閱使用受控識別設定 Azure Cosmos DB 資料庫的索引子連線。

將搜尋欄位新增至索引

在搜尋索引中，新增欄位以接受來源 JSON 文件或自訂查詢投影的輸出。確定搜尋索引結構描述與來源資料相容。針對 Azure Cosmos DB 中的內容，您的搜尋索引結構描述應對應至資料來源中的 Azure Cosmos DB 項目。

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

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

建立文件索引鍵欄位 ("key": true)。針對以 MongoDB 集合為基礎的搜尋索引，文件索引鍵可以是 "doc_id"、"rid" 或包含唯一值的部分其他字串欄位。只要兩端的欄位名稱和資料類型都相同，就不需要欄位對應。
- "doc_id" 代表物件識別碼的 "_id"。如果您在索引中指定 "doc_id" 的欄位，索引子會填入物件識別碼的值。
- "rid" 是 Azure Cosmos DB 中的系統屬性。如果您在索引中指定 "rid" 的欄位，索引子會填入 "rid" 屬性的 base64 編碼值。
- 對於任何其他欄位，搜尋欄位的名稱應該與集合中所定義的名稱相同。
建立其他欄位以取得更多可搜尋的內容。如需詳細資訊，請參閱建立索引。

對應資料類型

JSON 資料類型	Azure AI 搜尋服務欄位類型
Bool	Edm.Boolean、Edm.String
看起來像是整數的數字	Edm.Int32、Edm.Int64、Edm.String
看起來像是浮點的數字	Edm.Double、Edm.String
String	Edm.String
基本類型的陣列，例如 ["a"、"b"、"c"]	Collection(Edm.String)
看起來像是日期的字串	Edm.DateTimeOffset、Edm.String
GeoJSON 物件，例如 { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
其他 JSON 物件	N/A

設定和執行 Azure Cosmos DB for MongoDB 索引子

建立索引與資料來源之後，您就可以開始建立索引子。索引子會設定指定輸入、參數和屬性，控制執行階段行為。

建立或更新索引子，指定其名稱並參考資料來源和目標索引：

POST https://[service name].search.windows.net/indexers?api-version=2024-05-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=2024-05-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 索引子，唯一支援的原則是使用 _ts (時間戳記) Azure Cosmos DB 所提供屬性的 HighWaterMarkChangeDetectionPolicy。

下列範例顯示具有變更偵測原則的資料來源定義：

"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=2024-05-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 提取內容的索引子：

共用方式為