تعيينات الحقول والتحويلات باستخدام مفهرسات البحث المعرفي في Azure

مقالة
04/27/2022
قراءة خلال 9 دقائق

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

تتناول تعيينات الحقول السيناريوهات التالية:

أسماء الحقول غير المتطابقة. افترض أن مصدر البيانات يحتوي على حقل باسم _id. نظرا لأن Azure Cognitive Search لا يسمح بأسماء الحقول التي تبدأ بشرطة سفلية، فإن تعيين الحقل يتيح لك إعادة تسمية حقل بشكل فعال.
حقل واحد للعديد من الحقول. يمكنك ملء عدة حقول في الفهرس من نفس بيانات مصدر البيانات. على سبيل المثال، قد ترغب في تطبيق أدوات تحليل مختلفة على كل حقل.
العديد من الحقول إلى حقل واحد. تريد ملء حقل فهرس ببيانات من أكثر من مصدر بيانات واحد، وتستخدم كل من مصادر البيانات أسماء حقول مختلفة.
Base64 ترميز أو فك تشفير البيانات. تدعم التعيينات الميدانية العديد من وظائف رسم الخرائط، بما في ذلك وظائف ترميز وفك تشفير Base64.
تقسيم السلاسل أو إعادة صياغة صفيف JSON إلى مجموعة سلاسل. توفر وظائف رسم الخرائط الميدانية هذه القدرة.

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

ملاحظة

تنطبق تعيينات الحقول على فهارس البحث فقط. بالنسبة للمفهرسين الذين يقومون أيضا بإنشاء مخازن المعرفة، تحدد أشكال البيانات والإسقاطات اقترانات الحقول، ويتم تجاهل أي تعيينات للحقول وتعيينات حقول المخرجات في المفهرس.

إعداد تعيينات الحقول

يتكون رسم الخرائط الميدانية من ثلاثة أجزاء:

"sourceFieldName"، الذي يمثل حقلا في مصدر بياناتك. هذه الخاصية لازمة.
"targetFieldName" اختياري، يمثل حقلا في فهرس البحث. إذا تم حذفه ، يتم استخدام قيمة "sourceFieldName" للهدف.
"mappingFunction" اختياري ، والذي يمكنه تحويل بياناتك باستخدام واحدة من عدة وظائف محددة مسبقا. يمكن تطبيق ذلك على كل من تعيينات حقول الإدخال والإخراج.

تتم إضافة تعيينات الحقول إلى صفيف "تعيين الحقول" لتعريف المفهرس.

ملاحظة

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

حقول الخريطة باستخدام REST

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

على سبيل المثال، إليك كيفية تعيين حقل مصدر إلى حقل هدف باسم مختلف:

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_id", "targetFieldName" : "id" } ]
}

يمكن الرجوع إلى حقل المصدر في تعيينات حقول متعددة. يوضح المثال التالي كيفية "تشعب" حقل، ونسخ نفس حقل المصدر إلى حقلي فهرس مختلفين:


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

ملاحظة

يستخدم Azure Cognitive Search مقارنة غير حساسة لحالة الأحرف لحل أسماء الحقول والدالات في تعيينات الحقول. هذا مناسب (ليس عليك الحصول على كل الغلاف بشكل صحيح) ، ولكنه يعني أن مصدر البيانات أو الفهرس لا يمكن أن يحتوي على حقول تختلف فقط حسب الحالة.

حقول الخريطة باستخدام .NET

يمكنك تعريف تعيينات الحقول في .NET SDK باستخدام فئة FieldMapping ، التي تحتوي على خصائص "SourceFieldName" و "TargetFieldName" ، ومرجع اختياري "MappingFunction".

يمكنك تحديد تعيينات الحقول عند إنشاء المفهرس، أو في وقت لاحق عن طريق تعيين SearchIndexer.FieldMappings مباشرة.

يقوم مثال C# التالي بتعيين تعيينات الحقول عند إنشاء مفهرس.

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_id") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

وظائف رسم الخرائط الميدانية

تقوم دالة تعيين الحقل بتحويل محتويات الحقل قبل تخزينه في الفهرس. وظائف التعيين التالية مدعومة حاليا:

base64الترميز
base64فك التشفير
extractTokenAtPosition
jsonArrayToStringCollection
URLرمز
URLDECODE

base64ترميز الدالة

ينفذ ترميز Base64 الآمن لعنوان URL لسلسلة الإدخال. يفترض أن الإدخال هو UTF-8 مشفرة.

مثال: ترميز مفتاح مستند على أساس

يمكن أن تظهر الأحرف الآمنة لعنوان URL فقط في مفتاح مستند Azure Cognitive Search (بحيث يمكنك معالجة المستند باستخدام واجهة برمجة تطبيقات البحث). إذا كان الحقل المصدر للمفتاح يحتوي على أحرف غير آمنة لعنوان URL، مثل - و \، فاستخدم الدالة لتحويله في وقت الفهرسة base64Encode .

يحدد المثال التالي الدالة base64Encode على "metadata_storage_name" لمعالجة الأحرف غير المعتمدة.

PUT /indexers?api-version=2020-06-30
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

لا يمكن أن يزيد مفتاح المستند (قبل التحويل وبعده) عن 1024 حرفا. عند استرداد المفتاح المشفر في وقت البحث، استخدم الوظيفة base64Decode للحصول على قيمة المفتاح الأصلية، واستخدمها لاسترداد المستند المصدر.

مثال: جعل حقل مشفر بالأساس "قابلا للبحث"

هناك أوقات تحتاج فيها إلى استخدام إصدار مشفر من حقل مثل "metadata_storage_path" كمفتاح ، ولكنك تحتاج أيضا إلى إصدار غير مشفر للبحث عن النص الكامل. لدعم كلا السيناريوهين، يمكنك تعيين "metadata_storage_path" إلى حقلين: أحدهما للمفتاح (مشفر)، والثاني لحقل مسار يمكننا افتراض أنه "قابل للبحث" في مخطط الفهرس.

PUT /indexers/blob-indexer?api-version=2020-06-30
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

مثال - الحفاظ على القيم الأصلية

يضيف مفهرس تخزين blob تلقائيا تعيين حقل من metadata_storage_path، عنوان URI الخاص بالنقطة ، إلى حقل مفتاح الفهرس إذا لم يتم تحديد تعيين حقل. يتم ترميز هذه القيمة Base64 بحيث يكون من الآمن استخدامها كمفتاح مستند Azure Cognitive Search. يوضح المثال التالي كيفية تعيين إصدار metadata_storage_path مشفر Base64 آمن لعنوان URL في وقت واحد إلى index_key حقل والحفاظ على القيمة الأصلية في حقلmetadata_storage_path:

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

إذا لم تقم بتضمين خاصية معلمات لوظيفة التعيين، تعيينها افتراضيا إلى القيمة {"useHttpServerUtilityUrlTokenEncode" : true}.

يدعم Azure Cognitive Search ترميزين مختلفين ل Base64. يجب عليك استخدام نفس المعلمات عند ترميز وفك تشفير نفس الحقل. لمزيد من المعلومات، راجع خيارات ترميز base64 لتحديد المعلمات التي يجب استخدامها.

base64فك الشفرة وظيفة

ينفذ فك تشفير Base64 لسلسلة الإدخال. يفترض أن يكون الإدخال عبارة عن سلسلة مشفرة Base64 آمنة لعنوان URL .

مثال - فك تشفير البيانات الوصفية أو عناوين URL

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

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }]

إذا لم تقم بتضمين خاصية معلمات، تعيينها افتراضيا إلى القيمة {"useHttpServerUtilityUrlTokenEncode" : true}.

يدعم Azure Cognitive Search ترميزين مختلفين ل Base64. يجب عليك استخدام نفس المعلمات عند ترميز وفك تشفير نفس الحقل. لمزيد من التفاصيل، راجع خيارات ترميز base64 لتحديد المعلمات التي يجب استخدامها.

خيارات ترميز base64

يدعم Azure Cognitive Search ترميز base64 الآمن لعناوين URL والترميز الأساسي العادي64. يجب فك تشفير السلسلة التي يتم ترميزها بواسطة base64 أثناء الفهرسة لاحقا بنفس خيارات الترميز، وإلا فلن تتطابق النتيجة مع السلسلة الأصلية.

useHttpServerUtilityUrlTokenEncode إذا تم تعيين أو useHttpServerUtilityUrlTokenDecode معلمات الترميز وفك التشفير على التوالي إلى true، ثم base64Encode يتصرف مثل HttpServerUtility.UrlTokenEncode ويتصرف base64Decode مثل HttpServerUtility.UrlTokenDecode.

تحذير

إذا base64Encode تم استخدامه لإنتاج قيم رئيسية، useHttpServerUtilityUrlTokenEncode فيجب تعيينه إلى true. يمكن استخدام ترميز base64 الآمن لعنوان URL فقط للقيم الرئيسية. راجع قواعد التسمية للاطلاع على المجموعة الكاملة من القيود على الأحرف في القيم الرئيسية.

تفترض مكتبات .NET في Azure Cognitive Search .NET Framework الكاملة، والتي توفر ترميزا مدمجا. تستفيد useHttpServerUtilityUrlTokenEncode الخيارات والخيارات useHttpServerUtilityUrlTokenDecode من هذه الوظيفة المدمجة. إذا كنت تستخدم .NET Core أو إطار عمل آخر، فإننا نوصي بتعيين هذه الخيارات واستدعاء وظائف الترميز وفك false التشفير الخاصة بإطار العمل مباشرة.

يقارن الجدول التالي ترميزات base64 المختلفة للسلسلة 00>00?00. لتحديد المعالجة الإضافية المطلوبة (إن وجدت) لوظائف base64 الخاصة بك ، قم بتطبيق وظيفة ترميز المكتبة على السلسلة 00>00?00 وقارن الإخراج بالإخراج MDA-MDA_MDAالمتوقع .

الترميز	Base64 ترميز الإخراج	معالجة إضافية بعد ترميز المكتبة	معالجة إضافية قبل فك تشفير المكتبة
Base64 مع الحشو	`MDA+MDA/MDA=`	استخدام الأحرف الآمنة لعناوين URL وإزالة الحشو	استخدام الأحرف base64 القياسية وإضافة الحشو
Base64 بدون حشو	`MDA+MDA/MDA`	استخدام الأحرف الآمنة لعناوين URL	استخدام base64 حرفا قياسيا
قاعدة آمنة لعنوان URL64 مع الحشو	`MDA-MDA_MDA=`	إزالة الحشو	إضافة حشو
قاعدة آمنة لعناوين URL64 بدون حشو	`MDA-MDA_MDA`	بلا	بلا

استخراج وظيفة TokenAtPosition

يقسم حقل سلسلة باستخدام المحدد المحدد، ويختار الرمز المميز في الموضع المحدد في الانقسام الناتج.

تستخدم هذه الدالة المعلمات التالية:

delimiterسلسلة لاستخدامها كفاصل عند تقسيم سلسلة الإدخال.:
positionعدد صحيح يستند إلى موضع يستند إلى الصفر للرمز المميز للاختيار بعد تقسيم سلسلة الإدخال.:

على سبيل المثال ، إذا كان الإدخال هو ، هو (مسافة) و هو 0 ، والنتيجة هي ؛ إذا كان هو Jane Doe" "position 1 ، delimiter فإن النتيجة هي JaneDoe.position إذا كان الموضع يشير إلى رمز مميز غير موجود، إرجاع خطأ.

مثال - استخراج اسم

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

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

jsonArrayToStringCollection الدالة

يحول سلسلة منسقة كصفيف سلاسل JSON إلى صفيف سلسلة يمكن استخدامه لملء Collection(Edm.String) حقل في الفهرس.

على سبيل المثال ، إذا كانت سلسلة الإدخال هي ["red", "white", "blue"]، ملء حقل النوع Collection(Edm.String) المستهدف بالقيم redالثلاث ، whiteو blue. بالنسبة لقيم الإدخال التي لا يمكن تحليلها كمصفوفات سلسلة JSON، يتم إرجاع خطأ.

مثال - تعبئة المجموعة من البيانات العلائقية

لا يحتوي Azure SQL Database على نوع بيانات مضمن يقوم بشكل طبيعي بالتعيين إلى Collection(Edm.String) الحقول في Azure Cognitive Search. لملء حقول مجموعة السلسلة، يمكنك معالجة بيانات المصدر مسبقا كصفيف سلسلة JSON ثم استخدام وظيفة التعيين jsonArrayToStringCollection .

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

URLوظيفة الترميز

يمكن استخدام هذه الوظيفة لترميز سلسلة بحيث تكون "عنوان URL آمنا". عند استخدامها مع سلسلة تحتوي على أحرف غير مسموح بها في عنوان URL، ستقوم هذه الوظيفة بتحويل هذه الأحرف "غير الآمنة" إلى مكافئات لكيان الأحرف. تستخدم هذه الوظيفة تنسيق ترميز UTF-8.

مثال - البحث عن مفتاح المستند

urlEncode يمكن استخدام الدالة كبديل للوظيفة base64Encode ، إذا كان سيتم تحويل أحرف URL غير الآمنة فقط ، مع الحفاظ على الأحرف الأخرى كما هي.

لنفترض أن سلسلة الإدخال هي <hello> - ثم سيتم ملء حقل النوع (Edm.String) المستهدف بالقيمة %3chello%3e

عند استرداد المفتاح المشفر في وقت البحث، يمكنك بعد ذلك استخدام urlDecode الوظيفة للحصول على قيمة المفتاح الأصلية، واستخدام ذلك لاسترداد المستند المصدر.

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }]

urlDecode وظيفة

تقوم هذه الوظيفة بتحويل سلسلة مشفرة بواسطة عنوان URL إلى سلسلة تم فك تشفيرها باستخدام تنسيق ترميز UTF-8.

مثال - فك تشفير البيانات الوصفية للنقطة

تقوم بعض برامج تخزين Azure تلقائيا بتشفير بيانات تعريف blob إذا كانت تحتوي على أحرف غير ASCII. ومع ذلك ، إذا كنت ترغب في جعل هذه البيانات الوصفية قابلة للبحث (كنص عادي) ، فيمكنك استخدام urlDecode الوظيفة لتحويل البيانات المشفرة مرة أخرى إلى سلاسل عادية عند ملء فهرس البحث.

"fieldMappings" : [
 {
   "sourceFieldName" : "UrlEncodedMetadata",
   "targetFieldName" : "SearchableMetadata",
   "mappingFunction" : {
     "name" : "urlDecode"
   }
 }]

الثابتةالطولوظيفة الترميز

تقوم هذه الدالة بتحويل سلسلة من أي طول إلى سلسلة ثابتة الطول.

مثال - تعيين مفاتيح المستندات الطويلة جدا

عند مواجهة أخطاء تشكو من أن مفتاح المستند أطول من 1024 حرفا، يمكن تطبيق هذه الوظيفة لتقليل طول مفتاح المستند.


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }]

تعيينات الحقول والتحويلات باستخدام مفهرسات البحث المعرفي في Azure

هل هذه الصفحة مفيدة؟

إعداد تعيينات الحقول

حقول الخريطة باستخدام REST

حقول الخريطة باستخدام .NET

وظائف رسم الخرائط الميدانية

base64ترميز الدالة

مثال: ترميز مفتاح مستند على أساس

مثال: جعل حقل مشفر بالأساس "قابلا للبحث"

مثال - الحفاظ على القيم الأصلية

base64فك الشفرة وظيفة

مثال - فك تشفير البيانات الوصفية أو عناوين URL

خيارات ترميز base64

استخراج وظيفة TokenAtPosition

مثال - استخراج اسم

jsonArrayToStringCollection الدالة

مثال - تعبئة المجموعة من البيانات العلائقية

URLوظيفة الترميز

مثال - البحث عن مفتاح المستند

urlDecode وظيفة

مثال - فك تشفير البيانات الوصفية للنقطة

الثابتةالطولوظيفة الترميز

مثال - تعيين مفاتيح المستندات الطويلة جدا