نشر موصل 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. قبل النشر، تأكَّد من توفّر المكوّنات التالية:

• يجب تثبيت Java JRE 1.8 على الكمبيوتر الذي يتم تشغيل الموصّل عليه.
• معلومات Google Workspace لإنشاء عمليات ربط:
  • مفتاح Google Workspace الخاص (الذي يحتوي على رقم تعريف حساب الخدمة)
  • معرّف مصدر بيانات Google Workspace

عادةً، يقدّم مشرف 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. يجب توفير معرّف مصدر البيانات ورقم تعريف حساب الخدمة ومسار ملف المفتاح الخاص لحساب الخدمة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

جودة البحث

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

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

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

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

يستخدم Connector قوائم التحكّم بالوصول للتحكّم في الوصول. إذا كان المستودع يوفّر قوائم ACL، حمِّلها. بخلاف ذلك، اضبط قوائم التحكّم بالوصول التلقائية. اضبط قيمة 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.