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

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

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

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

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

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

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

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

إعداد المهام التابعة

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

Maven

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

Gradle

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

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

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

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

• بالنسبة إلى مُوصِّل المحتوى، يجب تحديد api.sourceId وapi.serviceAccountPrivateKeyFile لأنّ هذه المَعلمات تحدّد الموقع الجغرافي للمستودع والمفتاح الخاص المطلوب للوصول إلى المستودع.

ملاحظة: إذا لم يكن ملف المفتاح الخاص مفتاح 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" و"document" إلى المرادف في هذا المستند والرمز النموذجي.

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

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

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

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

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

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

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

TotalTraversalSample.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:

TotalTraversalSample.java

العرض على GitHub

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

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

GithubRepositoryjava.

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

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

TotalTraversalSample.java

العرض على GitHub

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

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

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

TotalTraversalSample.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. يوضّح المثال التالي كيفية إنشاء عنصر واحد قابل للفهرسة.

TotalTraversalSample.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 لإنشاء مكرّر وإرجاعه. يوضح مقتطف الرمز التالي كيفية إنشاء مكرّر وإرجاعه.

TotalTraversalSample.java

العرض على GitHub

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

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

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

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

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

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

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

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

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

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

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

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

ListTraversalSample.java

العرض على 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:

TotalTraversalSample.java

العرض على GitHub

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

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

GithubRepositoryjava.

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

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

TotalTraversalSample.java

العرض على GitHub

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

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

يتم تخزين البيانات الوصفية في عنصر 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) لموصِّل المحتوى.

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

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

TotalTraversalSample.java

العرض على GitHub

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

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

GithubRepositoryjava.

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

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

TotalTraversalSample.java

العرض على GitHub

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

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

يتم تخزين البيانات الوصفية في عنصر 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() لسحب أي موارد قبل إيقاف التشغيل.
• (اختياري) أنشِئ موصِّل هوية باستخدام حزمة SDK Connector Connector.

إنشاء أداة ربط للمحتوى باستخدام REST API

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: تشير العبارتان "item" و"document" إلى المرادف في هذا المستند والرمز النموذجي.

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

يُشار إلى كل عنصر قابل للفهرسة في 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 للتحقّق من أحد العناصر.

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

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

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

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

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

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

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