نشر موصل CSV

هذا الدليل مخصّص لمشرفي أداة ربط ملفات CSV (القيم المفصولة بفواصل) في Google Cloud Search المسؤولين عن تنزيل أداة الربط وإعدادها وتشغيلها ومراقبتها.

يتضمّن هذا الدليل تعليمات حول المهام الرئيسية التالية:

  • نزِّل برنامج موصّل CSV في Cloud Search.
  • اضبط الموصّل لمصدر بيانات CSV محدّد.
  • نشِّر الموصّل وشغِّله.

لفهم المفاهيم الواردة في هذا المستند، يجب أن تكون على دراية بخدمة Google Workspace وملفات CSV وقوائم التحكّم بالوصول (ACL).

نظرة عامة على موصّل ملفات CSV في Cloud Search

يعمل موصّل ملفات CSV في Cloud Search مع أي ملف نصي يتضمّن قيمًا مفصولة بفواصل (CSV). يخزِّن ملف CSV البيانات الجدولية، حيث يمثّل كل سطر سجل بيانات.

يستخرج الموصّل الصفوف من ملف CSV ويفهرسها في Cloud Search باستخدام Indexing API. بعد الفهرسة، يمكن البحث عن الصفوف من خلال برامج Cloud Search أو واجهة برمجة التطبيقات Query API. يتيح الموصل أيضًا استخدام قوائم التحكم بالوصول للتحكّم في إذن المستخدمين بالوصول إلى المحتوى.

يمكنك تثبيت الموصل على نظام التشغيل Linux أو Windows. قبل النشر، تأكَّد من توفّر المكوّنات التالية:

عادةً، يقدّم مشرف Google Workspace للنطاق بيانات الاعتماد هذه.

خطوات النشر

اتّبِع الخطوات التالية لنشر موصّل ملفات CSV في Cloud Search:

  1. تثبيت برنامج الموصّل
  2. تحديد إعدادات الموصّل
  3. ضبط إعدادات الوصول إلى مصدر بيانات Cloud Search
  4. ضبط إذن الوصول إلى ملف CSV
  5. تحديد أسماء الأعمدة والمفاتيح الفريدة وأعمدة التاريخ والوقت
  6. تحديد أعمدة لعناوين URL القابلة للنقر في نتائج البحث
  7. تحديد البيانات الوصفية وتنسيقات الأعمدة
  8. جدولة عملية استرجاع البيانات
  9. تحديد خيارات قائمة التحكّم بالوصول

1. تثبيت حزمة تطوير البرامج (SDK)

ثبِّت حزمة SDK في مستودع Maven المحلي.

  1. استنسِخ مستودع حزمة تطوير البرامج (SDK) من GitHub. 

    $ git clone https://github.com/google-cloudsearch/connector-sdk.git
$ cd connector-sdk/csv

  2. اطّلِع على الإصدار الذي اخترته: 

    $ git checkout tags/v1-0.0.3

  3. إنشاء الموصّل: 

    $ mvn package

  4. استخرِج الموصل وثبِّته: 

    $ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip
$ cd google-cloudsearch-csv-connector-v1-0.0.3

2. تحديد إعدادات موصّل CSV

يمكنك التحكّم في سلوك أداة الربط من خلال المَعلمات في ملف الإعدادات. تشمل المَعلمات القابلة للضبط ما يلي:

  • الوصول إلى مصدر البيانات
  • موقع ملف CSV وتعريفاته
  • أعمدة المعرّف الفريد
  • خيارات التنقّل وقوائم التحكّم بالوصول

لإنشاء ملف إعداد، اتّبِع الخطوات التالية:

  1. افتح محرِّر نصوص وسمِّ الملف connector-config.properties.
  2. أضِف مَعلمات الإعداد على شكل أزواج key=value، مع وضع كل زوج في سطر جديد. للاطّلاع على مثال لملف إعداد، يُرجى الرجوع إلى مثال على ملف إعداد.

احتفظ بملف الإعداد في الدليل نفسه الذي يحتوي على الموصّل لتسهيل عملية التتبّع. لضمان تعرّف الموصّل على ملفك، حدِّد مساره في سطر الأوامر. في الحالات الأخرى، يتم ضبط الموصل تلقائيًا على connector-config.properties في الدليل المحلي. راجِع مقالة تشغيل الموصّل.

3- ضبط إذن الوصول إلى مصدر بيانات Cloud Search

يجب أن يحدّد ملف الإعداد المَعلمات اللازمة للوصول إلى مصدر بيانات Cloud Search. يجب توفير معرّف مصدر البيانات ومعرّف حساب الخدمة ومسار ملف المفتاح الخاص لحساب الخدمة.

الإعداد المَعلمة
رقم تعريف مصدر البيانات api.sourceId=1234567890abcdef

الحقل مطلوب. رقم تعريف مصدر Cloud Search الذي أعدّه مشرف Google Workspace
مسار المفتاح الخاص لحساب الخدمة api.serviceAccountPrivateKeyFile=./PrivateKey.json

الحقل مطلوب. ملف مفتاح حساب الخدمة لإمكانية وصول الموصل.
رقم تعريف مصدر الهوية api.identitySourceId=x0987654321

مطلوب في حال استخدام مستخدمين ومجموعات خارجيين رقم تعريف مصدر الهوية الذي تم إعداده من قِبل مشرف Google Workspace

4. إعداد مَعلمات ملف CSV

تحديد مسار الملف وتنسيقه وترميزه

الإعداد المَعلمة
مسار ملف CSV csv.filePath=./movie_content.csv

الحقل مطلوب. تمثّل هذه السمة المسار إلى الملف المراد فهرسته.
تنسيق الملف csv.format=DEFAULT

تمثّل هذه السمة تنسيق الملف. يجب أن تكون القيم من فئة CSVFormat في Apache Commons CSV.

تشمل قيم التنسيق: DEFAULT وEXCEL وINFORMIX_UNLOAD وINFORMIX_UNLOAD_CSV وMYSQL وRFC4180 وORACLE وPOSTGRESQL_CSV وPOSTGRESQL_TEXT وTDF. في حال عدم تحديدها، تستخدم Cloud Search DEFAULT.
معدِّل تنسيق الملف csv.format.withMethod=value

تعديل على طريقة تعامل Cloud Search مع الملف الطُرق المتاحة هي من فئة CSVFormat في Apache Commons CSV وتشمل تلك التي تقبل قيمة حرف واحد أو سلسلة أو قيمة منطقية.

على سبيل المثال، لتحديد فاصلة منقوطة كمحدد، استخدِم csv.format.withDelimiter=;. لتجاهل الأسطر الفارغة، استخدِم csv.format.withIgnoreEmptyLines=true.
نوع ترميز الملف csv.fileEncoding=UTF-8

مجموعة أحرف Java التي سيتم استخدامها يتم ضبط هذه السمة تلقائيًا على مجموعة الأحرف الخاصة بالنظام الأساسي.

5- تحديد أسماء الأعمدة المطلوب فهرستها وأعمدة المفتاح الفريد

قدِّم معلومات الأعمدة في ملف الإعداد.

الإعداد المَعلمة
الأعمدة المطلوب فهرستها csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

أسماء الأعمدة التي سيتم فهرسة البيانات منها في ملف CSV يتم تلقائيًا استخدام الصف الأول من ملف CSV كعنوان. إذا تم تحديد csv.csvColumns، ستكون لها الأولوية. لتجنُّب فهرسة الصف الأول كبيانات عند ضبط csv.csvColumns واحتواء الصف الأول على عناوين، اضبط أيضًا csv.skipHeaderRecord=true.
أعمدة المفتاح الفريد csv.uniqueKeyColumns=movieId

الأعمدة المستخدَمة لإنشاء معرّف فريد القيمة التلقائية هي رمز التجزئة الخاص بالسجلّ.

6. تحديد أعمدة لعناوين URL الخاصة بنتائج البحث القابلة للنقر

تفعيل عناوين URL قابلة للنقر في نتائج البحث

الإعداد المَعلمة
تنسيق عنوان URL الخاص بنتائج البحث url.format=https://mymoviesite.com/movies/{0}

الحقل مطلوب. التنسيق المستخدَم لإنشاء عنوان URL الخاص بالعرض
معلمات عنوان URL url.columns=movieId

الحقل مطلوب. أسماء أعمدة ملف CSV التي سيتم استخدام قيمها لإنشاء عنوان URL الخاص بعرض السجلّ.
معلَمات عناوين URL الخاصة بنتائج البحث التي يجب تجاهلها url.columnsToEscape=movieId

اختياريّ. أسماء أعمدة ملف CSV التي سيتم ترميز قيمها باستخدام عنوان URL لإنشاء عنوان URL صالح للعرض.

7. تحديد البيانات الوصفية وتنسيقات الأعمدة وجودة البحث

يمكنك إضافة مَعلمات إلى ملف الإعداد تحدّد ما يلي:

مَعلمات إعداد البيانات الوصفية

تصف هذه المَعلمات الأعمدة التي يتم ملؤها ببيانات وصفية خاصة بالسلع.

الإعداد المعلَمة
العنوان itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind

سمة البيانات الوصفية لعنوان المستند القيمة التلقائية هي سلسلة فارغة.
عنوان URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
هي سمة البيانات الوصفية الخاصة بعنوان URL للمستند في نتائج البحث.
الطابع الزمني للإنشاء itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17

سمة البيانات الوصفية للطابع الزمني لإنشاء المستند
وقت آخر تعديل itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17

سمة البيانات الوصفية الخاصة بالطابع الزمني لآخر تعديل للمستند.
لغة المستند itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US

لغة المحتوى للمستندات التي تتم فهرستها
نوع عنصر المخطط itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie

نوع العنصر الذي تستخدمه أداة الربط، كما هو محدّد في المخطط لن يفهرس الموصل أي بيانات منظَّمة إذا لم يتم تحديد هذه السمة.
تنسيقات التاريخ والوقت

تحدّد هذه المَعلمة تنسيقات إضافية للتاريخ والوقت من أجل تحليل قيم السلسلة إلى حقول التاريخ أو التاريخ والوقت.

الإعداد المعلَمة
تنسيقات إضافية للتاريخ والوقت structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
قائمة مفصولة بفواصل منقوطة تتضمّن أنماط java.time.format.DateTimeFormatter إضافية. يتم استخدام الأنماط عند تحليل قيم السلسلة لأي حقول تاريخ أو تاريخ ووقت في بيانات التعريف أو المخطط. القيمة التلقائية هي قائمة فارغة، ولكن يتم دائمًا توفير تنسيقات RFC 3339 وRFC 1123.

تنسيقات الأعمدة

تحدّد هذه المَعلمات كيفية تحليل الأعمدة في ملف CSV.

الإعداد المَعلمة
تخطّي العنوان csv.skipHeaderRecord=true

تجاهُل السطر الأول القيمة التلقائية هي "خطأ".
أعمدة متعدّدة القيم csv.multiValueColumns=genre,actors

أسماء الأعمدة التي تتضمّن قيمًا متعددة
محدّد الأعمدة المتعدّدة القيم csv.multiValue.genre=;

محدّد الأعمدة المتعددة القيم الفاصل التلقائي هو الفاصلة.

جودة البحث

يستخدم الموصل نموذج محتوى لتنسيق السجلات. يحظى حقل العنوان بالأولوية القصوى. يمكنك تحديد مستويات الأولوية (عالية أو متوسطة أو منخفضة) للحقول الأخرى.

الإعداد المَعلمة
عنوان المحتوى contentTemplate.csv.title=movieTitle

عنوان المحتوى هو الحقل الأعلى جودة في البحث.
جودة البحث العالية لحقول المحتوى contentTemplate.csv.quality.high=actors

حقول المحتوى التي تم منحها قيمة عالية لجودة البحث القيمة التلقائية هي سلسلة فارغة.
جودة البحث المنخفضة لحقول المحتوى contentTemplate.csv.quality.low=genre

حقول المحتوى التي تم منحها قيمة منخفضة لجودة البحث القيمة التلقائية هي سلسلة فارغة.
جودة بحث متوسطة لحقول المحتوى contentTemplate.csv.quality.medium=description

حقول المحتوى التي تم منحها قيمة متوسطة لجودة البحث القيمة التلقائية هي سلسلة فارغة.
حقول المحتوى غير المحدّدة contentTemplate.csv.unmappedColumnsMode=IGNORE

كيفية تعامل أداة الربط مع حقول المحتوى غير المحدّدة القيم الصالحة هي:

  • APPEND: لإلحاق حقول المحتوى غير المحدّدة بالنموذج
  • IGNORE: لتجاهل حقول المحتوى غير المحدّدة

القيمة التلقائية هي APPEND.

8. جدولة عملية استكشاف البيانات

الزحف هو عملية اكتشاف المحتوى. يتنقّل الموصّل بين صفوف ملف CSV ويفهرسها باستخدام Indexing API. لا ينفّذ موصّل CSV سوى عمليات بحث شاملة.

الإعداد المَعلمة
فاصل الاجتياز schedule.traversalIntervalSecs=7200

الفاصل الزمني بين عمليات البحث الكاملة بالثواني القيمة التلقائية هي 86400 (يوم واحد).
التنقّل عند بدء التشغيل schedule.performTraversalOnStart=false

ينفّذ الموصّل عملية اجتياز عند بدء تشغيله، بدلاً من انتظار انتهاء الفاصل الزمني الأول. القيمة التلقائية هي true.

9- تحديد خيارات قائمة التحكّم بالوصول

يستخدم Connector قوائم التحكّم بالوصول للتحكّم في الوصول. إذا كان المستودع يوفّر قوائم ACL، حمِّلها. بخلاف ذلك، اضبط قوائم ACL التلقائية. اضبط defaultAcl.mode على قيمة غير none.

الإعداد المَعلمة
وضع قائمة التحكم في الوصول defaultAcl.mode=fallback

الحقل مطلوب. لا يتيح الموصل سوى وضع الاحتياط.
اسم قائمة التحكّم بالوصول التلقائية defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

اختياريّ. تتجاوز هذه السمة اسم الحاوية الافتراضية الذي يستخدمه الموصل في قوائم التحكّم بالوصول التلقائية. تكون القيمة التلقائية DEFAULT_ACL_VIRTUAL_CONTAINER. ننصحك بتجاهل هذا الإعداد إذا كانت أدوات ربط متعددة تفهرس المحتوى في مصدر البيانات نفسه.
قائمة التحكم بالوصول العامة التلقائية defaultAcl.public=true

يضبط المستودع بأكمله على إمكانية الوصول إلى النطاق العام. القيمة التلقائية هي false.
المستخدمون الذين يمكنهم قراءة مجموعة قائمة التحكّم بالوصول (ACL) الشائعة defaultAcl.readers.groups=google:group1, group2
برامج قراءة قوائم التحكّم بالوصول الشائعة defaultAcl.readers.users=user1, user2, google:user3
رفض ACL المشترك لقراء المجموعة defaultAcl.denied.groups=group3
القراء الذين تم رفض وصولهم إلى قائمة التحكّم بالوصول الشائعة defaultAcl.denied.users=user4, user5
إذن الوصول إلى النطاق بالكامل لتحديد أن يكون كل سجل مفهرس متاحًا للجميع من قِبل كل مستخدم في النطاق، اضبط الخيارَين التاليَين على القيم:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
قائمة التحكم بالوصول (ACL) المحدّدة الشائعة لتحديد قائمة ACL مشتركة لكل سجلّ، اضبط المَعلمات التالية:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

يُفترض أنّ المستخدمين والمجموعات محدَّدة في النطاق المحلي ما لم يتم تحديد البادئة "google:".

المستخدم أو المجموعة التلقائيان هما سلسلة فارغة. لا توفِّر خيارات المستخدم والمجموعة إلا إذا كانت قيمة defaultAcl.public هي false. استخدِم قائمة مفصولة بفواصل لتحديد مجموعات ومستخدمين متعددين.

إذا كانت قيمة defaultAcl.mode هي none، لن يكون بالإمكان البحث عن السجلات بدون قوائم تحكّم بالوصول فردية.

تعريف المخطط

لإتاحة طلبات البحث عن البيانات المنظَّمة، عليك إعداد مخطط لمصدر البيانات.

على سبيل المثال، لنفترض أنّ لديك ملف CSV يتضمّن المعلومات التالية عن الأفلام:

  1. movieId
  2. movieTitle
  3. الوصف
  4. سنة
  5. releaseDate
  6. الممثلون (قيم متعدّدة مفصولة بفواصل (،))
  7. النوع (قيم متعددة)
  8. التقييمات

استنادًا إلى هذه البنية، يمكنك تحديد المخطط التالي لمصدر البيانات:

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "actors",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "textPropertyOptions": {
            "operatorOptions": {
              "operatorName": "actor"
            }
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          }
        },
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "textPropertyOptions": {
            "retrievalImportance": {
              "importance": "HIGHEST"
            },
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentary"
              },
              {
                "stringValue": "Drama"
              },
              {
                "stringValue": "Crime"
              },
              {
                "stringValue": "Sci-fi"
              }
            ]
          }
        },
        {
          "name": "userRating",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": true,
          "integerPropertyOptions": {
            "orderedRanking": "ASCENDING",
            "maximumValue": "10",
            "operatorOptions": {
              "operatorName": "score",
              "lessThanOperatorName": "scorebelow",
              "greaterThanOperatorName": "scoreabove"
            }
          }
        }
      ]
    }
  ]
}

مثال على ملف الإعداد

يوضّح ملف الإعدادات المثال التالي أزواج المَعلمات key=value التي تحدّد سلوك أداة ربط نموذجية.

# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json

# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle

# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE

#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true

تشغيل الموصّل

لتشغيل أداة الربط من سطر الأوامر، اتّبِع الخطوات التالية:

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

تتوفّر سجلّات الموصل تلقائيًا في الإخراج العادي. يمكنك تسجيل الدخول إلى الملفات من خلال تحديد logging.properties.