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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

يؤدي موصل المحتوى المعتاد المهام التالية:

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

إنشاء موصِّل محتوى باستخدام حزمة SDK لموصِّل المحتوى

توضّح الأقسام التالية كيفية إنشاء موصِّل محتوى باستخدام Content 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). يمكنك تنفيذ استراتيجيتك الخاصة بالاجتياز، ولكن هذه النماذج تُسرّع كثيرًا عملية تطوير الموصِّل. لإنشاء موصل باستخدام نموذج، انتقِل إلى القسم المقابل لاستراتيجية الاجتياز:

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

يشير هذا القسم من المستندات إلى مقتطفات الرمز من المثال كاملTraversalSample.

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

نقطة الإدخال إلى الموصّل هي طريقة 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 class's init().

تحتوي الفئة Configuration على عدة طرق للحصول على أنواع مختلفة من البيانات من الإعدادات. تعرض كل طريقة عنصر ConfigValue. بعد ذلك، ستستخدم طريقة العنصر ConfigValue get() لاسترداد القيمة الفعلية. يعرض المقتطف التالي، من 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) وأساليب لوضع نماذج قوائم التحكم بالوصول (ACL) لمعظم المستودعات. يجب تحليل قائمة التحكُّم بالوصول (ACL) لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول (ACL) المقابلة لـ Google Cloud Search عند فهرسة عنصر. إذا كانت قائمة التحكم في الوصول (ACL) في مستودعك تستخدم مفاهيم مثل اكتساب قائمة التحكم بالوصول (ACL)، يمكن أن يكون وضع نموذج لقائمة التحكم في الوصول أمرًا صعبًا. للحصول على مزيد من المعلومات عن قوائم التحكم بالوصول (ACL) لخدمة Google Cloud Search، يمكنك الاطّلاع على قوائم التحكم في الوصول (ACL) في Google Cloud Search.

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

ستحتاج إلى فهم قوائم ACL لتصميم نموذج قوائم التحكم بالوصول (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، يُرجى الرجوع إلى قائمة انتظار فهرسة Google 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 class's init().

تحتوي الفئة Configuration على عدة طرق للحصول على أنواع مختلفة من البيانات من الإعدادات. تعرض كل طريقة عنصر ConfigValue. بعد ذلك، ستستخدم طريقة العنصر ConfigValue get() لاسترداد القيمة الفعلية. يعرض المقتطف التالي، من 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) وأساليب لوضع نماذج قوائم التحكم بالوصول (ACL) لمعظم المستودعات. يجب تحليل قائمة التحكُّم بالوصول (ACL) لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول (ACL) المقابلة لـ Google Cloud Search عند فهرسة عنصر. إذا كانت قائمة التحكم في الوصول (ACL) في مستودعك تستخدم مفاهيم مثل اكتساب قائمة التحكم بالوصول (ACL)، يمكن أن يكون وضع نموذج لقائمة التحكم في الوصول أمرًا صعبًا. للحصول على مزيد من المعلومات عن قوائم التحكم بالوصول (ACL) لخدمة Google Cloud Search، يمكنك الاطّلاع على قوائم التحكم في الوصول (ACL) في Google Cloud Search.

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

ستحتاج إلى فهم قوائم ACL لتصميم نموذج قوائم التحكم بالوصول (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 بقوائم الانتظار وتقارن محتوى قائمة الانتظار بتحديد حالة السلعة، مثل حذف عنصر من المستودع. للحصول على مزيد من المعلومات حول قائمة انتظار فهرسة "بحث Google"، يمكنك الاطّلاع على قائمة انتظار فهرسة 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 class's init().

تحتوي الفئة Configuration على عدة طرق للحصول على أنواع مختلفة من البيانات من الإعدادات. تعرض كل طريقة عنصر ConfigValue. بعد ذلك، ستستخدم طريقة العنصر ConfigValue get() لاسترداد القيمة الفعلية. يعرض المقتطف التالي، من 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() عنصرًا من قائمة انتظار البحث في Google. بالنسبة إلى كل عنصر في قائمة الانتظار، نفِّذ الخطوات التالية باستخدام الطريقة 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) وأساليب لوضع نماذج قوائم التحكم بالوصول (ACL) لمعظم المستودعات. يجب تحليل قائمة التحكُّم بالوصول (ACL) لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول (ACL) المقابلة لـ Google Cloud Search عند فهرسة عنصر. إذا كانت قائمة التحكم في الوصول (ACL) في مستودعك تستخدم مفاهيم مثل اكتساب قائمة التحكم بالوصول (ACL)، يمكن أن يكون وضع نموذج لقائمة التحكم في الوصول أمرًا صعبًا. للحصول على مزيد من المعلومات عن قوائم التحكم بالوصول (ACL) لخدمة Google Cloud Search، يمكنك الاطّلاع على قوائم التحكم في الوصول (ACL) في Google Cloud Search.

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

ستحتاج إلى فهم قوائم ACL لتصميم نموذج قوائم التحكم بالوصول (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 API

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

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

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

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

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

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

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

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

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

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

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

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

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

ويُشار إلى كل عنصر قابل للفهرسة في Google 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.

للحصول على مزيد من المعلومات عن واجهة برمجة تطبيقات Cloud Search REST، يُرجى الرجوع إلى Cloud Search API.