موصِّل المحتوى هو برنامج يُستخدَم لاجتياز البيانات في مستودع مؤسسة وتعبئة مصدر البيانات. توفر Google الخيارات التالية لتطوير موصلات المحتوى:
حزمة تطوير البرامج (SDK) لموصِّل المحتوى يعد هذا خيارًا جيدًا إذا كنت تبرمج بلغة Java. Content Connector SDK هي أداة تضمين حول واجهة برمجة تطبيقات REST تتيح لك إنشاء الموصلات بسرعة. لإنشاء موصل محتوى باستخدام حزمة SDK، راجع إنشاء موصِّل محتوى باستخدام حزمة تطوير البرامج (SDK) لموصِّل المحتوى.
مكتبات واجهة برمجة تطبيقات REST أو واجهة برمجة تطبيقات منخفضة المستوى استخدم هذه الخيارات إذا لم تكن مبرمجًا بلغة Java، أو إذا كانت قاعدة التعليمات البرمجية تتوافق بشكل أفضل مع واجهة برمجة تطبيقات RST أو مكتبة. لإنشاء موصِّل محتوى باستخدام REST API، يمكنك الاطّلاع على المقالة إنشاء موصِّل محتوى باستخدام REST API.
ينفِّذ موصِّل المحتوى النموذجي المهام التالية:
- يقرأ معلمات التكوين ويعالجها.
- سحب مجموعات منفصلة من البيانات القابلة للفهرسة تُسمى "items" من مستودع المحتوى التابع لجهة خارجية.
- دمج قوائم التحكم بالوصول والبيانات الوصفية وبيانات المحتوى في عناصر قابلة للفهرسة.
- لفهرسة العناصر لمصدر بيانات Cloud Search.
- (اختياري) يستمع إلى إشعارات التغيير من مستودع المحتوى التابع لجهة خارجية. يتم تحويل إشعارات التغيير إلى طلبات فهرسة للحفاظ على تزامن مصدر بيانات 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()
:
وراء الكواليس، تستدعي حزمة تطوير البرامج (SDK) الطريقة
initConfig()
بعد استدعاءات طريقة main()
للموصل
Application.build
.
تنفِّذ طريقة initConfig()
المهام التالية:
- لاستدعاء الطريقة
Configuation.isInitialized()
لضمان عدم إعدادConfiguration
. - لإعداد كائن
Configuration
باستخدام أزواج المفتاح/القيمة التي توفّرها Google يتم تخزين كل زوج مفتاح/قيمة في عنصرConfigValue
داخل كائنConfiguration
.
تنفيذ واجهة Repository
الغرض الوحيد من كائن Repository
هو اجتياز عناصر المستودع وفهرستها. عند استخدام نموذج، ما عليك سوى إلغاء طرق معيّنة ضمن واجهة Repository
لإنشاء موصِّل محتوى. تعتمد الطرق التي تتجاهلها على
القالب واستراتيجية الاجتياز التي تستخدمها. بالنسبة إلى FullTraversalConnector
، يمكنك إلغاء الطرق التالية:
الطريقة
init()
. لإجراء أي عملية إعداد أو إعداد لمستودع البيانات، يجب إلغاء طريقةinit()
.الطريقة
getAllDocs()
. لاجتياز جميع العناصر في مستودع البيانات وفهرستها، يجب إلغاء طريقةgetAllDocs()
. يتم استدعاء هذه الطريقة مرة واحدة لكل اجتياز مجدول (كما هو محدد من خلال التهيئة).(اختياري) طريقة
getChanges()
. إذا كان مستودعك يتيح رصد التغييرات، يمكنك إلغاء طريقةgetChanges()
. يتم استدعاء هذه الطريقة مرة واحدة لكل عملية اجتياز متزايد مجدول (كما هو محدد في التهيئة) لاسترداد العناصر المعدلة وفهرستها.(اختياري) طريقة
close()
. وإذا كنت بحاجة إلى تنظيف المستودع، يمكنك إلغاء الطريقةclose()
. يتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف تشغيل الموصل.
تؤدي كل طريقة من طرق الكائن Repository
إلى عرض نوع من كائنات ApiOperation
. ينفِّذ الكائن ApiOperation
إجراءً في شكل طلب IndexingService.indexItem()
واحد أو عدة استدعاءات لتنفيذ الفهرسة الفعلية للمستودع.
الحصول على مَعلمات الإعدادات المخصّصة
كجزء من معالجة إعدادات الموصِّل، ستحتاج إلى الحصول على أي مَعلمات مخصّصة من الكائن Configuration
. يتم تنفيذ هذه المهمة عادةً بطريقة
Repository
الصف
init()
.
تتضمن الفئة Configuration
عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتعرض كل طريقة عنصر ConfigValue
. ستستخدم بعد ذلك طريقة
get()
للكائن ConfigValue
لاسترداد القيمة الفعلية.
يعرض المقتطف التالي، من FullTraversalSample
، كيفية استرداد قيمة عدد صحيح واحد مخصّص من كائن Configuration
:
للحصول على معلَمة تحتوي على قيم متعدّدة وتحليلها، استخدِم أحد برامج التحليل اللغوي للفئة Configuration
لتحليل البيانات إلى أجزاء منفصلة.
يستخدم المقتطف التالي من موصِّل البرنامج التعليمي طريقة
getMultiValue
للحصول على قائمة بأسماء مستودعات GitHub:
إجراء الاجتياز الكامل
تجاهُل
getAllDocs()
لإجراء مسح كامل وفهرسة المستودع تقبل الطريقة getAllDocs()
نقطة مرجعية. يتم استخدام النقطة المرجعية لاستئناف الفهرسة عند عنصر محدد في حال مقاطعة العملية. لكل عنصر في مستودعك، نفِّذ هذه الخطوات في طريقة getAllDocs()
:
- ضبط الأذونات
- اضبط البيانات الوصفية للعنصر الذي تريد فهرسته.
- ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة
RepositoryDoc
. - أنشئ حزمة كل عنصر قابل للفهرسة في تكرار تعرضه الطريقة
getAllDocs()
. يُرجى العِلم أنّ السمةgetAllDocs()
تعرض العنصرCheckpointCloseableIterable
وهو تكرار لكائناتApiOperation
، ويمثّل كل عنصر طلب بيانات من واجهة برمجة التطبيقات تم تنفيذه علىRepositoryDoc
، مثل فهرسته.
إذا كانت مجموعة العناصر كبيرة جدًا بحيث لا يمكن معالجتها في مكالمة واحدة، يمكنك تضمين
نقطة تحقّق وضبط الرمز
hasMore(true)
للإشارة إلى توفّر المزيد من العناصر للفهرسة.
ضبط الأذونات لعنصر واحد
يستخدم مستودعك قائمة التحكم بالوصول (ACL) لتحديد المستخدمين أو المجموعات التي يمكنها الوصول إلى عنصر. قائمة التحكم بالوصول هي قائمة بمعرفات المجموعات أو المستخدمين الذين يمكنهم الوصول إلى العنصر.
يجب عليك إنشاء نسخة طبق الأصل من قائمة التحكم بالوصول (ACL) المستخدمة في مستودعك لضمان أنّ المستخدمين الذين لديهم حق الوصول إلى العنصر هم وحدهم الذين يمكنهم الاطّلاع على هذا العنصر في نتيجة البحث. يجب تضمين قائمة التحكم بالوصول (ACL) للعنصر عند فهرسة عنصر بحيث يحصل Google Cloud Search على المعلومات اللازمة لتوفير مستوى الوصول الصحيح إلى العنصر.
توفر حزمة Content Connector SDK مجموعة غنية من فئات وأساليب قائمة التحكم بالوصول (ACL) لتصميم قوائم التحكم بالوصول لمعظم المستودعات. يجب تحليل قائمة التحكم بالوصول (ACL) لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول المقابلة لخدمة Google Cloud Search عند فهرسة أحد العناصر. إذا كانت قائمة التحكم بالوصول في المستودع تستخدم مفاهيم مثل اكتساب قائمة التحكم بالوصول، فقد يكون من الصعب إعداد نماذج قائمة التحكم بالوصول. للحصول على مزيد من المعلومات عن قوائم التحكم في الوصول في Google Cloud Search، يُرجى الرجوع إلى قوائم التحكم في الوصول في Google Cloud Search.
ملاحظة: تتيح واجهة برمجة التطبيقات للفهرسة في Cloud Search قوائم التحكم في الوصول (ACL) لنطاق واحد. ولا يدعم قوائم التحكم بالوصول عبر النطاقات. يمكنك استخدام فئة Acl.Builder
لضبط الوصول إلى كل عنصر باستخدام قائمة التحكم بالوصول. يُتيح مقتطف الرمز التالي، المأخوذ من عينة الاجتياز الكامل،
لجميع المستخدمين أو "المدراء"
(getCustomerPrincipal()
)
أن يكونوا "قراء" لجميع العناصر
(.setReaders()
)
عند إجراء بحث.
يجب عليك استيعاب قوائم التحكم بالوصول (ACLs) لتصميم قوائم التحكم بالوصول للمستودع بشكل صحيح. على سبيل المثال، قد تكون تفهرس ملفات داخل نظام ملفات يستخدم نوعًا من نموذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب إعداد البيانات الموروثة لقائمة التحكم بالوصول معلومات إضافية يتم تناولها في قوائم التحكم بالوصول في Google Cloud Search
ضبط البيانات الوصفية لعنصر
يتم تخزين البيانات الوصفية في عنصر Item
. لإنشاء Item
، يجب أن يكون لديك
حدّ أدنى من معرّف سلسلة فريد ونوع العنصر وقائمة التحكم في الوصول (ACL) وعنوان URL وإصدار العنصر.
يوضِّح مقتطف الرمز التالي كيفية إنشاء Item
باستخدام فئة المساعدة
IndexingItemBuilder
.
إنشاء عنصر قابل للفهرسة
بعد ضبط البيانات الوصفية للعنصر، يمكنك إنشاء العنصر الفعلي القابل للفهرسة باستخدام الفئة RepositoryDoc.Builder
. يوضّح المثال التالي كيفية إنشاء عنصر واحد قابل للفهرسة.
السمة RepositoryDoc
هي نوع من ApiOperation
ينفّذ طلب
IndexingService.indexItem()
الفعلي.
يمكنك أيضًا استخدام طريقة
setRequestMode()
ضمن الفئة
RepositoryDoc.Builder
لتحديد طلب الفهرسة على أنّه ASYNCHRONOUS
أو SYNCHRONOUS
:
ASYNCHRONOUS
- يؤدي الوضع غير المتزامن إلى إطالة وقت استجابة الفهرسة للعرض لاستيعاب حصة سرعة معالجة كبيرة لطلبات الفهرسة. ويُنصح باستخدام الوضع غير المتزامن للفهرسة الأولية (إعادة التعبئة) للمستودع بأكمله.
SYNCHRONOUS
- ينتج عن الوضع المتزامن وقت استجابة أقصر عند الفهرسة والعرض
يستوعب حصة سرعة معالجة محدودة. يوصى باستخدام الوضع المتزامن
لفهرسة التحديثات والتغييرات في المستودع. في حال عدم تحديد هذا الحقل، يتم ضبط وضع الطلب تلقائيًا على
SYNCHRONOUS
.
إنشاء حزمة لكل عنصر قابل للفهرسة في مكرّر
تعرض الطريقة getAllDocs()
الكائنات Iterator
، خاصةً
CheckpointCloseableIterable
،
من الكائنات
RepositoryDoc
. يمكنك استخدام الفئة
CheckpointClosableIterableImpl.Builder
لإنشاء مكرّر وإرجاعه. يوضح مقتطف الرمز التالي كيفية إنشاء مُكرّر وإرجاعه.
تنفِّذ حزمة تطوير البرامج (SDK) كل استدعاء فهرسة مضمّن في المكرّر.
الخطوات التالية
في ما يلي بعض الخطوات التي يمكنك اتّخاذها:
- (اختياري) إذا كانت سرعة معالجة بيانات الفهرسة تبدو بطيئة، يمكنك الرجوع إلى المقالة زيادة معدّل الفهرسة على
FullTraversalConnector
. - (اختياري) نفِّذ طريقة
close()
لتحرير أي موارد قبل إيقاف التشغيل. - (اختياري) أنشئ موصِّل هوية باستخدام حزمة تطوير البرامج (SDK) لموصِّل المحتوى.
إنشاء موصل اجتياز قائمة باستخدام فئة نموذج
تُستخدم قائمة انتظار فهرسة Cloud Search للاحتفاظ بالأرقام التعريفية وقيم التجزئة الاختيارية لكل عنصر في المستودع. يرسل موصل اجتياز القائمة معرّفات العناصر إلى قائمة انتظار الفهرسة في Google Cloud Search ويستردها واحدًا تلو الآخر لإجراء الفهرسة. تحتفظ خدمة Google Cloud Search بقوائم الانتظار وتقارن محتوى قائمة الانتظار لتحديد حالة العنصر، مثل ما إذا تم حذف العنصر من المستودع. للحصول على مزيد من المعلومات حول قائمة انتظار فهرسة Cloud Search، يمكنك الرجوع إلى قائمة انتظار فهرسة Cloud Search.
يشير هذا القسم من المستندات إلى مقتطفات الرمز من مثال ListTraversalSample.
تنفيذ نقطة دخول الموصِّل
نقطة الدخول إلى الموصّل هي طريقة main()
. تتمثل المهمة الأساسية لهذه الطريقة في إنشاء مثيل من الفئة
Application
واستدعاء طريقة
start()
لتشغيل الموصل.
قبل طلب
application.start()
،
استخدِم الفئة
IndexingApplication.Builder
لإنشاء مثيل للنموذج
ListingConnector
. تقبل ListingConnector
عنصر
Repository
تنفذ طرقه. يوضّح المقتطف التالي طريقة بدء ListingConnector
وسمة Repository
المرتبطة بها:
وراء الكواليس، تستدعي حزمة تطوير البرامج (SDK) الطريقة
initConfig()
بعد استدعاءات طريقة main()
للموصل
Application.build
.
طريقة initConfig()
:
- لاستدعاء الطريقة
Configuation.isInitialized()
لضمان عدم إعدادConfiguration
. - لإعداد كائن
Configuration
باستخدام أزواج المفتاح/القيمة التي توفّرها Google يتم تخزين كل زوج مفتاح/قيمة في عنصرConfigValue
داخل كائنConfiguration
.
تنفيذ واجهة Repository
الغرض الوحيد من كائن Repository
هو اجتياز عناصر المستودع وفهرستها. عند استخدام نموذج، ما عليك سوى إلغاء طرق معيّنة
ضمن واجهة Repository
لإنشاء موصِّل محتوى.
تعتمد الطرق التي تلغيها على النموذج واستراتيجية الاجتياز التي تستخدمها. بالنسبة إلى ListingConnector
، يمكنك إلغاء الطرق التالية:
الطريقة
init()
. لإجراء أي عملية إعداد أو إعداد لمستودع البيانات، يجب إلغاء طريقةinit()
.الطريقة
getIds()
لاسترداد المعرّفات وقيم التجزئة لجميع السجلات في المستودع، يمكنك إلغاء طريقةgetIds()
.الطريقة
getDoc()
لإضافة عناصر جديدة أو تعديلها أو تعديلها أو حذفها من الفهرس، عليك إلغاء طريقةgetDoc()
.(اختياري) طريقة
getChanges()
. إذا كان مستودعك يتيح رصد التغييرات، يمكنك إلغاء طريقةgetChanges()
. يتم استدعاء هذه الطريقة مرة واحدة لكل عملية اجتياز متزايد مجدول (كما هو محدد في التهيئة) لاسترداد العناصر المعدلة وفهرستها.(اختياري) طريقة
close()
. وإذا كنت بحاجة إلى تنظيف المستودع، يمكنك إلغاء الطريقةclose()
. يتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف تشغيل الموصل.
تؤدي كل طريقة من طرق الكائن Repository
إلى عرض نوع من أنواع الكائنات
ApiOperation
. ينفِّذ الكائن ApiOperation
إجراءً في شكل طلب IndexingService.indexItem()
واحد أو عدة استدعاءات لتنفيذ الفهرسة الفعلية للمستودع.
الحصول على مَعلمات الإعدادات المخصّصة
كجزء من معالجة إعدادات الموصِّل، ستحتاج إلى الحصول على أي مَعلمات مخصّصة من الكائن Configuration
. يتم تنفيذ هذه المهمة عادةً بطريقة
Repository
الصف
init()
.
تتضمن الفئة Configuration
عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتعرض كل طريقة عنصر ConfigValue
. ستستخدم بعد ذلك طريقة
get()
للكائن ConfigValue
لاسترداد القيمة الفعلية.
يعرض المقتطف التالي، من FullTraversalSample
، كيفية استرداد قيمة عدد صحيح واحد مخصّص من كائن Configuration
:
للحصول على معلَمة تحتوي على قيم متعدّدة وتحليلها، استخدِم أحد برامج التحليل اللغوي للفئة Configuration
لتحليل البيانات إلى أجزاء منفصلة.
يستخدم المقتطف التالي من موصِّل البرنامج التعليمي طريقة
getMultiValue
للحصول على قائمة بأسماء مستودعات GitHub:
إجراء اجتياز القائمة
تجاوز طريقة
getIds()
لاسترداد أرقام التعريف وقيم التجزئة لجميع السجلات في المستودع.
تقبل الطريقة getIds()
نقطة مرجعية. تُستخدم نقطة التفتيش لاستئناف الفهرسة عند عنصر معين في حال مقاطعة العملية.
بعد ذلك، يمكنك إلغاء طريقة
getDoc()
للتعامل مع كل عنصر في قائمة انتظار الفهرسة في Cloud Search.
إرسال معرّفات العناصر وقيم التجزئة
إلغاء
getIds()
لجلب معرّفات السلع وقيم تجزئة المحتوى المرتبطة بها من
المستودع. يتم بعد ذلك تجميع أزواج رقم التعريف وقيم التجزئة في طلب عملية الدفع إلى قائمة انتظار فهرسة Cloud Search. عادةً ما يتم إرسال معرّفات الجذر أو المعرّفات الرئيسية أولاً متبوعةً بمعرّفات فرعية حتى تتم معالجة التسلسل الهرمي الكامل للعناصر.
تقبل الطريقة getIds()
نقطة مرجعية تمثل العنصر الأخير الذي ستتم فهرسته. يمكن استخدام النقطة المرجعية لاستئناف الفهرسة عند عنصر محدّد في حال مقاطعة العملية. لكل عنصر في مستودعك، نفِّذ هذه
الخطوات في طريقة getIds()
:
- الحصول على كل معرّف سلعة وقيمة تجزئة مرتبطة من المستودع
- اجمع كل زوج من المعرّف وقيمة التجزئة في
PushItems
. - ادمج كل
PushItems
في مُكرّر تعرض الطريقةgetIds()
. يُرجى العِلم أنّ السمةgetIds()
تعرض العنصرCheckpointCloseableIterable
وهو تكرار لكائناتApiOperation
، ويمثل كل عنصر طلب واجهة برمجة تطبيقات تم تنفيذه علىRepositoryDoc
، مثل إرسال العناصر إلى قائمة الانتظار.
يعرض مقتطف الرمز التالي كيفية الحصول على كل معرّف سلعة وقيمة تجزئة وإدخالها في PushItems
.
PushItems
هو طلب ApiOperation
لإرسال عنصر إلى قائمة انتظار الفهرسة في Cloud Search.
يوضِّح مقتطف الرمز التالي كيفية استخدام الفئة
PushItems.Builder
لتجميع أرقام التعريف وقيم التجزئة في دفعة واحدة
ApiOperation
.
يتم إرسال العناصر إلى قائمة انتظار الفهرسة في Cloud Search لإجراء المزيد من المعالجة.
استرداد كل عنصر والتعامل معه
تجاوز getDoc()
لمعالجة كل عنصر في قائمة انتظار الفهرسة في Cloud Search.
يمكن أن يكون العنصر جديدًا أو معدَّلاً أو غير متغير أو لا يمكن أن يكون متوفّرًا في المستودع
المصدر. استرداد وفهرسة كل عنصر جديد أو معدل. قم بإزالة العناصر
من الفهرس التي لم تعد موجودة في مستودع المصدر.
تقبل الطريقة getDoc()
عنصرًا من قائمة انتظار فهرسة Google Cloud Search. لكل عنصر في قائمة الانتظار، نفِّذ الخطوات التالية في طريقة
getDoc()
:
تحقَّق من توفُّر معرّف العنصر في قائمة انتظار الفهرسة في Cloud Search في المستودع. وإذا لم يكن كذلك، احذف العنصر من الفهرس.
استطلع رأي الفهرس بشأن حالة العنصر، وإذا لم يتغير العنصر (
ACCEPTED
)، لا تتّخذ أي إجراء.تم تغيير الفهرس أو عناصر جديدة:
- اضبط الأذونات.
- اضبط البيانات الوصفية للعنصر الذي تريد فهرسته.
- ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة
RepositoryDoc
. - عليك إرجاع جهاز "
RepositoryDoc
".
ملاحظة: لا يتيح النموذج ListingConnector
عرض null
بطريقة getDoc()
. عرض null
من النتائج في NullPointerException.
التعامل مع العناصر المحذوفة
يعرض مقتطف الرمز التالي كيفية تحديد ما إذا كان العنصر موجودًا في المستودع، وإذا لم يكن موجودًا، يمكنك حذفه.
لاحظ أن documents
هي بنية بيانات تمثل المستودع. إذا لم يتم العثور على documentID
في documents
، يمكنك عرض الرمز APIOperations.deleteItem(resourceName)
لحذف العنصر من الفهرس.
التعامل مع العناصر التي لم تتغيّر
يعرض مقتطف الرمز التالي كيفية استطلاع حالة العنصر في قائمة انتظار فهرسة Cloud Search والتعامل مع عنصر لم يتم تغييره.
لتحديد ما إذا كان العنصر غير معدّل، تحقَّق من حالة العنصر بالإضافة إلى البيانات الوصفية الأخرى التي قد تشير إلى حدوث تغيير. في المثال، يتم استخدام تجزئة بيانات التعريف لتحديد ما إذا كان العنصر قد تم تغييره.
ضبط الأذونات لعنصر واحد
يستخدم مستودعك قائمة التحكم بالوصول (ACL) لتحديد المستخدمين أو المجموعات التي يمكنها الوصول إلى عنصر. قائمة التحكم بالوصول هي قائمة بمعرفات المجموعات أو المستخدمين الذين يمكنهم الوصول إلى العنصر.
يجب عليك إنشاء نسخة طبق الأصل من قائمة التحكم بالوصول (ACL) المستخدمة في مستودعك لضمان أنّ المستخدمين الذين لديهم حق الوصول إلى العنصر هم وحدهم الذين يمكنهم الاطّلاع على هذا العنصر في نتيجة البحث. يجب تضمين قائمة التحكم بالوصول (ACL) للعنصر عند فهرسة عنصر بحيث يحصل Google Cloud Search على المعلومات اللازمة لتوفير مستوى الوصول الصحيح إلى العنصر.
توفر حزمة Content Connector SDK مجموعة غنية من فئات وأساليب قائمة التحكم بالوصول (ACL) لتصميم قوائم التحكم بالوصول لمعظم المستودعات. يجب تحليل قائمة التحكم بالوصول (ACL) لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول المقابلة لخدمة Google Cloud Search عند فهرسة أحد العناصر. إذا كانت قائمة التحكم بالوصول في المستودع تستخدم مفاهيم مثل اكتساب قائمة التحكم بالوصول، فقد يكون من الصعب إعداد نماذج قائمة التحكم بالوصول. للحصول على مزيد من المعلومات عن قوائم التحكم في الوصول في Google Cloud Search، يُرجى الرجوع إلى قوائم التحكم في الوصول في Google Cloud Search.
ملاحظة: تتيح واجهة برمجة التطبيقات للفهرسة في Cloud Search قوائم التحكم في الوصول (ACL) لنطاق واحد. ولا يدعم قوائم التحكم بالوصول عبر النطاقات. يمكنك استخدام فئة Acl.Builder
لضبط الوصول إلى كل عنصر باستخدام قائمة التحكم بالوصول. يُتيح مقتطف الرمز التالي، المأخوذ من عينة الاجتياز الكامل،
لجميع المستخدمين أو "المدراء"
(getCustomerPrincipal()
)
أن يكونوا "قراء" لجميع العناصر
(.setReaders()
)
عند إجراء بحث.
يجب عليك استيعاب قوائم التحكم بالوصول (ACLs) لتصميم قوائم التحكم بالوصول للمستودع بشكل صحيح. على سبيل المثال، قد تكون تفهرس ملفات داخل نظام ملفات يستخدم نوعًا من نموذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب إعداد البيانات الموروثة لقائمة التحكم بالوصول معلومات إضافية يتم تناولها في قوائم التحكم بالوصول في Google Cloud Search
ضبط البيانات الوصفية لعنصر
يتم تخزين البيانات الوصفية في عنصر Item
. لإنشاء Item
، يجب أن يكون لديك
حدّ أدنى من معرّف سلسلة فريد ونوع العنصر وقائمة التحكم في الوصول (ACL) وعنوان URL وإصدار العنصر.
يوضِّح مقتطف الرمز التالي كيفية إنشاء Item
باستخدام فئة المساعدة
IndexingItemBuilder
.
إنشاء عنصر قابل للفهرسة
بعد ضبط البيانات الوصفية للسلعة، يمكنك إنشاء العنصر الفعلي القابل للفهرسة باستخدام RepositoryDoc.Builder
.
يوضّح المثال التالي كيفية إنشاء عنصر واحد قابل للفهرسة.
إنّ السمة 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
المرتبطة بها:
وراء الكواليس، تستدعي حزمة تطوير البرامج (SDK) الطريقة
initConfig()
بعد استدعاءات طريقة main()
للموصل
Application.build
.
طريقة initConfig()
:
- لاستدعاء الطريقة
Configuation.isInitialized()
لضمان عدم إعدادConfiguration
. - لإعداد كائن
Configuration
باستخدام أزواج المفتاح/القيمة التي توفّرها Google يتم تخزين كل زوج مفتاح/قيمة في عنصرConfigValue
داخل كائنConfiguration
.
تنفيذ واجهة Repository
الغرض الوحيد من الكائن Repository
هو إجراء اجتياز عناصر المستودع وفهرستها. عند استخدام نموذج، ما عليك سوى إلغاء طرق معيّنة ضمن واجهة Repository
لإنشاء موصِّل محتوى. تعتمد الطرق التي تتجاهلها على
القالب واستراتيجية الاجتياز التي تستخدمها. بالنسبة إلى ListingConnector
، يمكنك إلغاء الطرق التالية:
الطريقة
init()
. لإجراء أي عملية إعداد أو إعداد لمستودع البيانات، يجب إلغاء طريقةinit()
.الطريقة
getIds()
لاسترداد المعرّفات وقيم التجزئة لجميع السجلات في المستودع، يمكنك إلغاء طريقةgetIds()
.الطريقة
getDoc()
لإضافة عناصر جديدة أو تعديلها أو تعديلها أو حذفها من الفهرس، عليك إلغاء طريقةgetDoc()
.(اختياري) طريقة
getChanges()
. إذا كان مستودعك يتيح رصد التغييرات، يمكنك إلغاء طريقةgetChanges()
. يتم استدعاء هذه الطريقة مرة واحدة لكل عملية اجتياز متزايد مجدول (كما هو محدد في التهيئة) لاسترداد العناصر المعدلة وفهرستها.(اختياري) طريقة
close()
. وإذا كنت بحاجة إلى تنظيف المستودع، يمكنك إلغاء الطريقةclose()
. يتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف تشغيل الموصل.
كل طريقة من طرق الكائن Repository
تعرض نوعًا من الكائنات ApiOperation
. ينفِّذ الكائن ApiOperation
إجراءً في شكل استدعاءات
IndexingService.indexItem()
واحدة أو ربما عدة استدعاءات لتنفيذ الفهرسة الفعلية لمستودعك.
الحصول على مَعلمات الإعدادات المخصّصة
كجزء من معالجة إعدادات الموصِّل، ستحتاج إلى الحصول على أي مَعلمات مخصّصة من الكائن Configuration
. يتم تنفيذ هذه المهمة عادةً بطريقة
Repository
الصف
init()
.
تتضمن الفئة Configuration
عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتعرض كل طريقة عنصر ConfigValue
. ستستخدم بعد ذلك طريقة
get()
للكائن ConfigValue
لاسترداد القيمة الفعلية.
يعرض المقتطف التالي، من FullTraversalSample
، كيفية استرداد قيمة عدد صحيح واحد مخصّص من كائن Configuration
:
للحصول على معلَمة تحتوي على قيم متعدّدة وتحليلها، استخدِم أحد برامج التحليل اللغوي للفئة Configuration
لتحليل البيانات إلى أجزاء منفصلة.
يستخدم المقتطف التالي من موصِّل البرنامج التعليمي طريقة
getMultiValue
للحصول على قائمة بأسماء مستودعات GitHub:
إجراء اجتياز الرسم البياني
تجاوز طريقة
getIds()
لاسترداد أرقام التعريف وقيم التجزئة لجميع السجلات في المستودع.
تقبل الطريقة getIds()
نقطة مرجعية. تُستخدم نقطة التفتيش لاستئناف الفهرسة عند عنصر معين في حال مقاطعة العملية.
بعد ذلك، يمكنك إلغاء طريقة
getDoc()
للتعامل مع كل عنصر في قائمة انتظار الفهرسة في Cloud Search.
إرسال معرّفات العناصر وقيم التجزئة
إلغاء
getIds()
لجلب معرّفات السلع وقيم تجزئة المحتوى المرتبطة بها من
المستودع. يتم بعد ذلك تجميع أزواج رقم التعريف وقيم التجزئة في طلب عملية الدفع إلى قائمة انتظار فهرسة Cloud Search. عادةً ما يتم إرسال معرّفات الجذر أو المعرّفات الرئيسية أولاً متبوعةً بمعرّفات فرعية حتى تتم معالجة التسلسل الهرمي الكامل للعناصر.
تقبل الطريقة getIds()
نقطة مرجعية تمثل العنصر الأخير الذي ستتم فهرسته. يمكن استخدام النقطة المرجعية لاستئناف الفهرسة عند عنصر محدّد في حال مقاطعة العملية. لكل عنصر في مستودعك، نفِّذ هذه
الخطوات في طريقة getIds()
:
- الحصول على كل معرّف سلعة وقيمة تجزئة مرتبطة من المستودع
- اجمع كل زوج من المعرّف وقيمة التجزئة في
PushItems
. - ادمج كل
PushItems
في مُكرّر تعرضه الطريقةgetIds()
. يُرجى العِلم أنّ السمةgetIds()
تعرض العنصرCheckpointCloseableIterable
وهو تكرار لكائناتApiOperation
، ويمثل كل عنصر طلب واجهة برمجة تطبيقات تم تنفيذه علىRepositoryDoc
، مثل إرسال العناصر إلى قائمة الانتظار.
يعرض مقتطف الرمز التالي كيفية الحصول على كل معرّف سلعة وقيمة تجزئة وإدخالها في PushItems
. PushItems
هو طلب ApiOperation
لإرسال عنصر إلى قائمة انتظار الفهرسة في Cloud Search.
يوضِّح مقتطف الرمز التالي كيفية استخدام الفئة
PushItems.Builder
لتجميع أرقام التعريف وقيم التجزئة في دفعة واحدة
ApiOperation
.
يتم إرسال العناصر إلى قائمة انتظار الفهرسة في Cloud Search لإجراء المزيد من المعالجة.
استرداد كل عنصر والتعامل معه
تجاوز getDoc()
لمعالجة كل عنصر في قائمة انتظار الفهرسة في Cloud Search.
يمكن أن يكون العنصر جديدًا أو معدَّلاً أو غير متغير أو لا يمكن أن يكون متوفّرًا في المستودع
المصدر. استرداد وفهرسة كل عنصر جديد أو معدل. قم بإزالة العناصر
من الفهرس التي لم تعد موجودة في مستودع المصدر.
تقبل الطريقة getDoc()
عنصرًا من قائمة انتظار الفهرسة في Cloud Search. لكل عنصر في قائمة الانتظار، نفِّذ الخطوات التالية في طريقة
getDoc()
:
تحقَّق من توفُّر معرّف العنصر في قائمة انتظار الفهرسة في Cloud Search في المستودع. وإذا لم يكن كذلك، احذف العنصر من الفهرس. إذا كان العنصر موجودًا، فتابع إلى الخطوة التالية.
تم تغيير الفهرس أو عناصر جديدة:
- اضبط الأذونات.
- اضبط البيانات الوصفية للعنصر الذي تريد فهرسته.
- ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة
RepositoryDoc
. - ضَع أرقام التعريف الفرعية في قائمة انتظار الفهرسة في Cloud Search لإجراء المزيد من المعالجة.
- عليك إرجاع جهاز "
RepositoryDoc
".
التعامل مع العناصر المحذوفة
يعرض مقتطف الرمز التالي كيفية تحديد ما إذا كان العنصر موجودًا في الفهرس أم لا، ويوضح كيفية حذفه.
ضبط الأذونات لعنصر واحد
يستخدم مستودعك قائمة التحكم بالوصول (ACL) لتحديد المستخدمين أو المجموعات التي يمكنها الوصول إلى عنصر. قائمة التحكم بالوصول هي قائمة بمعرفات المجموعات أو المستخدمين الذين يمكنهم الوصول إلى العنصر.
يجب عليك إنشاء نسخة طبق الأصل من قائمة التحكم بالوصول (ACL) المستخدمة في مستودعك لضمان أنّ المستخدمين الذين لديهم حق الوصول إلى العنصر هم وحدهم الذين يمكنهم الاطّلاع على هذا العنصر في نتيجة البحث. يجب تضمين قائمة التحكم بالوصول (ACL) للعنصر عند فهرسة عنصر بحيث يحصل Google Cloud Search على المعلومات اللازمة لتوفير مستوى الوصول الصحيح إلى العنصر.
توفر حزمة Content Connector SDK مجموعة غنية من فئات وأساليب قائمة التحكم بالوصول (ACL) لتصميم قوائم التحكم بالوصول لمعظم المستودعات. يجب تحليل قائمة التحكم بالوصول (ACL) لكل عنصر في المستودع وإنشاء قائمة التحكم بالوصول المقابلة لخدمة Google Cloud Search عند فهرسة أحد العناصر. إذا كانت قائمة التحكم بالوصول في المستودع تستخدم مفاهيم مثل اكتساب قائمة التحكم بالوصول، فقد يكون من الصعب إعداد نماذج قائمة التحكم بالوصول. للحصول على مزيد من المعلومات عن قوائم التحكم في الوصول في Google Cloud Search، يُرجى الرجوع إلى قوائم التحكم في الوصول في Google Cloud Search.
ملاحظة: تتيح واجهة برمجة التطبيقات للفهرسة في Cloud Search قوائم التحكم في الوصول (ACL) لنطاق واحد. ولا يدعم قوائم التحكم بالوصول عبر النطاقات. يمكنك استخدام فئة Acl.Builder
لضبط الوصول إلى كل عنصر باستخدام قائمة التحكم بالوصول. يُتيح مقتطف الرمز التالي، المأخوذ من عينة الاجتياز الكامل،
لجميع المستخدمين أو "المدراء"
(getCustomerPrincipal()
)
أن يكونوا "قراء" لجميع العناصر
(.setReaders()
)
عند إجراء بحث.
يجب عليك استيعاب قوائم التحكم بالوصول (ACLs) لتصميم قوائم التحكم بالوصول للمستودع بشكل صحيح. على سبيل المثال، قد تكون تفهرس ملفات داخل نظام ملفات يستخدم نوعًا من نموذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب إعداد البيانات الموروثة لقائمة التحكم بالوصول معلومات إضافية يتم تناولها في قوائم التحكم بالوصول في Google Cloud Search
ضبط البيانات الوصفية لعنصر
يتم تخزين البيانات الوصفية في عنصر Item
. لإنشاء Item
، يجب أن يكون لديك
حدّ أدنى من معرّف سلسلة فريد ونوع العنصر وقائمة التحكم في الوصول (ACL) وعنوان URL وإصدار العنصر.
يوضِّح مقتطف الرمز التالي كيفية إنشاء Item
باستخدام فئة المساعدة
IndexingItemBuilder
.
إنشاء عنصر قابل للفهرسة
بعد ضبط البيانات الوصفية للسلعة، يمكنك إنشاء العنصر الفعلي القابل للفهرسة باستخدام RepositoryDoc.Builder
.
يوضّح المثال التالي كيفية إنشاء عنصر واحد قابل للفهرسة.
السمة RepositoryDoc
هي نوع من ApiOperation
ينفّذ طلب
IndexingService.indexItem()
الفعلي.
يمكنك أيضًا استخدام طريقة
setRequestMode()
ضمن الفئة
RepositoryDoc.Builder
لتحديد طلب الفهرسة على أنّه ASYNCHRONOUS
أو SYNCHRONOUS
:
ASYNCHRONOUS
- يؤدي الوضع غير المتزامن إلى إطالة وقت استجابة الفهرسة للعرض لاستيعاب حصة سرعة معالجة كبيرة لطلبات الفهرسة. ويُنصح باستخدام الوضع غير المتزامن للفهرسة الأولية (إعادة التعبئة) للمستودع بأكمله.
SYNCHRONOUS
- ينتج عن الوضع المتزامن وقت استجابة أقصر عند الفهرسة والعرض
يستوعب حصة سرعة معالجة محدودة. يوصى باستخدام الوضع المتزامن
لفهرسة التحديثات والتغييرات في المستودع. في حال عدم تحديد هذا الحقل، يتم ضبط وضع الطلب تلقائيًا على
SYNCHRONOUS
.
وضع أرقام التعريف الفرعية في قائمة انتظار الفهرسة في Cloud Search
يعرض مقتطف الرمز التالي كيفية تضمين المعرّفات الفرعية، للعنصر الرئيسي الذي تتم معالجته حاليًا، في قائمة انتظار المعالجة. تتم معالجة هذه المعرّفات بعد فهرسة العنصر الرئيسي.
الخطوات التالية
في ما يلي بعض الخطوات التي يمكنك اتّخاذها:
- (اختياري) نفِّذ طريقة
close()
لتحرير أي موارد قبل إيقاف التشغيل. - (اختياري) أنشئ موصِّل هوية باستخدام حزمة تطوير البرامج لموصّل الهوية.
إنشاء موصِّل محتوى باستخدام REST API
تشرح الأقسام التالية طريقة إنشاء موصِّل محتوى باستخدام RST API.
تحديد استراتيجية الاجتياز
الوظيفة الأساسية لموصل المحتوى هي اجتياز مستودع وفهرسة بياناته. يجب عليك تنفيذ استراتيجية الاجتياز بناءً على حجم وتخطيط البيانات في مستودعك. فيما يلي ثلاث استراتيجيات اجتياز شائعة:
- استراتيجية الاجتياز الكاملة
تقوم استراتيجية الاجتياز الكاملة بفحص المستودع بأكمله وفهرسة كل عنصر بشكل عمياء. يشيع استخدام هذه الإستراتيجية عندما يكون لديك مستودع صغير وتتمكن من تحمل النفقات العامة لإجراء اجتياز كامل في كل مرة تقوم فيها بالفهرسة.
تناسب استراتيجية الاجتياز هذه المستودعات الصغيرة التي تحتوي في الغالب على بيانات ثابتة وغير هرمية. يمكنك أيضًا استخدام استراتيجية الاجتياز هذه عندما يكون اكتشاف التغيير صعبًا أو غير مدعوم من قبل المستودع.
- إدراج استراتيجية الاجتياز
تفحص استراتيجية اجتياز القائمة المستودع بأكمله، بما في ذلك جميع العُقد الفرعية، لتحديد حالة كل عنصر. وبعد ذلك، يحصل الموصّل على تمريرة ثانية ولا يفهرس سوى العناصر الجديدة أو التي تم تحديثها منذ آخر عملية فهرسة. تُستخدم هذه الإستراتيجية بشكل شائع لإجراء تحديثات تدريجية على فهرس موجود (بدلاً من الاضطرار إلى إجراء مسح كامل في كل مرة تقوم فيها بتحديث الفهرس).
تكون استراتيجية الاجتياز هذه مناسبة عندما يكون اكتشاف التغيير صعبًا أو غير مدعوم من قبل المستودع، وإذا كان لديك بيانات غير هرمية، وتعمل على مجموعات بيانات كبيرة جدًا.
- اجتياز الرسم البياني
تفحص استراتيجية اجتياز الرسم البياني العقدة الرئيسية بالكامل لتحديد حالة كل عنصر. وبعد ذلك، يحصل الموصل على تمريرة ثانية ولا يفهرس سوى العناصر في العقدة الجذرية وهي العناصر الجديدة أو تلك التي تم تحديثها منذ آخر عملية فهرسة. أخيرًا، يمرر الموصل أي معرّفات فرعية ثم يفهرس العناصر الجديدة أو التي تم تحديثها في العُقد الفرعية. يستمر الموصل بشكل متكرر خلال جميع العُقد الفرعية حتى تتم معالجة جميع العناصر. يُستخدم هذا الاجتياز عادةً للمستودعات الهرمية حيث لا يكون إدراج جميع المعرفات عملية.
هذه الاستراتيجية مناسبة إذا كانت لديك بيانات هرمية يجب الزحف إليها، مثل أدلة السلسلة أو صفحات الويب.
تنفيذ استراتيجية الاجتياز وفهرسة العناصر
تتم الإشارة إلى كل عنصر قابل للفهرسة في Cloud Search على أنه عنصر في Cloud Search API. قد يكون العنصر ملفًا أو مجلدًا أو سطرًا في ملف CSV أو سجل قاعدة بيانات.
بمجرد تسجيل المخطط، يمكنك تعبئة الفهرس عن طريق:
(اختياري) استخدام
items.upload
لتحميل ملفات يزيد حجمها عن 100 كيلوبايت للفهرسة. بالنسبة إلى الملفات الأصغر، يمكنك تضمين المحتوى بتنسيق inlineContent باستخدامitems.index
.(اختياري) استخدام
media.upload
لتحميل ملفات الوسائط للفهرسة.استخدام
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" }
ولإجراء مسح كامل، عليك إعادة فهرسة المستودع بالكامل بشكل دوري. لإجراء اجتياز قائمة أو رسم بياني، تحتاج إلى تنفيذ رمز للتعامل مع تغييرات المستودع.
التعامل مع تغييرات المستودع
يمكنك جمع كل عنصر وفهرسته بشكل دوري من المستودع لإجراء فهرسة كاملة. وعلى الرغم من فعاليتها في ضمان تحديث فهرسك، قد تكون الفهرسة الكاملة مكلفة عند التعامل مع مستودعات أكبر أو هرمية.
بدلاً من استخدام استدعاءات الفهرس لفهرسة مستودع بالكامل من حين لآخر، يمكنك أيضًا استخدام قائمة انتظار الفهرسة في Google Cloud كآلية لتتبُّع التغييرات وفهرسة العناصر التي تغيّرت فقط. يمكنك استخدام طلبات items.push لإرسال العناصر إلى قائمة الانتظار من أجل إجراء الاستطلاعات والتحديث لاحقًا. لمزيد من المعلومات حول قائمة انتظار فهرسة Google Cloud، يمكنك الرجوع إلى قائمة انتظار فهرسة Google Cloud.
لمزيد من المعلومات عن Google Cloud Search API، يمكنك الرجوع إلى واجهة برمجة تطبيقات Cloud Search.