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

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

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

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

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

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

إنشاء أداة ربط محتوى باستخدام حزمة تطوير البرامج لـ Content Connector

توضّح الأقسام التالية كيفية إنشاء موصِّل محتوى باستخدام حزمة تطوير البرامج (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) للعنصر عند فهرسة أحد العناصر حتى يكون لدى Google Cloud Search المعلومات التي يحتاج إليها لتوفير مستوى الوصول الصحيح إلى العنصر.

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

ملاحظة: تتوافق واجهة برمجة التطبيقات للفهرسة في Cloud Search مع قوائم التحكم بالوصول (ACL) ذات النطاق الواحد. لا يدعم قوائم التحكم في الوصول عبر النطاقات. استخدِم الفئة 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 في Google Cloud Search

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

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى ما لا يقل عن معرّف سلسلة فريد، ونوع العنصر، وقائمة التحكم بالوصول، وعنوان 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) للعنصر عند فهرسة أحد العناصر حتى يكون لدى Google Cloud Search المعلومات التي يحتاج إليها لتوفير مستوى الوصول الصحيح إلى العنصر.

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

ملاحظة: تتوافق واجهة برمجة التطبيقات للفهرسة في Cloud Search مع قوائم التحكم بالوصول (ACL) ذات النطاق الواحد. لا يدعم قوائم التحكم في الوصول عبر النطاقات. استخدِم الفئة 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 في Google Cloud Search

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

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى ما لا يقل عن معرّف سلسلة فريد، ونوع العنصر، وقائمة التحكم بالوصول، وعنوان 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) لـ Content Connector.

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

تُستخدم قائمة انتظار الفهرسة في 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) للعنصر عند فهرسة أحد العناصر حتى يكون لدى Google Cloud Search المعلومات التي يحتاج إليها لتوفير مستوى الوصول الصحيح إلى العنصر.

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

ملاحظة: تتوافق واجهة برمجة التطبيقات للفهرسة في Cloud Search مع قوائم التحكم بالوصول (ACL) ذات النطاق الواحد. لا يدعم قوائم التحكم في الوصول عبر النطاقات. استخدِم الفئة 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 في Google Cloud Search

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

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى ما لا يقل عن معرّف سلسلة فريد، ونوع العنصر، وقائمة التحكم بالوصول، وعنوان 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.

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

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

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

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

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

استراتيجية اجتياز القائمة

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

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

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

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

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

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

تتم الإشارة إلى كل عنصر قابل للفهرسة في Cloud Search باعتباره عنصرًا في واجهة برمجة تطبيقات Cloud Search. قد يكون العنصر ملفًا أو مجلدًا أو سطرًا في ملف 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، يُرجى الرجوع إلى Cloud Search API.