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

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

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

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

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

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

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

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

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

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

Maven

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

Gradle

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

إنشاء ضبط الموصل

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنفيذ واجهة Repository

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

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

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

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

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

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

الحصول على مَعلمات الإعدادات المخصّصة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنفيذ واجهة Repository

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

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

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

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

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

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

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

الحصول على مَعلمات الإعدادات المخصّصة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يوضّح المقتطف التالي طريقة بدء ListingConnector وسمة Repository المرتبطة بها:

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

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

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

تنفيذ واجهة Repository

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

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

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

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

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

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

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

الحصول على مَعلمات الإعدادات المخصّصة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

RepositoryDoc doc = docBuilder.build();

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

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

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

إنشاء موصِّل محتوى باستخدام REST API

تشرح الأقسام التالية طريقة إنشاء موصِّل محتوى باستخدام RST API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  4. (اختياري) باستخدام طلبات items.get للتحقق من فهرسة عنصر.

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

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

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

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

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