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

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

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

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

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

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

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

توضّح الأقسام التالية كيفية إنشاء موصِّل محتوى باستخدام حزمة تطوير البرامج لـ Content Connector

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

يجب عليك تضمين تبعيات معينة في ملف الإصدار لاستخدام 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 لأنّ هذه المَعلمات تحدّد الموقع الجغرافي من المستودع والمفتاح الخاص المطلوب للوصول إلى المستودع.

ملاحظة: إذا لم يكن ملف المفتاح الخاص مفتاح JSON، يجب أيضًا إلغاء api.serviceAccountId.

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

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

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

ملاحظة: ما مِن متطلبات صارمة لتسمية الموصل. هذه السمة، ولكننا ننصح بحفظ الملف باستخدام .properties أو .config إضافة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: المصطلحات "item" و"المستند" مترادفان في هذا المستند الرمز النموذجي.

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

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

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

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

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

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

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

FullTraversalSample.java

عرض على GitHub

/**
 * 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. ستطبق بعد ذلك استخدام كائن ConfigValue get() لاسترداد القيمة الفعلية. المقتطف التالي، من FullTraversalSample, كيفية استرداد قيمة عدد صحيح مخصّص واحدة من عنصر Configuration:

FullTraversalSample.java

عرض على GitHub

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

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

GithubRepository.java

عرض على GitHub

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

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

FullTraversalSample.java

عرض على GitHub

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

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

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

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

FullTraversalSample.java

عرض على GitHub

// 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

عرض على GitHub

// 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

عرض على GitHub

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

تنفّذ حزمة تطوير البرامج (SDK) كل طلب فهرسة مضمَّن في المكرّر.

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

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

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

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

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

يتم استخدام قائمة انتظار الفهرسة في 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

عرض على GitHub

/**
 * 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. ستطبق بعد ذلك استخدام كائن ConfigValue get() لاسترداد القيمة الفعلية. المقتطف التالي، من FullTraversalSample, كيفية استرداد قيمة عدد صحيح مخصّص واحدة من عنصر Configuration:

FullTraversalSample.java

عرض على GitHub

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

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

GithubRepository.java

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

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

FullTraversalSample.java

عرض على GitHub

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

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

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

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

ListTraversalSample.java

عرض على GitHub

// 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

عرض على GitHub

// 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.

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

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

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

• (اختياري) نفِّذ 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، كاستراتيجية اجتياز القائمة.

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

GraphTraversalSample.java

عرض على GitHub

/**
 * 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. ستطبق بعد ذلك استخدام كائن ConfigValue get() لاسترداد القيمة الفعلية. المقتطف التالي، من FullTraversalSample, كيفية استرداد قيمة عدد صحيح مخصّص واحدة من عنصر Configuration:

FullTraversalSample.java

عرض على GitHub

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

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

GithubRepository.java

عرض على GitHub

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

عرض على GitHub

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

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

GraphTraversalSample.java

عرض على GitHub

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

عرض على GitHub

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

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

FullTraversalSample.java

عرض على GitHub

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

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

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

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

GraphTraversalSample.java

عرض على GitHub

// 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

عرض على GitHub

// 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

عرض على GitHub

// 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();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: المصطلحات "item" و"المستند" مترادفان في هذا المستند الرمز النموذجي.

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

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

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

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

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

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

   {
     "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 الطلبات للتحقّق من عنصر تمت فهرسة.

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

ملاحظة: يجب أن يتطابق الحقل objectType في ItemMetadata مع الكائن. اسم تعريف في المخطط. وبهذه الطريقة، يحدد Cloud Search البيانات بنية العنصر في طلب الفهرس. في طلب الفهرسة، إذا إرسال بيانات منظَّمة تحتوي على مواقع غير مسجّلة في الموقع الإلكتروني الحالي أو إعطاء نوع كائن لا يتوافق مع اسم تعريفات الكائن في المخطط، يتم تجاهل الكائن أو الخاصية. بالإضافة إلى ذلك، في حال إرسال مواقع من نوع مختلف عن النوع مسجَّلة في المخطط، تعرض خدمة Cloud Search رد خطأ عند الفهرسة الوقت.

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

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

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

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

لمزيد من المعلومات حول Google Cloud Search API، يمكنك الاطّلاع على واجهة برمجة تطبيقات Cloud Search: