نشر موصِّل قاعدة بيانات

تحذير: يتم تقديم الموصلات المرجعية في Cloud Search "كما هي". كنموذج للرمز البرمجي للاستخدام في إنشاء موصلات تعمل الخاصة بك. يتطلب هذا الرمز النموذجي تخصيص واختبار جوهري قبل استخدامه في إثبات جدوى أو بيئات الإنتاج. لاستخدام الإنتاج، ننصحك بشدة بالحصول على المساعدة من أحد شركاء Cloud Search. لمزيد من المساعدة في العثور على سحابة إلكترونية مناسبة شريك البحث، يُرجى التواصل مع مدير حسابك في Google.

يمكنك إعداد Google Cloud Search لاكتشاف البيانات من حساب مؤسستك وفهرسته. بقواعد البيانات باستخدام موصل قاعدة بيانات Google Cloud Search.

اعتبارات مُهمّة

يمكنك تثبيت وتشغيل موصِّل قاعدة بيانات Cloud Search في أي بيئة تقريبًا يمكن فيها تشغيل تطبيقات Java، ما دام للموصل إذن الوصول إلى كليهما. الإنترنت وقاعدة البيانات.

متطلبات النظام

متطلبات النظام
نظام التشغيل نظاما التشغيل Windows أو Linux
قاعدة بيانات لغة الاستعلامات البنيوية أي قاعدة بيانات SQL تتضمّن برنامج تشغيل متوافق مع JDBC 4.0 أو إصدار أحدث، بما في ذلك ما يلي:
  • MS SQL Server (2008 و2012 و2014 و2016)
  • Oracle (11g، 12c)
  • Google Cloud SQL
  • MySQL
البرامج برنامج تشغيل JDBC للموصل لاستخدامه للوصول إلى قاعدة البيانات (يتم تنزيله وتثبيته بشكل منفصل)

نشر الموصِّل

توضِّح الخطوات التالية كيفية تثبيت الموصِّل وضبطه. لفهرسة قواعد البيانات المحددة وعرض النتائج إلى مستخدمي Cloud Search.

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

قبل نشر موصِّل قاعدة بيانات Cloud Search، عليك جمع المعلومات التالية:

الخطوة 1: تنزيل وإنشاء برنامج موصل قاعدة البيانات

  1. استنسِخ مستودع الموصل من GitHub.
    $ git clone https://github.com/google-cloudsearch/database-connector.git
    $ cd database-connector
  2. تحقَّق من الإصدار المطلوب من الموصِّل:
    $ git checkout tags/v1-0.0.3
  3. قم ببناء الموصل.
    $ mvn package
    لتخطّي الاختبارات أثناء إنشاء الموصِّل، استخدِم mvn package -DskipTests.
  4. انسخ الملف المضغوط للموصل إلى دليل التثبيت المحلي ثم فك ضغطه:
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
    $ cd installation-dir
    $ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
    $ cd google-cloudsearch-database-connector-v1-0.0.3

الخطوة 2: إعداد موصل قاعدة البيانات

  1. أنشئ ملفًا نصيًا وأدخِل اسمًا له connector-config.properties (الملف التلقائي) أو عبارة مشابهة. تنصحك Google في تسمية ملفات الإعداد باستخدام .properties أو .config واحتفظ بالملف في الدليل نفسه مثل الموصل. إذا كنت تستخدم اسمًا أو مسارًا مختلفًا، يجب تحديد المسار عند تشغيل الموصِّل.
  2. أضِف مَعلمات كأزواج مفتاح/قيمة إلى محتوى الملف. يجب أن يحدد ملف الضبط معاملات الوصول إلى مصدر البيانات، والوصول إلى قاعدة البيانات، وعبارة SQL للاجتياز الكامل لقاعدة البيانات، وعنوان حقل المحتوى وتعريفات العمود. يمكنك أيضًا ضبط سلوك موصل آخر مع معلمات اختيارية. مثل:
    # Required parameters for data source access
    api.sourceId=1234567890abcdef
    api.identitySourceId=0987654321lmnopq
    api.serviceAccountPrivateKeyFile=./PrivateKey.json
    #
    # Required parameters for database access
    db.url=jdbc:mysql://localhost:3306/mysql_test
    db.user=root
    db.password=passw0rd
    #
    # Required full traversal SQL statement parameter
    db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
    #
    # Required parameters for column definitions and URL format
    db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
    db.uniqueKeyColumns=customer_id
    url.columns=customer_id
    #
    # Required content field parameter
    contentTemplate.db.title=customer_id
    #
    # Optional parameters to set ACLs to "entire domain" access
    defaultAcl.mode=fallback
    defaultAcl.public=true
    #
    # Optional parameters for schedule traversals
    schedule.traversalIntervalSecs=36000
    schedule.performTraversalOnStart=true
    schedule.incrementalTraversalIntervalSecs=3600
    

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

    للتعرّف على المعلَمات المشتركة في جميع Cloud Search مثل تهيئة البيانات الوصفية وتنسيقات التاريخ وخيارات قائمة التحكم بالوصول، انتقل إلى مَعلمات الموصِّل التي توفّرها Google

    تحديد خصائص كائن المخطط في SQL للاجتياز، إن أمكن مَعلمات طلب البحث. عادةً يمكنك إضافة أسماء مستعارة إلى SQL الشخصي. فعلى سبيل المثال، إذا كان لديك فيلم قاعدة البيانات وأن مخطط مصدر البيانات يحتوي على تعريف خاصية باسم "ActorName"، يمكن أن تكون عبارة SQL على الشكل: SELECT …, last_name AS ActorName, … FROM … .

الخطوة 3: تشغيل موصل قاعدة البيانات

يفترض المثال التالي أن المكونات المطلوبة موجودة في دليل على نظام Linux.

لتشغيل الموصل من سطر الأوامر، أدخل الأمر التالي:

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

المكان:

  • google-cloud-search-database-connector-v1-0.0.3.jar هو ملف .jar لموصل قاعدة البيانات
  • mysql-connector-java-5.1.41-bin.jar هو برنامج تشغيل JDBC المُستخدَم للوصول إلى قاعدة البيانات
  • mysql.config هو ملف إعداد يحمل اسمًا مخصّصًا. وللتأكد من أن الموصل يتعرف على ملف تهيئة، حدد مساره في سطر الأوامر. بخلاف ذلك، يستخدم الموصل connector-config.properties في منطقتك الدليل كاسم الملف الافتراضي.

يُبلِغ الموصِّل عن أخطاء الضبط أثناء رصدها. يتم الإبلاغ عن بعض الأخطاء عندما يبدأه الموصّل، مثلاً عندما يتم تعريف عمود قاعدة البيانات كجزء من محتوى السجل (في db.allColumns)، ولكن لا يتم استخدام العمود في استعلام SQL (لغة الاستعلام البنيوية) للاجتياز قاعدة البيانات (في db.allRecordsSql). يتم اكتشاف الأخطاء الأخرى والإبلاغ عنها فقط في حال يحاول الموصل الوصول إلى قاعدة البيانات للاجتياز الأول، مثل بناء جملة جملة SQL (لغة الاستعلام البنيوية) غير الصالح.

مرجع مَعلمات الإعدادات

مَعلمات الوصول إلى مصدر البيانات

الإعدادات المعلمة
رقم تعريف مصدر البيانات api.sourceId = source-ID

مطلوب. Cloud Search معرّف المصدر الذي أعده مشرف Google Workspace.

رقم تعريف مصدر الهوية api.identitySourceId = identity-source-ID

مطلوب لاستخدام المجموعات والمستخدمين الخارجيين لقوائم التحكم في الوصول (ACL). Cloud Search رقم تعريف مصدر الهويات الذي أعده مشرف Google Workspace.

حساب الخدمة api.serviceAccountPrivateKeyFile = path-to-private-key

مطلوب. المسار إلى Cloud Search ملف مفتاح حساب الخدمة الذي أنشأه مشرف Google Workspace.

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

الإعدادات المعلمة
عنوان URL لقاعدة البيانات db.url = database-URL

مطلوب. تشير رسالة الأشكال البيانية المسار الكامل لقاعدة البيانات المراد الوصول إليه، مثل jdbc:mysql://127.0.0.1/dbname.

اسم المستخدم وكلمة المرور لقاعدة البيانات db.user = username
db.password = password

مطلوب. اسم مستخدم صالح التي يستخدمها الموصل للوصول إلى قاعدة البيانات. يجب على مستخدم قاعدة البيانات هذا لديهم حق الوصول للقراءة إلى السجلات ذات الصلة بقاعدة البيانات التي تتم قراءتها.

برنامج تشغيل JDBC db.driverClass = oracle.jdbc.OracleDriver

مطلوبة فقط إذا لم يتم تحديد برنامج تشغيل JDBC 4.0 من قبل في مسار الفئة.

مَعلمات طلب بحث SQL للاجتياز

يجتاز الموصل سجلات قاعدة البيانات باستخدام SQL SELECT في ملف التهيئة. يجب تهيئة استعلام اجتياز كامل؛ طلبات البحث عن تعد عمليات اجتياز التزايد اختيارية.

يقرأ الاجتياز الكامل كل سجلّ قاعدة بيانات تم إعداده للفهرسة. ملف يجب إجراء الاجتياز لفهرسة السجلات الجديدة في Cloud Search وكذلك إعادة الفهرسة جميع السجلات الحالية.

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

ينفِّذ الموصل عمليات الاجتياز هذه وفقًا للجداول الزمنية التي تحدِّدها في. مَعلمات جدول الاجتياز

الإعدادات المعلمة
طلب بحث الاجتياز الكامل db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

مطلوب. يتم تشغيل الاستعلام لكل اجتياز كامل.

كل اسم عمود يستخدمه الموصل في أي يجب أن تكون السعة (المحتوى، والمعرّف الفريد، وقوائم التحكم في الوصول) موجودة في هذا الاستعلام. تشير رسالة الأشكال البيانية يجري موصل بعض عمليات التحقق الأولية عند بدء التشغيل لاكتشاف الأخطاء وعمليات الحذف. لهذا السبب، لا تستخدم عبارة عامة "SELECT * FROM ..." طلب البحث.

التقسيم على صفحات خلال الاجتياز الكامل db.allRecordsSql.pagination = {none | offset}

يمكن أن تكون القيمة:

  • بدون: عدم استخدام التقسيم على صفحات
  • الاقتطاع: استخدام التقسيم على صفحات حسب إزاحة الصف

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

طلب بحث إضافي حول الاجتياز db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

هذا الحقل مطلوب في حال جدولة عمليات اجتياز تدريجية.

تتيح لك علامة "؟" في الاستعلام عنصر نائب إلزامي لقيمة الطابع الزمني. تشير رسالة الأشكال البيانية الطابع الزمني لتتبع التعديلات بين استعلامات SQL (لغة الاستعلام البنيوية) للاجتياز التزايدي.

لتتبُّع عمود الطابع الزمني لقاعدة البيانات لآخر وقت تعديل، أضِف السمة اسم timestamp_column البديل إلى عبارة SQL وإلا، فاستخدم الطابع الزمني الحالي اجتياز الموصل.

بالنسبة إلى الاجتياز التدريجي الأول، يستخدم الموصل وقت بدء الموصل. بعد والاجتياز الأول، تخزن خدمة Cloud Search الطابع الزمني بحيث تسمح عمليات إعادة تشغيل الموصل بالوصول إلى الاجتياز التدريجي السابق الطابع الزمني.

المنطقة الزمنية لقاعدة البيانات db.timestamp.timezone = America/Los_Angeles

تُستخدَم لتحديد المنطقة الزمنية المطلوب استخدامها للطوابع الزمنية لقاعدة البيانات. الطابع الزمني لقاعدة البيانات المستخدم لتحديد إضافات السجل الجديدة أو وسجلات قاعدة البيانات المعدّلة. يكون الوضع التلقائي هو المنطقة الزمنية المحلية التي يعمل فيها الموصل.

أمثلة على طلبات بحث SQL للاجتياز

  • استعلام الاجتياز الكامل الأساسي الذي يقرأ كل سجل مهم في قاعدة بيانات الموظفين للفهرسة:
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
        FROM employee
  • تحديد التقسيم على صفحات حسب الإزاحة، وتقسيم عملية الاجتياز الكامل إلى طلبات بحث متعددة

    بالنسبة إلى SQL Server 2012 أو Oracle 12c (بناء جملة SQL 2008 القياسي):

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
        FROM employee \
        ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
    db.allRecordsSql.pagination = offset
    

    أو، بالنسبة إلى MySQL أو Google Cloud SQL:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
        FROM employee \
        ORDER BY customer_id LIMIT 1000 OFFSET ?
    db.allRecordsSql.pagination = offset
  • استعلام الاجتياز الكامل الذي يطبق قوائم التحكم بالوصول الفردية مع أسماء مستعارة:
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
         permitted_readers AS readers_users, \
         denied_readers AS denied_users, \
         permitted_groups AS readers_groups, \
         denied_groups AS denied_groups \
         FROM employee
  • طلب بحث الاجتياز التدريجي الأساسي:
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
         FROM employee \
         WHERE last_update_time > ?
  • استعلام اجتياز إضافي يطبق قوائم التحكم في الوصول الفردية بأسماء مستعارة:
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
         permitted_readers AS readers_users, \
         denied_readers AS denied_users, \
         permitted_groups AS readers_groups, \
         denied_groups AS denied_groups \
         FROM employee \
         WHERE last_update_time > ?
  • استعلام اجتياز إضافي يستخدم الطابع الزمني لقاعدة البيانات بدلاً من الوقت الحالي:
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
         last_update_time AS timestamp_column \
         FROM employee \
         WHERE last_update_time > ?

مَعلمات تعريف العمود

تحدد المعلمات التالية الأعمدة التي تستخدمها في عبارات الاجتياز لتعريف كل سجل بشكل فريد.

الإعدادات المعلمة
كل الأعمدة db.allColumns = column-1, column-2, ...column-N

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

مثال:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
الأعمدة الرئيسية الفريدة db.uniqueKeyColumns = column-1[, column-2]

مطلوب. يسرد إما عمود قاعدة بيانات واحد يحتوي على قيم فريدة أو على مجموعة من الأعمدة التي تحدد قيمها معًا معرفًا فريدًا.

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

أمثلة:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
عمود "رابط عنوان URL" url.columns = column-1[, column-2]

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

ومع ذلك، إذا حددت قيم العمود رابطًا صالحًا لكل سجل، فإن طريقة العرض يجب تحديد أعمدة عناوين URL وقيم إعدادات التنسيق.

تنسيق عنوان URL url.format = https://www.example.com/{0}

تحدد تنسيق عنوان URL للعرض. تشير المعلمات المرقمة إلى الأعمدة محددة في db.columns، بالترتيب، بدءًا من صفر.

وإذا لم يتم تحديده، تكون القيمة التلقائية هي "{0}."

تتبع الأمثلة هذا الجدول.

الأعمدة المرمّزة بنسبة مئوية لعنوان URL url.columnsToEscape = column-1[, column-2]

تحديد أعمدة من db.columns التي سيتم ترميز قيمها بنسبة مئوية قبل تضمينها في سلسلة عنوان URL المنسقة.

أمثلة على أعمدة عناوين URL

لتحديد الأعمدة المستخدمة في استعلامات الاجتياز وتنسيق عنوان URL للعرض:

  • لاستخدام عنوان URL ثابت لا يستخدم أي قيم لسجلات قاعدة البيانات، اتّبِع الخطوات التالية:
    url.format = https://www.example.com
  • لاستخدام قيمة في عمود واحد تكون عنوان URL للعرض:
    url.format = {0}
    url.columns = customer_id
  • لاستخدام قيمة عمود واحد يتم استبدالها بعنوان URL للعرض في الموضع {0}:
    url.format = https://www.example.com/customer/id={0}
    url.columns = customer_id
    url.columnsToEscape = customer_id
  • لاستخدام قيم أعمدة متعددة من أجل إنشاء عنوان URL للعرض (تعتمد الأعمدة على الترتيب):
    url.format = {1}/customer={0}
    url.columns = customer_id, linked_url
    url.columnsToEscape = customer_id

حقول المحتوى

استخدام خيارات المحتوى لتحديد قيم السجل يجب أن يكون جزءًا من المحتوى القابل للبحث.

الإعدادات المعلمة
عمود البحث الأعلى جودة contentTemplate.db.title = column-name

مطلوب. العمود الأعلى جودة لفهرسة البحث وتحديد أولوية النتائج.

تحديد أولوية الأعمدة للبحث contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

تحديد أعمدة المحتوى (باستثناء مجموعة الأعمدة التي تتضمّن contentTemplate.db.title) كحقول ذات جودة بحث عالية أو متوسطة أو منخفضة يتم ضبط الأعمدة غير المحدَّدة تلقائيًا على القيمة "منخفضة".

أعمدة بيانات المحتوى db.contentColumns = column-1[, column-2...]

حدد أعمدة المحتوى في قاعدة البيانات. يتم تنسيقها تم تحميله إلى Cloud Search كمحتوى مستند قابل للبحث.

إذا لم تحدّد قيمة، ستكون القيمة التلقائية "*" مما يشير إلى أن جميع والأعمدة للمحتوى.

عمود Blob db.blobColumn = column-name

تحديد اسم الكائن الثنائي الكبير (blob) واحد عمود لاستخدامه لمحتوى المستند بدلاً من مجموعة من أعمدة المحتوى.

إذا تم تحديد عمود الكائن الثنائي الكبير (blob)، يُعتبر خطأ إذا تم تحديد أعمدة المحتوى هي الأخرى أيضًا. ومع ذلك، فإن بيانات التعريف وتعريفات أعمدة البيانات المنظمة لا يزال مسموحًا به مع أعمدة الكائن الثنائي الكبير (blob).