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

文章
09/03/2024

重要

Azure Cosmos DB for Apache Gremlin 索引子目前處於公開預覽狀態，並遵循補充使用規定。目前沒有 SDK 支援。

在本文中，了解如何設定索引子，從 Azure Cosmos DB for Apache Gremlin 匯入內容，並使其可在 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 用戶端。

定義資料來源

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

針對此呼叫，請指定預覽 REST API 版本，以建立透過 Azure Cosmos DB for Apache Gremlin 連線的資料來源。您可以使用 2021-04-01-preview 或更新版本。我們建議最新的預覽版 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-gremlin-ds]",
   "type": "cosmosdb",
   "credentials": {
     "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;"
   },
   "container": {
     "name": "[cosmos-db-collection]",
     "query": "g.V()"
   },
   "dataChangeDetectionPolicy": {
     "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
     "highWaterMarkColumnName": "_ts"
   },
   "dataDeletionDetectionPolicy": null,
   "encryptionKey": null,
   "identity": null
 }
 }

將「type」設定為 "cosmosdb" (必要)。
將「credentials」設定為連接字串。下一節說明支援的格式。
將「container」設定為集合。「name」為必要屬性，且會指定圖形的識別碼。

「query」是選擇性屬性。根據預設，適用於 Azure Cosmos DB for Apache Gremlin 的 Azure AI 搜尋服務索引子會讓圖形中的每個頂點成為索引中的文件。將會忽略邊緣。查詢預設為 g.V()。或者，您可以將查詢設定為僅編製邊緣的索引。若要編製邊緣的索引，請將查詢設定為 g.E()。
如果資料具有變動性，而且您希望索引子在後續執行時只挑選最新和更新的項目，請設定「dataChangeDetectionPolicy」。累加式進度預設會使用 _ts 做為高水位線資料行來啟用。
如果希望當來源項目刪除時，從搜尋索引中移除搜尋檔，請設定「dataDeletionDetectionPolicy」。

支援的認證和連接字串

索引子可以使用下列連線來連線到集合。針對以 Azure Cosmos DB for Apache Gremlin 為目標的連線，請務必在連接字串中包含「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 帳戶] 頁面，在左側瀏覽窗格中選取 [金鑰]，以取得連接字串。請務必選取完整的連接字串，而不只是金鑰。

受控識別連接字串
`{ "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": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     },{
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

建立文件索引鍵欄位 ("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=2024-05-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-gremlin-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"
}

下列範例會建立包含虛刪除原則的資料來源：

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

即使您啟用刪除偵測原則，還是不支援從索引中刪除複雜的 (Edm.ComplexType) 欄位。此原則要求 Gremlin 資料庫中的 'active' 資料行須屬於整數、字串或布林值類型。

將圖形資料對應至搜尋索引中的欄位

Azure Cosmos DB for Apache Gremlin 索引子會自動對應幾個圖形資料：

如果索引子存在，索引子就會將 _rid 對應至索引中的 rid 欄位，並將其以 Base64 編碼。
如果索引子存在，索引子就會將 _id 對應至索引中的 id 欄位。
使用 Azure Cosmos DB for Apache Gremlin 查詢 Azure Cosmos DB 資料庫時，您可能會注意到，每個屬性的 JSON 輸出都有 id 和 value。索引子會自動將屬性 value 對應至搜尋索引中具有與屬性 (如果屬性存在的話) 相同名稱的欄位。在下列範例中，450 會對應至搜尋索引中的 pages 欄位。

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

您可能會發現需要使用輸出欄位對應，才能將查詢輸出對應至索引中的欄位。您可能要使用輸出欄位對應，而不是欄位對應，因為自訂查詢可能會包含複雜的資料。

例如，假設您的查詢產生此輸出：

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

如果您想要將上述 JSON 中的 pages 值對應至索引中的 totalpages 欄位，您可以將下列輸出欄位對應新增至索引子定義：

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

請注意輸出欄位對應以 /document 做為開頭的方式，且不包含 JSON 中屬性索引鍵的參考。這是因為索引子在擷取圖形資料時，會將每個文件放在 /document 節點底下，且索引子也會自動讓您藉由簡單的參考 pages 來參考 pages 的值，而不必參考 pages 陣列中的第一個物件。

下一步

若要深入了解 Azure Cosmos DB for Apache Gremlin，請參閱 Azure Cosmos DB 簡介：Azure Cosmos DB for Apache Gremlin。
如需 Azure AI 搜尋服務案例和定價的詳細資訊，請參閱 azure.microsoft.com 上的搜尋服務頁面。
若要了解索引子的網路設定，請參閱索引子存取受 Azure 網路安全性功能保護的內容。

分享方式：