موصِّل المحتوى هو برنامج يُستخدَم لاجتياز البيانات في مستودع مؤسسة وتعبئة مصدر بيانات. تقدم Google الخيارات التالية لتطوير موصلات المحتوى:
حزمة SDK لموصل المحتوى. وهذا خيار جيد إذا كنت تبرمج لغة جافا. حزمة SDK لموصل المحتوى هي برنامج مضمن حول واجهة برمجة تطبيقات REST مما يتيح لك إنشاء موصلات بسرعة. لإنشاء موصل محتوى باستخدام حزمة SDK، يمكنك الرجوع إلى إنشاء موصل محتوى باستخدام حزمة SDK لموصل المحتوى.
واجهة برمجة تطبيقات REST منخفضة المستوى أو مكتبات واجهة برمجة التطبيقات. استخدم هذه الخيارات إذا كنت لا برمجة في جافا، أو إذا كانت قاعدة شفرتك تستوعب بشكل أفضل واجهة برمجة تطبيقات REST أو مكتبة. لإنشاء موصِّل محتوى باستخدام واجهة برمجة تطبيقات REST، يُرجى الرجوع إلى إنشاء موصِّل محتوى باستخدام واجهة برمجة تطبيقات REST.
ينفِّذ موصِّل المحتوى النموذجي المهام التالية:
- قراءة معلمات التهيئة ومعالجتها.
- يسحب أجزاء منفصلة من البيانات القابلة للفهرسة، تسمى "items"، من مستودع المحتوى التابع لجهة خارجية.
- يدمج قوائم ACL والبيانات الوصفية وبيانات المحتوى في عناصر قابلة للفهرسة.
- لفهرسة العناصر إلى مصدر بيانات 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
. وستستخدم عندئذٍ طريقة الكائن ConfigValue
في get()
لاسترداد القيمة الفعلية.
يعرض المقتطف التالي، من
FullTraversalSample
،
كيفية استرداد قيمة عدد صحيح مخصّصة واحدة من كائن Configuration
:
للحصول على معلمة تحتوي على قيم متعددة وتحليلها، استخدِم أحد المحللين من النوع "Configuration
" للفئة لتحليل البيانات في أجزاء منفصلة.
يستخدم المقتطف التالي، من موصِّل البرامج التعليمية، طريقة
getMultiValue
للحصول على قائمة بأسماء مستودعات GitHub:
إجراء الاجتياز بشكل كامل
يمكنك إلغاء
getAllDocs()
لإجراء عملية المسح الكامل وفهرسة المستودع. تقبل طريقة getAllDocs()
نقطة تفتيش. يتم استخدام النقطة المرجعية لاستئناف الفهرسة على عنصر معيّن في حال مقاطعة العملية. بالنسبة إلى كل سلعة في مستودعك،
نفِّذ الخطوات التالية في طريقة getAllDocs()
:
- تعيين الأذونات.
- عيّن البيانات الوصفية للعنصر الذي تريد فهرسته.
- ادمج البيانات الوصفية والعنصر في عنصر واحد قابل للفهرسة
RepositoryDoc
. - يمكنك تجميع كل عنصر قابل للفهرسة في مكرّر يتم عرضه باستخدام طريقة
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()
)
عند إجراء بحث.
يجب استيعاب قوائم التحكم في الوصول (ACL) لتشكيل قوائم التحكم في الوصول (ACL) بشكل صحيح للمستودع. على سبيل المثال، يمكنك فهرسة الملفات داخل نظام الملفات الذي يستخدم أحد نماذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب توريث قائمة التحكم بالوصول (ACL) إنشاء معلومات إضافية تم تناولها في قوائم التحكم في الوصول (ACL) في 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
. وستستخدم عندئذٍ طريقة الكائن ConfigValue
في get()
لاسترداد القيمة الفعلية.
يعرض المقتطف التالي، من
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) المستخدمة في مستودعك لضمان عدم رؤية سوى هذا العنصر للمستخدمين الذين لهم حق الوصول إلى عنصر داخل نتيجة بحث. يجب تضمين قائمة التحكم بالوصول (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()
)
عند إجراء بحث.
يجب استيعاب قوائم التحكم في الوصول (ACL) لتشكيل قوائم التحكم في الوصول (ACL) بشكل صحيح للمستودع. على سبيل المثال، يمكنك فهرسة الملفات داخل نظام الملفات الذي يستخدم أحد نماذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب توريث قائمة التحكم بالوصول (ACL) إنشاء معلومات إضافية تم تناولها في قوائم التحكم في الوصول (ACL) في 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
. وستستخدم عندئذٍ طريقة الكائن ConfigValue
في get()
لاسترداد القيمة الفعلية.
يعرض المقتطف التالي، من
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) المستخدمة في مستودعك لضمان عدم رؤية سوى هذا العنصر للمستخدمين الذين لهم حق الوصول إلى عنصر داخل نتيجة بحث. يجب تضمين قائمة التحكم بالوصول (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()
)
عند إجراء بحث.
يجب استيعاب قوائم التحكم في الوصول (ACL) لتشكيل قوائم التحكم في الوصول (ACL) بشكل صحيح للمستودع. على سبيل المثال، يمكنك فهرسة الملفات داخل نظام الملفات الذي يستخدم أحد نماذج الوراثة حيث تكتسب المجلدات الفرعية الأذونات من المجلدات الرئيسية. يتطلب توريث قائمة التحكم بالوصول (ACL) إنشاء معلومات إضافية تم تناولها في قوائم التحكم في الوصول (ACL) في 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()
لإطلاق أي موارد قبل إيقاف التشغيل. - (اختياري) أنشئ موصِّل هويات باستخدام SDK لموصِّل الهوية.
إنشاء موصِّل محتوى باستخدام واجهة برمجة تطبيقات REST
توضح الأقسام التالية كيفية إنشاء موصل محتوى باستخدام واجهة برمجة تطبيقات REST.
تحديد استراتيجية الاجتياز
الوظيفة الأساسية لموصِّل المحتوى هي اجتياز المستودع وفهرسة بياناته. يجب تنفيذ إستراتيجية المسح استنادًا إلى حجم وتنسيق البيانات في المستودع. في ما يلي ثلاث استراتيجيات اجتياز شائعة:
- استراتيجية الاجتياز الكاملة
تعمل إستراتيجية الاجتياز الكاملة على فحص المستودع بأكمله وفهرسة كل عنصر بشكلٍ عشوائي. وتُستخدم هذه الإستراتيجية بشكل عام عندما يكون لديك مستودع صغير وتستطيع تحمّل تكاليف إجراء الاجتياز الكامل في كل مرة تفهرس فيها.
وتتناسب إستراتيجية المسح هذه مع المستودعات الصغيرة التي تحتوي غالبًا على بيانات ثابتة وغير هرمية. يمكنك أيضًا استخدام إستراتيجية المسح هذه عندما يكون اكتشاف التغيير صعبًا أو غير متاح في المستودع.
- استراتيجية المسح في قائمة
تفحص إستراتيجية مسح القوائم المستودع بالكامل، بما في ذلك جميع العُقد الفرعية، لتحديد حالة كل عنصر. بعد ذلك، يأخذ الموصّل تمريرة ثانية ولا يفهرس سوى العناصر الجديدة أو التي تم تحديثها منذ آخر فهرسة. وتستخدم هذه الإستراتيجية بشكل شائع لإجراء تحديثات إضافية على فهرس حالي (بدلاً من الاضطرار إلى إجراء مسح كامل في كل مرة تقوم فيها بتحديث الفهرس).
تكون إستراتيجية الاجتياز هذه مناسبة عندما يكون اكتشاف التغيير صعبًا أو غير متاح في المستودع، وإذا كانت لديك بيانات غير هرمية، وكنت تعمل مع مجموعات بيانات كبيرة جدًا.
- اجتياز الرسم البياني
تفحص إستراتيجية الرسم البياني لمسح العقد الرئيسي بأكمله حالة كل عنصر. بعد ذلك، يأخذ الموصِّل تمريرة ثانية ولا يفهرس سوى العناصر في العقدة الجذر الجديدة أو التي تم تحديثها منذ آخر فهرسة. وأخيرًا، يمرِّر الموصِّل أي أرقام تعريف فرعية ثم يفهرس العناصر في العُقد الفرعية الجديدة أو التي تم تحديثها. ويستمر الموصل بشكل متكرر عبر جميع العقد الفرعية حتى تتم معالجة جميع العناصر. وعادةً ما يتم استخدام هذا الاجتياز في المستودعات الهرمية حيث يكون إدراج جميع أرقام التعريف غير عملي.
تكون هذه الإستراتيجية مناسبة إذا كانت لديك بيانات هرمية تحتاج إلى الزحف إليها، مثل أدلة السلسلة أو صفحات الويب.
تنفيذ استراتيجية المسح وفهرسة العناصر
تتم الإشارة إلى كل عنصر قابل للفهرسة في Cloud Search على أنه عنصر في واجهة برمجة تطبيقات Cloud Search. قد يكون العنصر ملفًا أو مجلدًا أو سطرًا في ملف 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" }
(اختياري) تمت فهرسة استخدام items.get للتحقّق من أنّ السلعة تمت فهرستها.
لإجراء المسح الكامل، يجب إعادة فهرسة المستودع بالكامل بشكل دوري. لإجراء عملية مسح قائمة أو رسم بياني، يجب تنفيذ الشفرة من أجل التعامل مع تغييرات المستودع.
التعامل مع تغييرات المستودع
يمكنك تجميع كل عنصر وفهرسته من المستودع لإجراء فهرسة كاملة. على الرغم من فعالية عملية التأكد من حداثة الفهرس، قد تكون الفهرسة الكاملة مكلفة عند التعامل مع المستودعات الكبيرة أو الهرمية.
بدلاً من استخدام استدعاءات الفهرس لفهرسة مستودع كامل بشكل متكرر، يمكنك أيضًا استخدام قائمة انتظار الفهرسة في Google Cloud كآلية لتتبع التغييرات وفهرسة العناصر التي تم تغييرها فقط. يمكنك استخدام طلبات items.push لإدراج العناصر في قائمة الانتظار لإجراء استطلاع رأي وتحديث لاحق. لمزيد من المعلومات حول "قائمة انتظار الفهرسة في Google Cloud"، يُرجى الرجوع إلى قائمة انتظار الفهرسة في Google Cloud.
لمزيد من المعلومات عن واجهة برمجة تطبيقات Google Cloud Search، يُرجى الرجوع إلى واجهة برمجة تطبيقات Cloud Search.