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

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

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

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

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

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

  1. قراءة معلمات التهيئة ومعالجتها.
  2. يسحب أجزاء منفصلة من البيانات القابلة للفهرسة، تسمى "items"، من مستودع المحتوى التابع لجهة خارجية.
  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 حيث تحدد هذه المعلمات موقع مستودعك والمفتاح الخاص اللازم للوصول إلى المستودع.
  • بالنسبة إلى موصِّل الهوية، عليك الإعلان عن 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. وستستخدم عندئذٍ طريقة الكائن ConfigValue في get() لاسترداد القيمة الفعلية. يعرض المقتطف التالي، من FullTraversalSample، كيفية استرداد قيمة عدد صحيح مخصّصة واحدة من كائن Configuration:

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

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

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

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

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

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

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

تعيين الأذونات لأحد العناصر

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

وضع كل عنصر قابل للفهرسة في مكرّر

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

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

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

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

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

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

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

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

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

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

إجراء عملية المسح في القائمة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تعيين الأذونات لأحد العناصر

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنفيذ عملية اجتياز الرسم البياني

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

RepositoryDoc doc = docBuilder.build();

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

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

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

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

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

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

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

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

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

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

استراتيجية المسح في قائمة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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