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

發行項
11/23/2024

在本文中，了解如何設定索引子，從 Azure Cosmos DB for NoSQL 匯入內容，並使其可在 Azure AI 搜尋服務中搜尋。

本文提供 Cosmos DB 的特定資訊，用於補充建立索引子。它會使用 Azure 入口網站和 REST API 來示範所有索引器通用的三部分工作流程：建立數據源、建立索引、建立索引器。提交建立索引子要求時會擷取資料。

因為術語可能會令人混淆，所以請注意 Azure Cosmos DB 編製索引和 Azure AI 搜尋服務編製索引是不同的作業。 Azure AI 搜尋服務中的編製索引會在您的搜尋服務上建立並載入搜尋索引。

必要條件

Azure Cosmos DB 帳戶、資料庫、容器和項目。針對 Azure AI 搜尋服務和 Azure Cosmos DB 使用相同的區域來降低延遲，並避免產生頻寬費用。
Azure Cosmos DB 集合上的自動索引編製原則，已設定為一致。這是預設設定。不建議延遲索引編製，其可能會導致資料遺失。
讀取權限。「完整存取」連接字串包含可授與內容的存取權的密鑰，但如果您使用身分識別（Microsoft Entra ID），請確定搜尋服務受控識別已獲指派 Cosmos DB 帳戶讀取者角色和 Cosmos DB 內建數據讀取者角色。

若要完成本文中的範例，您需要 Azure 入口網站或 REST 用戶端。如果您使用 Azure 入口網站，請確定已啟用所有公用網路的存取權。建立 Cosmos DB 索引器的其他方法包括 Azure SDK。

嘗試使用範例數據

使用這些指示在 Cosmos DB 中建立容器和資料庫以供測試之用。

從 GitHub 下載HotelsData_toCosmosDB.JSON ，以在 Cosmos DB 中建立容器，其中包含範例旅館數據集的子集。
登入 Azure 入口網站，並在 Cosmos DB 上建立帳戶、資料庫和容器。

在 Cosmos DB 中，選取 新容器的數據 總管，提供下列值。

屬性	值
Database	新建
資料庫識別碼	hotelsdb
跨容器共用輸送量	請勿選取
容器識別碼	旅館
分割區索引鍵	/HotelId
容器輸送量 (自動縮放)	Autoscale
容器最大 RU/秒	1000

在 [數據總管] 中，展開 hotelsdb 和 *hotels“，然後選取 [ 專案]。
選取 [ 上傳專案 ]，然後選取 您從 GitHub 下載HotelsData_toCosmosDB.JSON 檔案。
以滑鼠右鍵按兩下 [專案 ]，然後選取 [ 新增 SQL 查詢]。預設查詢為 SELECT * FROM c。
選取 [ 執行查詢 ] 以執行查詢並檢視結果。您應該有 50 份旅館檔。

既然您已擁有容器，您可以使用 Azure 入口網站、REST 用戶端或 Azure SDK 來編製數據的索引。

[描述] 欄位提供最詳細的內容。您應該將此欄位設為全文搜索和選擇性向量查詢的目標。

使用 Azure 入口網站

您可以使用 [ 匯入數據 精靈] 或 [匯入及向量化數據 精靈]，從 SQL 資料庫數據表或檢視表自動編制索引。這兩個精靈的數據源組態很類似。

啟動精靈。
在 [連線到您的數據] 上，選取或確認數據源類型為 Azure Cosmos DB 或 NoSQL 帳戶。

數據源名稱是指 Azure AI 搜尋服務中的數據源連接物件。如果您使用向量精靈，則會使用精靈工作流程結尾指定的自定義前置詞自動產生數據源名稱。
指定資料庫名稱和集合。查詢是選擇性的。如果您有階層式數據，而且想要匯入特定配量，這會很有用。
指定驗證方法，可以是受控識別或內建 API 金鑰。如果您未指定受控識別連線，入口網站會使用密鑰。

如果您將 Azure AI 搜尋設定為使用受控識別，並在 Cosmos DB 上建立角色指派，以授與 Cosmos DB 帳戶讀取器和 Cosmos DB 內建數據讀取器身分識別的身分識別許可權，您的索引器可以使用 Microsoft Entra ID 和角色來連線到 Cosmos DB。
針對 [ 匯入和向量化數據 精靈]，您可以指定變更和刪除追蹤的選項。

根據預設_ts，透過欄位支援變更偵測（時間戳）。如果您使用 Try with 範例數據中所述的方法上傳內容，則會使用 _ts 字段建立集合。

刪除偵測需要您在集合中具有預先存在的最上層字段，才能做為虛刪除旗標。它應該是布爾值欄位（您可以將它命名為 IsDeleted）。指定 true 為虛刪除值。在搜尋索引中，新增名為 IsDeleted的 對應搜尋欄位，以擷取和篩選。
繼續進行其餘步驟以完成精靈：
- 快速入門：匯入數據精靈
- 快速入門：匯入和向量化數據精靈

使用 REST API

本節示範建立數據源、索引和索引器之 REST API 呼叫。

定義資料來源

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

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

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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"。
將 "credentials" 設定為連接字串。下一節說明支援的格式。
將 "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=2024-07-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 for NoSQL 索引子

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

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

POST https://[service name].search.windows.net/indexers?api-version=2024-07-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 避免此情況。若要控制索引子執行，請視需要執行索引子或排程執行索引子。

檢查索引子狀態

若要監視索引器狀態和執行歷程記錄，請檢查 Azure 入口網站中的索引器執行歷程記錄，或傳送取得索引器狀態 REST APIrequest

入口網站
REST

在搜尋服務頁面上，開啟 [搜尋管理>索引器]。
選取索引器以存取組態和執行歷程記錄。
選取特定的索引器作業，以檢視詳細數據、警告和錯誤。

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":"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"
},

注意

當您將 null 值指派給 Azure Cosmos DB 中的欄位時，AI 搜尋索引子無法區分 null 和遺漏的欄位值。因此，如果索引中的欄位是空的，它就不會取代為 null 值，即使該修改是在資料庫中特別進行的也一樣。

累加式索引編製與自訂查詢

如果您使用自訂查詢來擷取文件，請確定查詢會依 _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=2024-07-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 參考文件，以在受控程式碼中實作 JSON 索引子：

下一步

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

共用方式為