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

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

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

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

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

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

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

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

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

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

Maven

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

Gradle

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

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

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

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

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

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

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

تمرير ملف الضبط إلى الموصِّل

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

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

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

تحديد استراتيجية التنقّل

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

استراتيجية التنقّل الكامل

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

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

استراتيجية تنقّل القائمة

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

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

التنقّل في الرسم البياني

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

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

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

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

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

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

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

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

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

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

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

إجراء تنقّل كامل

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

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

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

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

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

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

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

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

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

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

يتم تخزين البيانات الوصفية في عنصر Item. لإنشاء Item، تحتاج إلى حدّ أدنى من معرّف سلسلة فريد ونوع العنصر وقائمة التحكّم بالوصول وعنوان 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();

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

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

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

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

تُستخدَم "قائمة انتظار فهرسة 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(). يتمّ استدعاء هذه الطريقة مرّة واحدة لكلّ عملية اجتياز تصاعدي مجدوَلة (على النحو المحدّد في الإعدادات) لاسترداد العناصر المعدّلة و index index.

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

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

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

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

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

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

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

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

تنفيذ تنقّل القائمة

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

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

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

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

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

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

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

  • طريقة getIds() لاسترداد أرقام التعريف وقيم التجزئة لجميع السجلّات في المستودع، استبدِل طريقة getIds().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

أنشئ العنصر القابل للفهرسة.

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

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

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

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

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

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

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

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

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

RepositoryDoc doc = docBuilder.build();

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

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

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

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

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

تحديد استراتيجية التنقّل

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

استراتيجية التنقّل الكامل

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

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

استراتيجية تنقّل القائمة

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

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

التنقّل في الرسم البياني

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

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

تنفيذ استراتيجية التنقّل والفهرسة

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