نشر موصل CSV

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

يتضمّن هذا الدليل تعليمات لتنفيذ المهام الرئيسية المتعلّقة بنشر محوِّل CSV:

• تنزيل برنامج موصل ملف CSV في Google Cloud Search
• ضبط الموصّل لاستخدامه مع مصدر بيانات CSV معيّن
• نشر الموصّل وتشغيله

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

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

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

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

يمكن تثبيت موصل CSV في Google Cloud Search على نظام التشغيل Linux أو Windows. قبل نشر محوِّل ملفات CSV في Google Cloud Search، تأكَّد من توفُّر المكوّنات المطلوبة التالية:

• تثبيت Java JRE 1.8 على جهاز كمبيوتر يعمل بتنسيق CSV موصِّل Google Cloud Search

• معلومات Google Workspace المطلوبة لإنشاء علاقات بين Google Cloud Search ومصدر البيانات:

  • مفتاح Google Workspace الخاص (الذي يحتوي على رقم تعريف حساب الخدمة)
  • رقم تعريف مصدر بيانات Google Workspace

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

خطوات النشر

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

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

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

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

1. استنسِخ مستودع حزمة SDK من GitHub.

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

2. اطّلِع على الإصدار المطلوب من حزمة تطوير البرامج (SDK):

   $ git checkout tags/v1-0.0.3

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

   $ mvn package

4. انسخ ملف zip الخاص بالموصّل إلى دليل التثبيت على الجهاز:

   $ 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 و سماته التي تحدّد المَعلمات في ملف إعدادات الموصّل. تشمل المَعلمات القابلة للضبط ما يلي:

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

لكي يتمكّن الموصّل من الوصول إلى ملف CSV بشكل صحيح وفهرسة المحتوى ذي الصلة، يجب أولاً إنشاء ملف الإعدادات الخاص به.

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

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

بما أنّه يمكنك تحديد مسار ملف الإعدادات في سطر الأوامر، ليس من الضروري تحديد موقع ملف عادي. ومع ذلك، عليك الاحتفاظ بملف الإعدادات في الدليل نفسه الذي يتضمّن الموصِّل لتبسيط عملية تتبُّع الموصِّل وتشغيله.

لضمان تعرّف الموصّل على ملف الإعداد، حدِّد مساره في سطر الأوامر. وإلا، سيستخدم الموصّل connector-config.properties في دليلك المحلي كاسم الملف default. للحصول على معلومات عن تحديد مسار الإعداد على سطر الأوامر، يُرجى الاطّلاع على تشغيل أداة ربط ملف CSV في Cloud Search.

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

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

4. ضبط مَعلمات ملف CSV

قبل أن يتمكّن الموصّل من التنقّل في ملف CSV واستخراج البيانات منه بهدف الفهرسة، عليك تحديد مسار الملف. يمكنك أيضًا تحديد تنسيق الملف ونوع ترميزه. أضِف المَعلمات التالية لتحديد سمات ملف CSV في ملف الإعدادات.

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

لكي يتمكّن الموصّل من الوصول إلى ملفات CSV والفهرسة، يجب تقديم معلومات عن تعريفات الأعمدة في ملف الإعدادات. إذا كانملف الإعدادات لا يحتوي على المَعلمات التي تحدّد أسماء الأعمدة التي سيتم فهرستها وأعمدة المفاتيح الفريدة، يتم استخدام القيم التلقائية.

6- تحديد الأعمدة لاستخدامها في عناوين URL لنتائج البحث القابلة للنقر

عندما يبحث أحد المستخدِمين باستخدام Google Cloud Search، يستجيب محرّك البحث من خلال عرض صفحة نتائج تتضمّن عناوين URL قابلة للنقر لكل نتيجة. لتفعيل هذه الميزة، يجب إضافة المَعلمة الموضّحة في الجدول التالي إلى ملف الإعدادات.

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

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

• مَعلمات ضبط البيانات الوصفية
• تنسيقات الأعمدة
• جودة البحث

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

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

تنسيقات التاريخ والوقت

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

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

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

جودة البحث

يتيح موصل CSV في Cloud Search تنسيق HTML تلقائيًا لحقول البيانات. يحدِّد الموصِّل حقول البيانات في بداية تنفيذ الموصِّل، ويستخدم بعد ذلك نموذج محتوى لتنسيق كل سجلّ بيانات قبل تحميله إلى Cloud Search.

يحدِّد نموذج المحتوى أهمية كل قيمة حقل للبحث. حقل العنوان مطلوب ويتم تحديده على أنّه حقل ذو أولوية قصوى. يمكنك تحديد مستويات أهمية جودة البحث لجميع حقول المحتوى الأخرى: "مرتفع" أو "متوسط" أو "منخفض". أيّ حقل محتوى لم يتمّ تحديده في فئة معيّنة يكون تلقائيًا منخفض الأولوية. يعرض الجدول التالي هذه المَعلمات.

8. جدولة تنقّل البيانات

التنقّل هو عملية الموصّل لاكتشاف المحتوى من مصدر البيانات، وفي هذه الحالة، ملف CSV. أثناء تشغيل محوِّل ملفات CSV، سيجتاز صفوف ملف CSV، ويفهرس كل صف في "بحث Google" من خلال واجهة برمجة التطبيقات للفهرسة.

فهرسة التنقّل الكامل لجميع الأعمدة في الملف لا فهرس التنقّل التزايدي سوى الأعمدة التي تمت إضافتها أو تعديلها منذ التنقّل السابق. لا تُجري أداة ربط ملفات CSV سوى عمليات تنقّل كاملة. ولا تُجري عمليات تنقّل تدريجية.

تحدِّد مَعلمات الجدولة عدد المرات التي ينتظرها الموصِّل بين عمليات التنقّل. إذا لم يحتوي ملف الإعدادات على مَعلمات جدولة، يتم استخدام القيمة التلقائية. يعرض الجدول التالي هذه المَعلمات.

9. تحديد خيارات قائمة التحكّم بالوصول (ACL)

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

إذا كان المستودع يحتوي على معلومات فردية لقائمة التحكّم بالوصول (ACL) مرتبطة بكل مستند، حمِّل جميع معلومات قائمة التحكّم بالوصول للتحكّم في الوصول إلى المستندات ضمن Cloud Search. إذا كان مستودعك يقدّم معلومات ACL جزئية أو لا يقدّم أي معلومات، يمكنك تقديم معلومات ACL التلقائية في المَعلمات التالية التي تقدّمها حزمة SDK لملف الاتصال.

يعتمد الموصّل على تفعيل جداول التحكم في الوصول التلقائية في ملف الضبط. ل تفعيل جداول التحكم في الوصول التلقائية، اضبط defaultAcl.mode على أي وضع آخر غير none واضبطه باستخدام defaultAcl.*.

تعريف المخطط

تسمح خدمة Cloud Search بفهرسة المحتوى المنظَّم وغير المنظَّم وعرض بياناته. لتفعيل طلبات البحث عن البيانات المنظَّمة في بياناتك، عليك إعداد مخطّط لمصدر بياناتك.

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

لنفترض أنّ ملف CSV الذي يتم إدخاله يتضمّن المحتوى التالي.

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

استنادًا إلى بنية البيانات أعلاه، يمكنك تحديد مخطّط لمصدر بيانات تريد فهرسة البيانات منه في ملف CSV.

{
  "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 pairs التي تحدّد سلوك مثال على الموصّل.

# 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

للحصول على أوصاف مفصّلة لكل مَعلمة، اطّلِع على مرجع مَعلمات الضبط.

تشغيل موصِّل ملف CSV في Cloud Search

لتشغيل أداة الربط من سطر الأوامر، اكتب الأمر التالي:

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

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