從適用於 NoSQL 的 Azure Cosmos DB 匯入數據，以在 Azure AI 搜尋中查詢

發行項
02/06/2024

在本文中，瞭解如何設定索引器，以從適用於 NoSQL 的 Azure Cosmos DB 匯入內容，並使其可在 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 RBAC（Microsoft Entra ID），請確定搜尋服務受控識別同時獲指派 Cosmos DB 帳戶讀取者角色和 Cosmos DB 內建數據讀取者角色。
用來建立數據源、索引和索引器之 REST 用戶端。

定義數據源

數據源定義會指定要用來識別數據變更之索引、認證和原則的數據。數據源是可供多個索引器使用的獨立資源。

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

POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
      "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": {
      "name": "[my-cosmos-db-collection]",
      "query": null
    },
    "dataChangeDetectionPolicy": {
      "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "  highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": null,
    "encryptionKey": null,
    "identity": null
}

將「type」設定為 "cosmosdb" （必要）。如果您使用舊版搜尋 API 2017-11-11，則 “type” 的語法為 "documentdb"。否則，針對 2019-05-06 和更新版本，請使用 "cosmosdb"。
將「認證」設定為連接字串。下一節說明支援的格式。
將「container」設定為集合。需要「name」屬性，並指定要編製索引的資料庫集合標識碼。 “query” 屬性是選擇性的。使用它將任意 JSON 檔扁平化為 Azure AI 搜尋可編製索引的一般架構。
如果數據是動態的，而且您希望索引器在後續執行時只挑選新的和更新的專案，請設定 “dataChangeDetectionPolicy ”。
如果您想要在刪除來源專案時，從搜尋索引中移除搜尋檔，請設定「dataDeletionDetectionPolicy 」。

支援的認證和連接字串

索引器可以使用下列連接連接到集合。

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

完整存取連接字串
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>`" }'
您可以從 Azure 入口網站中的 [Azure 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];)/(IdentityAuthType=[identity-auth-type])" }`
此連接字串不需要帳戶密鑰，但您必須擁有可使用受控識別進行連線的搜尋服務。針對以 SQL API 為目標的連線，您可以從連接字串省略`ApiKind`。如需的詳細資訊 `ApiKind`， `IdentityAuthType` 請參閱使用受控識別設定 Azure Cosmos DB 資料庫的索引器連線。

使用查詢來塑造已編製索引的數據

在「container」底下的「query」屬性中，您可以指定 SQL 查詢來扁平化巢狀屬性或數位、專案 JSON 屬性，以及篩選要編制索引的數據。

範例文件︰

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

篩選查詢：

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

扁平化查詢：

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

投影查詢：

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

陣列扁平化查詢：

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

不支援的查詢（DISTINCT 和 GROUP BY）

不支援使用 DISTINCT 關鍵詞或 GROUP BY 子句的查詢。 Azure AI 搜尋依賴 SQL 查詢分頁來完整列舉查詢的結果。 DISTINCT 關鍵詞或 GROUP BY 子句都與用來分頁結果的接續令牌不相容。

不支援的查詢範例：

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

雖然 Azure Cosmos DB 有因應措施可支援使用 ORDER BY 子句搭配 DISTINCT 關鍵詞的 SQL 查詢分頁，但它與 Azure AI 搜尋不相容。此查詢會傳回單一 JSON 值，而 Azure AI 搜尋會預期 JSON 物件。

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

將搜尋欄位新增至索引

在搜尋索引中，新增字段以接受來源 JSON 檔或自定義查詢投影的輸出。確定搜尋索引架構與源數據相容。針對 Azure Cosmos DB 中的內容，您的搜尋索引架構應該對應至數據源中的 Azure Cosmos DB 專案。

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

POST https://[service name].search.windows.net/indexes?api-version=2023-11-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

建立文件索引鍵欄位（“key”： true）。針對分割集合，默認檔索引鍵是 Azure Cosmos DB _rid 屬性，Azure AI 搜尋會自動重新命名， rid 因為功能變數名稱不能以底線字元開頭。此外，Azure Cosmos DB _rid 值也包含 Azure AI 搜尋金鑰中無效的字元。因此，這些 _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 索引器

建立索引和數據源之後，您就可以開始建立索引器。索引器組態會指定控制運行時間行為的輸入、參數和屬性。

藉由提供名稱並參考數據源和目標索引，建立或更新索引器：

POST https://[service name].search.windows.net/indexers?api-version=2023-11-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-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=2023-11-01
  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 使用 _ts Azure Cosmos DB 所提供的（timestamp）屬性。

下列範例顯示具有變更偵測原則的數據源定義：

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

累加式索引編製和自定義查詢

如果您使用自定義查詢來擷取檔，請確定查詢會依 _ts 數據行排序結果。這可讓 Azure AI 搜尋用來在失敗時提供累加進度的定期檢查點。

在某些情況下，即使您的查詢包含子 ORDER BY [collection alias]._ts 句，Azure AI 搜尋可能不會推斷查詢是由排序的 _ts。您可以藉由設定 assumeOrderByHighWaterMarkColumn 組態屬性，告訴 Azure AI 搜尋會排序結果。

若要指定此提示，請建立或更新索引器定義，如下所示：

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

編製已刪除文件的索引

從集合中刪除資料列時，您通常也想要從搜尋索引中刪除那些數據列。數據刪除偵測原則的目的是要有效率地識別已刪除的數據項。目前，唯一支持的原則是 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 參考的屬性是由查詢投影。

softDeleteColumnName必須是索引中的最上層欄位。不支援在複雜數據類型 softDeleteColumnName 中使用巢狀欄位。

下列範例會建立具有虛刪除原則的數據源：

POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "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"
    }
}

使用 .NET

針對透過 SQL API 通訊協定存取的數據，您可以使用 .NET SDK 來自動化索引器。建議您檢閱先前的 REST API 區段，以瞭解概念、工作流程和需求。然後，您可以參考下列 .NET API 參考檔，以在Managed 程式代碼中實作 JSON 索引器：

下一步

您現在可以控制如何執行索引器、監視狀態或排程索引器執行。下列文章適用於從 Azure Cosmos DB 提取內容的索引器：