إنشاء موصِّل محتوى

موصِّل المحتوى هو برنامج يُستخدم لاجتياز البيانات في مستودع مؤسسة وتعبئة مصدر بيانات. توفر Google الخيارات التالية لتطوير موصِّلات المحتوى:

  • حزمة تطوير البرامج (SDK) لموصِّل المحتوى. يعد هذا خيارًا جيدًا إذا كنت تبرمج باستخدام Java. حزمة SDK لموصِّل المحتوى هي أداة تضمين حول واجهة برمجة تطبيقات REST تتيح لك إنشاء الموصلات بسرعة. لإنشاء موصِّل محتوى باستخدام حزمة تطوير البرامج (SDK)، يمكنك الرجوع إلى إنشاء موصِّل محتوى باستخدام حزمة Content Connector SDK.

  • مكتبات واجهة برمجة تطبيقات REST أو واجهة برمجة تطبيقات منخفضة المستوى استخدِم هذه الخيارات إذا لم تكن مبرمجًا بلغة Java أو إذا كانت قاعدة الترميز الخاصة بك تستوعب واجهة برمجة تطبيقات RST أو مكتبة بشكل أفضل. لإنشاء موصِّل محتوى باستخدام واجهة برمجة تطبيقات REST، يمكنك الاطّلاع على إنشاء موصِّل محتوى باستخدام REST API.

يؤدي موصل المحتوى النموذجي المهام التالية:

  1. يقرأ معلَمات الإعداد ويعالجها.
  2. يسحب هذا الحقل أجزاء منفصلة من البيانات القابلة للفهرسة تُسمى "items" من مستودع المحتوى التابع لجهة خارجية.
  3. دمج قوائم التحكم بالوصول (ACL) والبيانات الوصفية وبيانات المحتوى في عناصر قابلة للفهرسة.
  4. تتم فهرسة العناصر في مصدر بيانات Cloud Search.
  5. (اختياري) يستمع إلى تغييرات الإشعارات من مستودع المحتوى التابع لجهة خارجية. يتم تحويل الإشعارات إلى طلبات فهرسة للحفاظ على مزامنة مصدر بيانات Cloud Search مع المستودع التابع لجهة خارجية. لا ينفذ الموصل هذه المهمة إلا إذا كان المستودع يتيح اكتشاف التغيير.

إنشاء موصِّل محتوى باستخدام حزمة تطوير البرامج (SDK) لموصِّل المحتوى

توضح الأقسام التالية كيفية إنشاء موصِّل محتوى باستخدام حزمة SDK لموصِّل المحتوى.

إعداد التبعيات

يجب تضمين بعض التبعيات في ملف الإصدار لاستخدام حزمة تطوير البرامج (SDK). انقر على علامة تبويب أدناه لعرض التبعيات لبيئة التصميم الخاصة بك:

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

Gradle

compile group: 'com.google.enterprise.cloudsearch',
        name: 'google-cloudsearch-indexing-connector-sdk',
        version: 'v1-0.0.3'

إنشاء إعدادات الموصل

يحتوي كل موصل على ملف تهيئة يحتوي على المعلمات التي يستخدمها الموصل، مثل رقم تعريف المستودع. يتم تعريف المَعلمات على أنّها أزواج من القيم الأساسية، مثل api.sourceId=1234567890abcdef.

تحتوي حزمة تطوير البرامج (SDK) لخدمة Google Cloud Search على العديد من مَعلمات الإعداد التي توفّرها Google وتستخدمها جميع الموصِّلات. يجب الإفصاح عن المعلَمات التالية التي توفّرها Google في ملف الإعداد:

  • بالنسبة إلى موصِّل المحتوى، يجب تعريف api.sourceId وapi.serviceAccountPrivateKeyFile لأنّ هاتَين المعلمتَين تحدّدان موقع المستودع والمفتاح الخاص المطلوب للوصول إلى المستودع.
  • بالنسبة إلى موصِّل الهوية، يجب تعريف api.identitySourceId لأنّ هذه المَعلمة تحدِّد موقع مصدر هويتك الخارجي. في حال مزامنة المستخدمين، عليك أيضًا تصنيف api.customerId كمعرّف فريد لحساب Google Workspace الخاص بمؤسستك.

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

يمكنك أيضًا تحديد المعلمات الخاصة بمستودعك لاستخدامها في ملف الضبط.

تمرير ملف الإعداد إلى الموصل

اضبط خاصية النظام config لتمرير ملف الإعداد إلى الموصل. يمكنك ضبط الخاصية باستخدام الوسيطة -D عند بدء تشغيل الموصل. على سبيل المثال، يبدأ الأمر التالي تشغيل الموصل باستخدام ملف الإعداد MyConfig.properties:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

في حال عدم توفّر هذه الوسيطة، تحاول حزمة SDK الوصول إلى ملف إعداد تلقائي يُسمى connector-config.properties.

تحديد استراتيجية الاجتياز

تكمن الوظيفة الأساسية لموصل المحتوى في اجتياز مستودع وفهرسة بياناته. يجب عليك تنفيذ استراتيجية الاجتياز بناءً على حجم البيانات وتخطيطها في مستودعك. يمكنك تصميم استراتيجيتك الخاصة أو الاختيار من بين الاستراتيجيات التالية المنفَّذة في SDK:

استراتيجية الاجتياز الكامل

تعمل استراتيجية الاجتياز الكاملة على فحص المستودع بأكمله وفهرسة كل عنصر بشكل عشوائي. تُستخدم هذه الإستراتيجية بشكل شائع عندما يكون لديك مستودع صغير وتتحمل النفقات العامة لإجراء اجتياز كامل في كل مرة تفهرس فيها.

تُعد استراتيجية الاجتياز هذه مناسبة للمستودعات الصغيرة التي تحتوي في الغالب على بيانات ثابتة وغير هرمية. يمكنك أيضًا استخدام استراتيجية الاجتياز هذه عندما يكون اكتشاف التغيير صعبًا أو غير متاح في المستودع.

إدراج استراتيجية الاجتياز

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

استراتيجية الاجتياز هذه مناسبة عندما يكون اكتشاف التغيير صعبًا أو لا يدعمه المستودع، وكانت لديك بيانات غير هرمية، وتعمل على مجموعات بيانات كبيرة جدًا.

اجتياز الرسم البياني

تفحص استراتيجية اجتياز الرسم البياني العقدة الرئيسية بأكملها لتحديد حالة كل عنصر. بعد ذلك، يأخذ الموصل تمريرة ثانية ولا يفهرس سوى العناصر في العقدة الجذرية الجديدة أو التي تم تحديثها منذ آخر فهرسة. أخيرًا، يمرر الموصل أي معرّفات فرعية ثم يفهرس العناصر الجديدة أو التي تم تحديثها في العُقد الفرعية. يستمر الموصل بشكل متكرر من خلال جميع العُقد الفرعية حتى تتم معالجة جميع العناصر. عادةً ما يستخدم هذا الاجتياز للمستودعات الهرمية حيث لا تكون سرد جميع أرقام التعريف عملية.

هذه الاستراتيجية مناسبة إذا كانت لديك بيانات هرمية تحتاج إلى الزحف إليها، مثل سلسلة من الأدلة أو صفحات الويب.

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

إنشاء موصل اجتياز كامل باستخدام فئة نموذج

يشير هذا القسم من المستندات إلى مقتطفات التعليمات البرمجية من مثال FullTraversalSample.

تنفيذ نقطة دخول الموصل

نقطة الدخول إلى الموصّل هي طريقة main(). تتمثل المهمة الأساسية لهذه الطريقة في إنشاء مثيل للفئة Application واستدعاء طريقة start() الخاصة بها لتشغيل الموصل.

قبل طلب application.start()، استخدِم الفئة IndexingApplication.Builder لإنشاء مثيل للنموذج FullTraversalConnector. يقبل FullTraversalConnector كائن Repository يتم تنفيذ طرقه. يعرض مقتطف الرمز التالي كيفية تنفيذ طريقة main():

FullTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

وراء الكواليس، تستدعي حزمة SDK الطريقة initConfig() بعد استدعاءات طريقة main() للموصل Application.build. تنفِّذ طريقة initConfig()المهام التالية:

  1. يتم استدعاء الطريقة Configuation.isInitialized() للتأكد من عدم تهيئة Configuration.
  2. تعمل هذه السياسة على إعداد كائن Configuration باستخدام أزواج المفتاح/القيمة التي توفّرها Google. يتم تخزين كل زوج مفتاح/قيمة في كائن ConfigValue داخل كائن Configuration.

تنفيذ واجهة Repository

الغرض الوحيد من الكائن Repository هو إجراء اجتياز عناصر المستودع وفهرستها. عند استخدام نموذج، ما عليك سوى إلغاء طُرق معيّنة ضمن واجهة Repository لإنشاء موصِّل محتوى. تعتمد الطرق التي تلغيها على النموذج واستراتيجية الاجتياز التي تستخدمها. بالنسبة إلى FullTraversalConnector، يمكنك إلغاء الطُرق التالية:

  • الطريقة init(). لإجراء أي عملية إعداد لمستودع البيانات وإعداده، عليك إلغاء طريقة init().

  • الطريقة getAllDocs(). لاجتياز جميع العناصر في مستودع البيانات وفهرستها، عليك إلغاء طريقة getAllDocs(). يتم استدعاء هذه الطريقة مرة واحدة لكل اجتياز مجدول (كما هو محدد في التهيئة).

  • (اختياري) طريقة getChanges(). إذا كان المستودع يتيح رصد التغيير، يمكنك إلغاء طريقة getChanges(). يتم استدعاء هذه الطريقة مرة واحدة لكل عملية اجتياز تزايدي مجدول (كما هو محدد في التهيئة) لاسترداد العناصر المعدّلة وفهرستها.

  • (اختياري) طريقة close(). إذا كنت بحاجة إلى تنفيذ تنظيف المستودع، ألغِ الطريقة close(). ويتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف الموصل.

وتُرجع كل طريقة من طرق الكائن Repository بعض أنواع الكائنات ApiOperation. ينفِّذ الكائن ApiOperation إجراءً في شكل استدعاءات IndexingService.indexItem() واحدة أو عدة طلبات لإجراء الفهرسة الفعلية للمستودع.

الحصول على معلَمات ضبط مخصّصة

كجزء من معالجة إعدادات الموصل، عليك الحصول على أي معلَمات مخصّصة من الكائن Configuration. يتم تنفيذ هذه المهمة عادةً بطريقة Repository init() للصفوف.

تتضمن الفئة Configuration عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتُرجع كل طريقة عنصر ConfigValue. ستستخدم بعد ذلك طريقة get() للكائن ConfigValue لاسترداد القيمة الفعلية. يوضّح المقتطف التالي، من FullTraversalSample، كيفية استرداد قيمة عدد صحيح واحد مخصّصة من كائن Configuration:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

للحصول على معلَمة تحتوي على عدة قيم وتحليلها، استخدِم أحد المحللين اللغويين للفئة Configuration لتحليل البيانات في أجزاء منفصلة. يستخدم المقتطف التالي، من موصل البرنامج التعليمي، طريقة getMultiValue للحصول على قائمة بأسماء مستودعات GitHub:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

إجراء الاجتياز بالكامل

تجاوز getAllDocs() لإجراء اجتياز كامل وفهرسة المستودع. تقبل الطريقة getAllDocs() نقطة مرجعية. تُستخدم نقطة التفتيش لاستئناف الفهرسة عند عنصر محدد في حال مقاطعة العملية. لكل عنصر في مستودعك، نفِّذ هذه الخطوات في طريقة getAllDocs():

  1. ضبط الأذونات
  2. اضبط البيانات الوصفية للعنصر الذي تريد فهرسته.
  3. ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة RepositoryDoc.
  4. عليك تجميع كل عنصر قابل للفهرسة في تكرار يعرضه الطريقة getAllDocs(). يُرجى العِلم أنّ getAllDocs() تعرض فعليًا عنصر CheckpointCloseableIterable وهو تكرار لعناصر ApiOperation، وكل عنصر يمثّل طلب واجهة برمجة تطبيقات تم تنفيذه على RepositoryDoc، مثل فهرسته.

إذا كانت مجموعة العناصر كبيرة جدًا ولا يمكن معالجتها في مكالمة واحدة، يمكنك تضمين نقطة اختيار وضبط الرمز hasMore(true) للإشارة إلى توفُّر المزيد من العناصر للفهرسة.

ضبط الأذونات لعنصر

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

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

توفر حزمة تطوير البرامج (SDK) لموصِّل المحتوى مجموعة ثرية من فئات وأساليب قائمة التحكم بالوصول (ACL) لتصميم قوائم التحكم بالوصول لمعظم المستودعات. يجب تحليل قائمة التحكم بالوصول لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول المقابلة لخدمة Google Cloud Search عند فهرسة أحد العناصر. إذا كانت قائمة التحكم في الوصول (ACL) في مستودعك تستخدم مفاهيم مثل وراثة قائمة التحكم بالوصول، فقد يكون نمذجة هذه القائمة أمرًا صعبًا. للحصول على مزيد من المعلومات عن قوائم التحكم بالوصول في Google Cloud Search، يُرجى مراجعة قوائم التحكم في الوصول (ACL) في Google Cloud Search.

ملاحظة: تتيح واجهة برمجة التطبيقات للفهرسة في Cloud Search قوائم التحكم بالوصول (ACL) لنطاق واحد. وهي لا تدعم قوائم التحكم بالوصول (ACLs) عبر النطاقات. استخدم الفئة Acl.Builder لضبط الوصول إلى كل عنصر باستخدام قائمة التحكم بالوصول (ACL). يتيح مقتطف الرمز التالي، المأخوذ من عيّنة الاجتياز الكامل، لجميع المستخدمين أو "المسؤولين" (getCustomerPrincipal()) أن يكونوا "قرّاء" لجميع العناصر (.setReaders()) عند إجراء بحث.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

تحتاج إلى فهم قوائم التحكم في الوصول (ACLs) لوضع نماذج لقوائم التحكم في الوصول (ACL) بشكلٍ صحيح للمستودع. على سبيل المثال، قد تفهرس ملفات داخل نظام ملفات يستخدم نوعًا من نموذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب نمذجة البيانات الموروثة لقائمة التحكم بالوصول (ACL) معلومات إضافية مشمولة في قوائم التحكم بالوصول (ACL) في Google Cloud Search

ضبط البيانات الوصفية لعنصر

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى حدّ أدنى من رقم تعريف السلسلة الفريد ونوع العنصر وقائمة التحكم بالوصول (ACL) وعنوان URL وإصدار العنصر. يوضّح مقتطف الرمز التالي كيفية إنشاء Item باستخدام فئة المساعدة IndexingItemBuilder.

FullTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

إنشاء عنصر قابل للفهرسة

بعد ضبط البيانات الوصفية للعنصر، يمكنك إنشاء العنصر الفعلي القابل للفهرسة باستخدام الفئة RepositoryDoc.Builder. يوضّح المثال التالي كيفية إنشاء عنصر واحد قابل للفهرسة.

FullTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc هو نوع من ApiOperation ينفّذ طلب IndexingService.indexItem() الفعلي.

يمكنك أيضًا استخدام طريقة setRequestMode() ضمن الفئة RepositoryDoc.Builder لتحديد طلب الفهرسة على أنّه ASYNCHRONOUS أو SYNCHRONOUS:

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

إنشاء حزمة لكل عنصر قابل للفهرسة في تكرار

تعرض الطريقة getAllDocs() عنصر Iterator، تحديدًا CheckpointCloseableIterable من عناصر RepositoryDoc. يمكنك استخدام الفئة CheckpointClosableIterableImpl.Builder لإنشاء مُكرّر وإرجاعه. يوضح مقتطف الرمز التالي كيفية إنشاء تكرار وإرجاعه.

FullTraversalSample.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

تنفِّذ حزمة SDK كل استدعاء فهرسة مضمَّن في المكرّر.

الخطوات التالية

في ما يلي بعض الخطوات التي يمكنك اتّخاذها:

إنشاء موصل اجتياز قائمة باستخدام فئة نموذج

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

يشير هذا القسم من المستندات إلى مقتطفات التعليمات البرمجية من مثال ListTraversalSample.

تنفيذ نقطة دخول الموصل

نقطة الدخول إلى الموصّل هي طريقة main(). تتمثل المهمة الأساسية لهذه الطريقة في إنشاء مثيل للفئة Application واستدعاء طريقة start() الخاصة بها لتشغيل الموصل.

قبل طلب application.start()، استخدِم الفئة IndexingApplication.Builder لإنشاء مثيل للنموذج ListingConnector. تقبل ListingConnector الكائن Repository الذي تنفذ طرقه. يوضّح المقتطف التالي كيفية إنشاء مثيل ListingConnector وRepository المرتبط به:

ListTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

وراء الكواليس، تستدعي حزمة SDK الطريقة initConfig() بعد استدعاءات طريقة main() للموصل Application.build. طريقة initConfig():

  1. يتم استدعاء الطريقة Configuation.isInitialized() للتأكد من عدم تهيئة Configuration.
  2. تعمل هذه السياسة على إعداد كائن Configuration باستخدام أزواج المفتاح/القيمة التي توفّرها Google. يتم تخزين كل زوج مفتاح/قيمة في كائن ConfigValue داخل كائن Configuration.

تنفيذ واجهة Repository

الغرض الوحيد من الكائن Repository هو إجراء اجتياز عناصر المستودع وفهرستها. عند استخدام نموذج، ما عليك سوى إلغاء طرق معيّنة ضمن واجهة Repository لإنشاء موصِّل محتوى. وتعتمد الطرق التي تلغيها على النموذج واستراتيجية الاجتياز التي تستخدمها. بالنسبة إلى ListingConnector، يمكنك إلغاء الطرق التالية:

  • الطريقة init(). لإجراء أي عملية إعداد لمستودع البيانات وإعداده، عليك إلغاء طريقة init().

  • الطريقة getIds() لاسترداد المعرّفات وقيم التجزئة لجميع السجلات في المستودع، يمكنك إلغاء طريقة getIds().

  • الطريقة getDoc() لإضافة عناصر جديدة أو تعديلها أو تعديلها أو حذفها من الفهرس، عليك إلغاء طريقة getDoc().

  • (اختياري) طريقة getChanges(). إذا كان المستودع يتيح رصد التغيير، يمكنك إلغاء طريقة getChanges(). يتم استدعاء هذه الطريقة مرة واحدة لكل عملية اجتياز تزايدي مجدول (كما هو محدد في التهيئة) لاسترداد العناصر المعدّلة وفهرستها.

  • (اختياري) طريقة close(). إذا كنت بحاجة إلى تنفيذ تنظيف المستودع، ألغِ الطريقة close(). ويتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف الموصل.

وتُرجع كل طريقة من طرق الكائن Repository نوعًا من كائنات ApiOperation. ينفِّذ الكائن ApiOperation إجراءً في شكل استدعاءات IndexingService.indexItem() واحدة أو عدة طلبات لإجراء الفهرسة الفعلية للمستودع.

الحصول على معلَمات ضبط مخصّصة

كجزء من معالجة إعدادات الموصل، عليك الحصول على أي معلَمات مخصّصة من الكائن Configuration. يتم تنفيذ هذه المهمة عادةً بطريقة Repository init() للصفوف.

تتضمن الفئة Configuration عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتُرجع كل طريقة عنصر ConfigValue. ستستخدم بعد ذلك طريقة get() للكائن ConfigValue لاسترداد القيمة الفعلية. يوضّح المقتطف التالي، من FullTraversalSample، كيفية استرداد قيمة عدد صحيح واحد مخصّصة من كائن Configuration:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

للحصول على معلَمة تحتوي على عدة قيم وتحليلها، استخدِم أحد المحللين اللغويين للفئة Configuration لتحليل البيانات في أجزاء منفصلة. يستخدم المقتطف التالي، من موصل البرنامج التعليمي، طريقة getMultiValue للحصول على قائمة بأسماء مستودعات GitHub:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

إجراء اجتياز القائمة

تجاوز طريقة getIds() لاسترداد أرقام التعريف وقيم التجزئة لجميع السجلات في المستودع. تقبل الطريقة getIds() نقطة مرجعية. تُستخدم نقطة التفتيش لاستئناف الفهرسة عند عنصر معين في حال مقاطعة العملية.

بعد ذلك، يمكنك تجاهل الطريقة getDoc() لمعالجة كل عنصر في قائمة انتظار فهرسة Cloud Search.

إرسال معرّفات العناصر وقيم التجزئة

يمكنك تجاهل getIds() لجلب معرّفات السلع وقيم تجزئة المحتوى المرتبطة بها من المستودع. يتم بعد ذلك حزم أزواج المعرّف وقيمة التجزئة في طلب عملية دفع إلى قائمة انتظار فهرسة Cloud Search. عادةً ما يتم إرسال معرفات الجذر أو الأصل أولاً متبوعة بأرقام التعريف الفرعية حتى تتم معالجة التسلسل الهرمي بالكامل للعناصر.

تقبل الطريقة getIds() نقطة مرجعية تمثل آخر عنصر ستتم فهرسته. يمكن استخدام النقطة المرجعية لاستئناف الفهرسة عند عنصر محدّد في حال مقاطعة العملية. لكل عنصر في المستودع، نفِّذ هذه الخطوات باستخدام طريقة getIds():

  • احصل على كل معرّف سلعة وقيمة تجزئة مرتبطة من المستودع.
  • اجمع كل زوج من أرقام التعريف وقيمة التجزئة في PushItems.
  • ادمِج كل PushItems في مُكرّر يتم عرضه باستخدام الطريقة getIds(). يُرجى العِلم أنّ السمة getIds() تعرض في الواقع عنصر CheckpointCloseableIterable وهو تكرار لعناصر ApiOperation، وكل عنصر يمثّل طلب واجهة برمجة تطبيقات يتم تنفيذه على RepositoryDoc، مثل دفع العناصر إلى قائمة الانتظار.

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

ListTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

يوضِّح مقتطف الرمز التالي كيفية استخدام الفئة PushItems.Builder لتجميع أرقام التعريف وقيم التجزئة في دفعة واحدة ApiOperation.

ListTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

يتم إرسال العناصر إلى قائمة انتظار الفهرسة في Cloud Search لإجراء المزيد من المعالجة.

استرداد كل عنصر والتعامل معه

تجاهُل getDoc() لمعالجة كل عنصر في قائمة انتظار الفهرسة في Cloud Search يمكن أن يكون العنصر جديدًا أو معدَّلاً أو غير معدَّل أو لم يعُد متوفّرًا في مستودع المصدر. استرداد وفهرسته كل عنصر جديد أو معدّل. قم بإزالة العناصر من الفهرس والتي لم تعد موجودة في مستودع المصدر.

تقبل الطريقة getDoc() عنصرًا من قائمة انتظار فهرسة Google Cloud Search. لكل عنصر في قائمة الانتظار، نفِّذ الخطوات التالية في طريقة getDoc():

  1. تحقّق من توفُّر رقم تعريف العنصر في قائمة انتظار الفهرسة في Cloud Search في المستودع. وإذا لم يكن كذلك، احذفه من الفهرس.

  2. استطلع رأي الفهرس عن حالة العنصر، وإذا لم يتغير العنصر (ACCEPTED)، فلا تتخذ أي إجراء.

  3. تم تغيير الفهرس أو العناصر الجديدة:

    1. ضبط الأذونات
    2. اضبط البيانات الوصفية للعنصر الذي تريد فهرسته.
    3. ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة RepositoryDoc.
    4. إرجاع RepositoryDoc

ملاحظة: لا يتيح النموذج ListingConnector عرض null في طريقة getDoc(). تم عرض نتائج باللغة null في NullPointerException..

التعامل مع العناصر المحذوفة

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

ListTraversalSample.java
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

تجدر الإشارة إلى أن documents هي بنية بيانات تمثل المستودع. إذا لم يتم العثور على documentID في documents، يمكنك الرجوع إلى APIOperations.deleteItem(resourceName) لحذف العنصر من الفهرس.

التعامل مع العناصر التي لم يتم تغييرها

يعرض مقتطف الرمز التالي كيفية استطلاع حالة العنصر في قائمة انتظار فهرسة Cloud Search والتعامل مع عنصر لم يتم تغييره.

ListTraversalSample.java
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

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

ListTraversalSample.java
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

ضبط الأذونات لعنصر

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

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

توفر حزمة تطوير البرامج (SDK) لموصِّل المحتوى مجموعة ثرية من فئات وأساليب قائمة التحكم بالوصول (ACL) لتصميم قوائم التحكم بالوصول لمعظم المستودعات. يجب تحليل قائمة التحكم بالوصول لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول المقابلة لخدمة Google Cloud Search عند فهرسة أحد العناصر. إذا كانت قائمة التحكم في الوصول (ACL) في مستودعك تستخدم مفاهيم مثل وراثة قائمة التحكم بالوصول، فقد يكون نمذجة هذه القائمة أمرًا صعبًا. للحصول على مزيد من المعلومات عن قوائم التحكم بالوصول في Google Cloud Search، يُرجى مراجعة قوائم التحكم في الوصول (ACL) في Google Cloud Search.

ملاحظة: تتيح واجهة برمجة التطبيقات للفهرسة في Cloud Search قوائم التحكم بالوصول (ACL) لنطاق واحد. وهي لا تدعم قوائم التحكم بالوصول (ACLs) عبر النطاقات. استخدم الفئة Acl.Builder لضبط الوصول إلى كل عنصر باستخدام قائمة التحكم بالوصول (ACL). يتيح مقتطف الرمز التالي، المأخوذ من عيّنة الاجتياز الكامل، لجميع المستخدمين أو "المسؤولين" (getCustomerPrincipal()) أن يكونوا "قرّاء" لجميع العناصر (.setReaders()) عند إجراء بحث.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

تحتاج إلى فهم قوائم التحكم في الوصول (ACLs) لوضع نماذج لقوائم التحكم في الوصول (ACL) بشكلٍ صحيح للمستودع. على سبيل المثال، قد تفهرس ملفات داخل نظام ملفات يستخدم نوعًا من نموذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب نمذجة البيانات الموروثة لقائمة التحكم بالوصول (ACL) معلومات إضافية مشمولة في قوائم التحكم بالوصول (ACL) في Google Cloud Search

ضبط البيانات الوصفية لعنصر

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى حدّ أدنى من رقم تعريف السلسلة الفريد ونوع العنصر وقائمة التحكم بالوصول (ACL) وعنوان URL وإصدار العنصر. يوضّح مقتطف الرمز التالي كيفية إنشاء Item باستخدام فئة المساعدة IndexingItemBuilder.

ListTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

إنشاء عنصر قابل للفهرسة

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

ListTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc هو نوع من ApiOperation ينفّذ طلب IndexingService.indexItem() الفعلي.

يمكنك أيضًا استخدام طريقة setRequestMode() ضمن الفئة RepositoryDoc.Builder لتحديد طلب الفهرسة على أنّه ASYNCHRONOUS أو SYNCHRONOUS:

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

الخطوات التالية

في ما يلي بعض الخطوات التي يمكنك اتّخاذها:

  • (اختياري) نفِّذ طريقة close() لتحرير أي موارد قبل إيقاف التشغيل.
  • (اختياري) أنشئ موصِّل هوية باستخدام حزمة تطوير البرامج (SDK) لموصِّل المحتوى.

إنشاء موصل اجتياز الرسم البياني باستخدام فئة نموذج

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

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

يشير هذا القسم من المستندات إلى مقتطفات التعليمات البرمجية من مثال GraphTraversalSample.

تنفيذ نقطة دخول الموصل

نقطة الدخول إلى الموصّل هي طريقة main(). تتمثل المهمة الأساسية لهذه الطريقة في إنشاء مثيل للفئة Application واستدعاء طريقة start() الخاصة بها لتشغيل الموصل.

قبل استدعاء application.start()، استخدِم الفئة IndexingApplication.Builder لإنشاء مثيل للنموذج ListingConnector. يقبل ListingConnector كائن Repository يتم تنفيذ طرقه.

يوضّح المقتطف التالي كيفية إنشاء مثيل ListingConnector وRepository المرتبط به:

GraphTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

وراء الكواليس، تستدعي حزمة SDK الطريقة initConfig() بعد استدعاءات طريقة main() للموصل Application.build. طريقة initConfig():

  1. يتم استدعاء الطريقة Configuation.isInitialized() للتأكد من عدم تهيئة Configuration.
  2. تعمل هذه السياسة على إعداد كائن Configuration باستخدام أزواج المفتاح/القيمة التي توفّرها Google. يتم تخزين كل زوج مفتاح/قيمة في كائن ConfigValue داخل كائن Configuration.

تنفيذ واجهة Repository

الغرض الوحيد من الكائن Repository هو إجراء اجتياز عناصر المستودع وفهرستها. عند استخدام نموذج، ما عليك سوى إلغاء طُرق معيّنة ضمن واجهة Repository لإنشاء موصِّل محتوى. تعتمد الطرق التي تلغيها على القالب واستراتيجية الاجتياز التي تستخدمها. بالنسبة إلى ListingConnector، يمكنك إلغاء الطرق التالية:

  • الطريقة init(). لإجراء أي عملية إعداد لمستودع البيانات وإعداده، عليك إلغاء طريقة init().

  • الطريقة getIds() لاسترداد المعرّفات وقيم التجزئة لجميع السجلات في المستودع، يمكنك إلغاء طريقة getIds().

  • الطريقة getDoc() لإضافة عناصر جديدة أو تعديلها أو تعديلها أو حذفها من الفهرس، عليك إلغاء طريقة getDoc().

  • (اختياري) طريقة getChanges(). إذا كان المستودع يتيح رصد التغيير، يمكنك إلغاء طريقة getChanges(). يتم استدعاء هذه الطريقة مرة واحدة لكل عملية اجتياز تزايدي مجدول (كما هو محدد في التهيئة) لاسترداد العناصر المعدّلة وفهرستها.

  • (اختياري) طريقة close(). إذا كنت بحاجة إلى تنفيذ تنظيف المستودع، ألغِ الطريقة close(). ويتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف الموصل.

وتعرِض كل طريقة من طرق الكائن Repository نوعًا من أنواع ApiOperation. ينفِّذ الكائن ApiOperation إجراءً في شكل استدعاءات IndexingService.indexItem() واحدة أو عدة استدعاءات لإجراء الفهرسة الفعلية للمستودع.

الحصول على معلَمات ضبط مخصّصة

كجزء من معالجة إعدادات الموصل، عليك الحصول على أي معلَمات مخصّصة من الكائن Configuration. يتم تنفيذ هذه المهمة عادةً بطريقة Repository init() للصفوف.

تتضمن الفئة Configuration عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتُرجع كل طريقة عنصر ConfigValue. ستستخدم بعد ذلك طريقة get() للكائن ConfigValue لاسترداد القيمة الفعلية. يوضّح المقتطف التالي، من FullTraversalSample، كيفية استرداد قيمة عدد صحيح واحد مخصّصة من كائن Configuration:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

للحصول على معلَمة تحتوي على عدة قيم وتحليلها، استخدِم أحد المحللين اللغويين للفئة Configuration لتحليل البيانات في أجزاء منفصلة. يستخدم المقتطف التالي، من موصل البرنامج التعليمي، طريقة getMultiValue للحصول على قائمة بأسماء مستودعات GitHub:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

إجراء اجتياز الرسم البياني

تجاوز طريقة getIds() لاسترداد أرقام التعريف وقيم التجزئة لجميع السجلات في المستودع. تقبل الطريقة getIds() نقطة مرجعية. تُستخدم نقطة التفتيش لاستئناف الفهرسة عند عنصر معين في حال مقاطعة العملية.

بعد ذلك، يمكنك تجاهل الطريقة getDoc() لمعالجة كل عنصر في قائمة انتظار فهرسة Cloud Search.

إرسال معرّفات العناصر وقيم التجزئة

يمكنك تجاهل getIds() لجلب معرّفات السلع وقيم تجزئة المحتوى المرتبطة بها من المستودع. يتم بعد ذلك حزم أزواج المعرّف وقيمة التجزئة في طلب عملية دفع إلى قائمة انتظار فهرسة Cloud Search. عادةً ما يتم إرسال معرفات الجذر أو الأصل أولاً متبوعة بأرقام التعريف الفرعية حتى تتم معالجة التسلسل الهرمي بالكامل للعناصر.

تقبل الطريقة getIds() نقطة مرجعية تمثل آخر عنصر ستتم فهرسته. يمكن استخدام النقطة المرجعية لاستئناف الفهرسة عند عنصر محدّد في حال مقاطعة العملية. لكل عنصر في المستودع، نفِّذ هذه الخطوات باستخدام طريقة getIds():

  • احصل على كل معرّف سلعة وقيمة تجزئة مرتبطة من المستودع.
  • اجمع كل زوج من أرقام التعريف وقيمة التجزئة في PushItems.
  • ادمج كل PushItems في مُكرَّر يعرضه الطريقة getIds(). يُرجى العِلم أنّ السمة getIds() تعرض في الواقع عنصر CheckpointCloseableIterable وهو تكرار لعناصر ApiOperation، وكل عنصر يمثّل طلب واجهة برمجة تطبيقات يتم تنفيذه على RepositoryDoc، مثل دفع العناصر إلى قائمة الانتظار.

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

GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

يوضِّح مقتطف الرمز التالي كيفية استخدام الفئة PushItems.Builder لتجميع أرقام التعريف وقيم التجزئة في دفعة واحدة ApiOperation.

GraphTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

يتم إرسال العناصر إلى قائمة انتظار الفهرسة في Cloud Search لإجراء المزيد من المعالجة.

استرداد كل عنصر والتعامل معه

تجاهُل getDoc() لمعالجة كل عنصر في قائمة انتظار الفهرسة في Cloud Search يمكن أن يكون العنصر جديدًا أو معدَّلاً أو غير معدَّل أو لم يعُد متوفّرًا في مستودع المصدر. استرداد وفهرسته كل عنصر جديد أو معدّل. قم بإزالة العناصر من الفهرس والتي لم تعد موجودة في مستودع المصدر.

تقبل الطريقة getDoc() عنصرًا من قائمة انتظار الفهرسة في Cloud Search. لكل عنصر في قائمة الانتظار، نفِّذ الخطوات التالية في طريقة getDoc():

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

  2. تم تغيير الفهرس أو العناصر الجديدة:

    1. ضبط الأذونات
    2. اضبط البيانات الوصفية للعنصر الذي تريد فهرسته.
    3. ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة RepositoryDoc.
    4. يمكنك وضع أرقام التعريف الفرعية في قائمة انتظار الفهرسة في Cloud Search لإجراء المزيد من المعالجة.
    5. إرجاع RepositoryDoc

التعامل مع العناصر المحذوفة

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

GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

ضبط الأذونات لعنصر

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

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

توفر حزمة تطوير البرامج (SDK) لموصِّل المحتوى مجموعة ثرية من فئات وأساليب قائمة التحكم بالوصول (ACL) لتصميم قوائم التحكم بالوصول لمعظم المستودعات. يجب تحليل قائمة التحكم بالوصول لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول المقابلة لخدمة Google Cloud Search عند فهرسة أحد العناصر. إذا كانت قائمة التحكم في الوصول (ACL) في مستودعك تستخدم مفاهيم مثل وراثة قائمة التحكم بالوصول، فقد يكون نمذجة هذه القائمة أمرًا صعبًا. للحصول على مزيد من المعلومات عن قوائم التحكم بالوصول في Google Cloud Search، يُرجى مراجعة قوائم التحكم في الوصول (ACL) في Google Cloud Search.

ملاحظة: تتيح واجهة برمجة التطبيقات للفهرسة في Cloud Search قوائم التحكم بالوصول (ACL) لنطاق واحد. وهي لا تدعم قوائم التحكم بالوصول (ACLs) عبر النطاقات. استخدم الفئة Acl.Builder لضبط الوصول إلى كل عنصر باستخدام قائمة التحكم بالوصول (ACL). يتيح مقتطف الرمز التالي، المأخوذ من عيّنة الاجتياز الكامل، لجميع المستخدمين أو "المسؤولين" (getCustomerPrincipal()) أن يكونوا "قرّاء" لجميع العناصر (.setReaders()) عند إجراء بحث.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

تحتاج إلى فهم قوائم التحكم في الوصول (ACLs) لوضع نماذج لقوائم التحكم في الوصول (ACL) بشكلٍ صحيح للمستودع. على سبيل المثال، قد تفهرس ملفات داخل نظام ملفات يستخدم نوعًا من نموذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب نمذجة البيانات الموروثة لقائمة التحكم بالوصول (ACL) معلومات إضافية مشمولة في قوائم التحكم بالوصول (ACL) في Google Cloud Search

ضبط البيانات الوصفية لعنصر

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى حدّ أدنى من رقم تعريف السلسلة الفريد ونوع العنصر وقائمة التحكم بالوصول (ACL) وعنوان URL وإصدار العنصر. يوضّح مقتطف الرمز التالي كيفية إنشاء Item باستخدام فئة المساعدة IndexingItemBuilder.

GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

إنشاء عنصر قابل للفهرسة

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

GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

RepositoryDoc هو نوع من ApiOperation ينفّذ طلب IndexingService.indexItem() الفعلي.

يمكنك أيضًا استخدام طريقة setRequestMode() ضمن الفئة RepositoryDoc.Builder لتحديد طلب الفهرسة على أنّه ASYNCHRONOUS أو SYNCHRONOUS:

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

وضع أرقام التعريف الفرعية في قائمة انتظار الفهرسة في Cloud Search

يعرض مقتطف الرمز التالي كيفية تضمين المعرّفات الفرعية، للعنصر الرئيسي الذي تتم معالجته حاليًا، في قائمة انتظار المعالجة. تتم معالجة المعرفات هذه بعد فهرسة العنصر الرئيسي.

GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

الخطوات التالية

في ما يلي بعض الخطوات التي يمكنك اتّخاذها:

  • (اختياري) نفِّذ طريقة close() لتحرير أي موارد قبل إيقاف التشغيل.
  • (اختياري) أنشئ موصِّل هوية باستخدام حزمة SDK لموصِّل الهوية.

إنشاء موصِّل محتوى باستخدام واجهة برمجة تطبيقات REST

تشرح الأقسام التالية كيفية إنشاء موصل محتوى باستخدام REST API.

تحديد استراتيجية الاجتياز

تكمن الوظيفة الأساسية لموصل المحتوى في اجتياز مستودع وفهرسة بياناته. يجب عليك تنفيذ استراتيجية الاجتياز بناءً على حجم البيانات وتخطيطها في مستودعك. فيما يلي ثلاث استراتيجيات اجتياز شائعة:

استراتيجية الاجتياز الكامل

تعمل استراتيجية الاجتياز الكاملة على فحص المستودع بأكمله وفهرسة كل عنصر بشكل عشوائي. تُستخدم هذه الإستراتيجية بشكل شائع عندما يكون لديك مستودع صغير وتتحمل النفقات العامة لإجراء اجتياز كامل في كل مرة تفهرس فيها.

تُعد استراتيجية الاجتياز هذه مناسبة للمستودعات الصغيرة التي تحتوي في الغالب على بيانات ثابتة وغير هرمية. يمكنك أيضًا استخدام استراتيجية الاجتياز هذه عندما يكون اكتشاف التغيير صعبًا أو غير متاح في المستودع.

إدراج استراتيجية الاجتياز

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

استراتيجية الاجتياز هذه مناسبة عندما يكون اكتشاف التغيير صعبًا أو لا يدعمه المستودع، وكانت لديك بيانات غير هرمية، وتعمل على مجموعات بيانات كبيرة جدًا.

اجتياز الرسم البياني

تفحص استراتيجية اجتياز الرسم البياني العقدة الرئيسية بأكملها لتحديد حالة كل عنصر. بعد ذلك، يأخذ الموصل تمريرة ثانية ولا يفهرس سوى العناصر في العقدة الجذرية الجديدة أو التي تم تحديثها منذ آخر فهرسة. أخيرًا، يمرر الموصل أي معرّفات فرعية ثم يفهرس العناصر الجديدة أو التي تم تحديثها في العُقد الفرعية. يستمر الموصل بشكل متكرر من خلال جميع العُقد الفرعية حتى تتم معالجة جميع العناصر. عادةً ما يستخدم هذا الاجتياز للمستودعات الهرمية حيث لا تكون سرد جميع أرقام التعريف عملية.

هذه الاستراتيجية مناسبة إذا كانت لديك بيانات هرمية تحتاج إلى الزحف، مثل أدلة السلاسل أو صفحات الويب.

تنفيذ استراتيجية الاجتياز وفهرسة العناصر

يُشار إلى كل عنصر قابل للفهرسة في Cloud Search باسم عنصر في Cloud Search API. قد يكون العنصر ملفًا أو مجلدًا أو سطرًا في ملف CSV أو سجل قاعدة بيانات.

بعد تسجيل المخطط، يمكنك تعبئة الفهرس من خلال:

  1. (اختياري) استخدام items.upload لتحميل ملفات يزيد حجمها عن 100 كيلوبايت للفهرسة بالنسبة إلى الملفات الأصغر حجمًا، يمكنك تضمين المحتوى بتنسيق inlineContent باستخدام items.index.

  2. (اختياري) استخدام media.upload لتحميل ملفات الوسائط لفهرستها.

  3. استخدام items.index لفهرسة العنصر. على سبيل المثال، إذا كان المخطط يستخدم تعريف الكائن في مخطط الفيلم، سيظهر طلب الفهرسة لعنصر واحد على النحو التالي:

    {
      "name": "datasource/<data_source_id>/items/titanic",
      "acl": {
        "readers": [
          {
            "gsuitePrincipal": {
              "gsuiteDomain": true
            }
          }
        ]
      },
      "metadata": {
        "title": "Titanic",
        "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
        "objectType": "movie"
      },
      "structuredData": {
        "object": {
          "properties": [
            {
              "name": "movieTitle",
              "textValues": {
                "values": [
                  "Titanic"
                ]
              }
            },
            {
              "name": "releaseDate",
              "dateValues": {
                "values": [
                  {
                    "year": 1997,
                    "month": 12,
                    "day": 19
                  }
                ]
              }
            },
            {
              "name": "actorName",
              "textValues": {
                "values": [
                  "Leonardo DiCaprio",
                  "Kate Winslet",
                  "Billy Zane"
                ]
              }
            },
            {
              "name": "genre",
              "enumValues": {
                "values": [
                  "Drama",
                  "Action"
                ]
              }
            },
            {
              "name": "userRating",
              "integerValues": {
                "values": [
                  8
                ]
              }
            },
            {
              "name": "mpaaRating",
              "textValues": {
                "values": [
                  "PG-13"
                ]
              }
            },
            {
              "name": "duration",
              "textValues": {
                "values": [
                  "3 h 14 min"
                ]
              }
            }
          ]
        }
      },
      "content": {
        "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
        "contentFormat": "TEXT"
      },
      "version": "01",
      "itemType": "CONTENT_ITEM"
    }
    
  4. (اختياري) باستخدام طلبات items.get للتحقق من فهرسة عنصر.

لإجراء اجتياز كامل، يجب إعادة فهرسة المستودع بأكمله بشكل دوري. لإجراء اجتياز قائمة أو رسم بياني، عليك تنفيذ رمز للتعامل مع تغييرات المستودع.

التعامل مع تغييرات المستودع

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

وبدلاً من استخدام طلبات الفهرسة لفهرسة مستودع بأكمله من حين لآخر، يمكنك أيضًا استخدام قائمة انتظار الفهرسة في Google Cloud كآلية لتتبُّع التغييرات وفهرسة العناصر التي طرأ عليها تغيير فقط. يمكنك استخدام طلبات items.push لدفع العناصر إلى قائمة الانتظار من أجل إجراء استطلاعات لها وتعديلها لاحقًا. للحصول على مزيد من المعلومات حول قائمة انتظار الفهرسة في Google Cloud، يمكنك الرجوع إلى قائمة انتظار فهرسة Google Cloud.

للحصول على مزيد من المعلومات حول Google Cloud Search API، يُرجى الاطّلاع على Cloud Search API.