بيانات الفهرس من Azure Cosmos DB باستخدام واجهة برمجة تطبيقات Gremlin

  • مقالة
  • قراءة خلال 8 دقائق

هام

مفهرس واجهة برمجة تطبيقات Gremlin حاليا في المعاينة العامة ضمن شروط الاستخدام التكميلية. حاليا، لا يوجد دعم SDK.

في هذه المقالة، تعرف على كيفية تكوين مفهرس يستورد المحتوى من قاعدة بيانات Azure Cosmos ويجعله قابلا للبحث في البحث المعرفي في Azure.

تكمل هذه المقالة إنشاء مفهرس يحتوي على معلومات خاصة بواجهة برمجة تطبيقات Cosmos DB Gremlin. يستخدم واجهات برمجة تطبيقات REST لإظهار سير عمل مكون من ثلاثة أجزاء مشترك بين جميع المفهرسين: إنشاء مصدر بيانات وإنشاء فهرس وإنشاء مفهرس. يحدث استخراج البيانات عند إرسال طلب إنشاء مفهرس.

نظرا لأن المصطلحات يمكن أن تكون مربكة ، تجدر الإشارة إلى أن فهرسة Cosmos DB وفهرسةالبحث المعرفي هما عمليتان مختلفتان. تؤدي الفهرسة في البحث المعرفي إلى إنشاء فهرس بحث وتحميله على خدمة البحث.

المتطلبات الأساسية

تعريف مصدر البيانات

يحدد تعريف مصدر البيانات البيانات المراد فهرستها وبيانات اعتمادها وسياساتها لتحديد التغييرات في البيانات. يتم تعريف مصدر البيانات كمورد مستقل بحيث يمكن استخدامه من قبل مفهرسين متعددين.

بالنسبة لهذه المكالمة، حدد إصدار واجهة برمجة تطبيقات REST للمعاينة (2020-06-30-Preview أو 2021-04-30-Preview) لإنشاء مصدر بيانات يتصل باستخدام واجهة برمجة تطبيقات Gremlin.

  1. إنشاء مصدر بيانات أو تحديثه لتعيين تعريفه:

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

  2. اضبط "النوع" على "cosmosdb" (مطلوب).

  3. تعيين "بيانات الاعتماد" إلى سلسلة اتصال. يصف القسم التالي التنسيقات المدعومة.

  4. اضبط "الحاوية" على المجموعة. الخاصية "الاسم" مطلوبة وتحدد معرف الرسم البياني.

    الخاصية "استعلام" اختيارية. بشكل افتراضي، سيجعل مفهرس Azure Cognitive Search Cosmos DB Gremlin API كل قمة في الرسم البياني مستندا في الفهرس. سيتم تجاهل الحواف. الافتراضي للاستعلام هو g.V(). بدلا من ذلك، يمكنك تعيين الاستعلام لفهرسة الحواف فقط. لفهرسة الحواف، اضبط الاستعلام على g.E().

  5. قم بتعيين "dataChangeDetectionPolicy" إذا كانت البيانات متقلبة وتريد أن يلتقط المفهرس العناصر الجديدة والمحدثة فقط في عمليات التشغيل اللاحقة. سيتم تمكين التقدم التدريجي افتراضيا باستخدام _ts عمود العلامة المائية العالية.

  6. قم بتعيين "dataDeletionDetectionPolicy" إذا كنت تريد إزالة مستندات البحث من فهرس بحث عند حذف العنصر المصدر.

بيانات الاعتماد المدعومة وسلاسل الاتصال

يمكن للمفهرسين الاتصال بمجموعة باستخدام الاتصالات التالية. بالنسبة للاتصالات التي تستهدف واجهة برمجة تطبيقات 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" }
يمكنك الحصول على سلسلة الاتصال من صفحة حساب Cosmos DB في مدخل Azure عن طريق تحديد المفاتيح في جزء التنقل الأيمن. تأكد من تحديد سلسلة اتصال كاملة وليس مجرد مفتاح.
سلسلة اتصال الهوية المدارة
{ "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 أذونات دور قارئ الحساب . راجع إعداد اتصال مفهرس بقاعدة بيانات Cosmos باستخدام هوية مدارة للحصول على مزيد من المعلومات.

إضافة حقول بحث إلى فهرس

في فهرس البحث، أضف حقولا لقبول مستندات JSON المصدر أو مخرجات إسقاط الاستعلام المخصص. تأكد من توافق مخطط فهرس البحث مع الرسم البياني. بالنسبة للمحتوى في قاعدة بيانات Cosmos، يجب أن يتوافق مخطط فهرس البحث مع عناصر قاعدة بيانات Azure Cosmos في مصدر البيانات.

  1. إنشاء فهرس أو تحديثه لتحديد حقول البحث التي ستخزن البيانات:

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

  2. إنشاء حقل مفتاح مستند ("المفتاح": true). بالنسبة للمجموعات المقسمة، يكون مفتاح المستند الافتراضي هو خاصية _rid Azure Cosmos DB، والتي يقوم Azure Cognitive Search تلقائيا بإعادة تسميتها rid لأن أسماء الحقول لا يمكن أن تبدأ بحرف تسطير سفلي. أيضا، تحتوي قيم قاعدة بيانات _rid Azure Cosmos على أحرف غير صالحة في مفاتيح البحث المعرفي في Azure. لهذا السبب، _rid يتم ترميز القيم Base64.

  3. أنشئ حقولا إضافية للحصول على محتوى أكثر قابلية للبحث. راجع إنشاء فهرس للحصول على التفاصيل.

تعيين أنواع البيانات

نوع بيانات JSON أنواع حقول البحث المعرفي
قيمة منطقية Edm.Boolian ، Edm.String
الأرقام التي تبدو وكأنها أعداد صحيحة Edm.Int32, Edm.Int64, Edm.String
الأرقام التي تبدو وكأنها نقاط عائمة Edm.Double, Edm.String
سلسلة Edm.String
صفائف من الأنواع البدائية مثل ["أ"، "ب"، "ج"] مجموعة (Edm.String)
السلاسل التي تبدو وكأنها تواريخ Edm.DateTimeOffset, Edm.String
كائنات GeoJSON مثل { "النوع": "نقطة"، "الإحداثيات": [طويل، lat] } Edm.GeographyPoint
كائنات JSON الأخرى غير متوفر

تكوين مفهرس قاعدة بيانات Cosmos وتشغيله

بمجرد إنشاء الفهرس ومصدر البيانات، تصبح جاهزا لإنشاء المفهرس. يحدد تكوين المفهرس المدخلات والمعلمات والخصائص التي تتحكم في سلوكيات وقت التشغيل.

  1. إنشاء مفهرس أو تحديثه عن طريق إعطائه اسما والرجوع إلى مصدر البيانات والفهرس المستهدف:

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

  2. حدد تعيينات الحقول إذا كانت هناك اختلافات في اسم الحقل أو نوعه، أو إذا كنت بحاجة إلى إصدارات متعددة من حقل مصدر في فهرس البحث.

  3. راجع إنشاء مفهرس لمزيد من المعلومات حول الخصائص الأخرى.

يتم تشغيل المفهرس تلقائيا عند إنشائه. يمكنك منع ذلك عن طريق تعيين "معطل" إلى true. للتحكم في تنفيذ المفهرس، قم بتشغيل مفهرس عند الطلب أو وضعه على جدول زمني.

التحقق من حالة المفهرس

لمراقبة حالة المفهرس ومحفوظات التنفيذ، أرسل طلب الحصول على حالة المفهرس :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  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" في تعريف مصدر البيانات. تخبر هذه الخاصية المفهرس بآلية تتبع التغييرات المستخدمة في بياناتك.

بالنسبة لمفهرسات قاعدة بيانات Cosmos، فإن النهج الوحيد المدعوم هو HighWaterMarkChangeDetectionPolicy استخدام _ts الخاصية (الطابع الزمني) التي يوفرها Azure Cosmos DB.

يوضح المثال التالي تعريف مصدر بيانات مع نهج اكتشاف التغيير:

"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=2020-06-30-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"
    }
}

تعيين بيانات الرسم البياني إلى حقول في فهرس بحث

سيقوم مفهرس واجهة برمجة تطبيقات Cosmos DB Gremlin تلقائيا بتعيين قطعتين من بيانات الرسم البياني لك:

  1. سيقوم المفهرس بتعيين _ridrid حقل في الفهرس إذا كان موجودا، ويقوم Base64 بترميزه.

  2. سيقوم المفهرس بتعيين _idid حقل في الفهرس إذا كان موجودا.

  3. عند الاستعلام عن قاعدة بيانات Cosmos DB باستخدام واجهة برمجة تطبيقات Gremlin ، قد تلاحظ أن إخراج JSON لكل خاصية idvalueيحتوي على و . سيقوم مفهرس Azure Cognitive Search Cosmos DB تلقائيا بتعيين الخصائص 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"
          }
        ]
      }
    ]

إذا كنت ترغب في تعيين قيمة pages في JSON أعلاه إلى حقل في الفهرس، فيمكنك إضافة تعيين حقل المخرجات التالي إلى totalpages تعريف المفهرس:

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

لاحظ كيف يبدأ تعيين حقل الإخراج ب /document ولا يتضمن مرجعا إلى مفتاح الخصائص في JSON. وذلك لأن المفهرس يضع كل مستند تحت العقدة عند استيعاب بيانات الرسم البياني ويسمح لك المفهرس أيضا تلقائيا بالإشارة إلى قيمة pages عن طريق الرجوع pages إلى مرجع بسيط بدلا من الاضطرار إلى الإشارة إلى الكائن /document الأول في صفيف pages.

الخطوات التالية