قوائم انتظار فهرسة Google Cloud Search

تتيح حزمة تطوير البرامج (SDK) الخاصة بالموصِّل وGoogle Cloud Search API إنشاء قوائم انتظار الفهرسة في Cloud Search التي تُستخدم لتنفيذ المهام التالية:

• الحفاظ على حالة كل مستند (الحالة وقيم التجزئة وما إلى ذلك) التي يمكن استخدامها للحفاظ على مزامنة الفهرس مع المستودع

• الاحتفاظ بقائمة بالعناصر التي سيتم فهرسة محتواها أثناء عملية الزحف

• تحديد أولويات العناصر في قوائم الانتظار استنادًا إلى حالة العنصر

• الاحتفاظ بمعلومات حالة إضافية لتحقيق تكامل فعّال، مثل نقاط التحقّق ورمز التغيير وما إلى ذلك

قائمة الانتظار هي تصنيف يتم تعيينه لعنصر مفهرس، مثل "تلقائي" لقائمة الانتظار التلقائية أو "ب" لقائمة الانتظار ب.

الحالة والأولوية

تستند أولوية المستند في قائمة الانتظار إلى ItemStatus الخاص به. في ما يلي رموز ItemStatus المحتملة بترتيب الأولوية (يتم التعامل معها من الأولوية الأولى إلى الأولوية الأخيرة):

• ERROR - حدث خطأ غير متزامن أثناء عملية الفهرسة ويجب إعادة فهرسة العنصر.

• ‫MODIFIED: عنصر تمت فهرسته سابقًا وتم تعديله منذ ذلك الحين في المستودع منذ آخر عملية فهرسة.

• ‫NEW_ITEM: عنصر غير مفهرس

• ACCEPTED: مستند تمت فهرسته سابقًا ولم يتغير في المستودع منذ آخر عملية فهرسة.

عندما يكون لعنصرَين في قائمة الانتظار الحالة نفسها، تُمنح الأولوية للعناصر التي بقيت في قائمة الانتظار لأطول فترة زمنية.

نظرة عامة على استخدام قوائم انتظار الفهرسة لفهرسة عنصر جديد أو معدَّل

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

الشكل 1. خطوات الفهرسة لإضافة عنصر أو تعديله

1. يستخدم موصّل المحتوى items.push لنقل العناصر (البيانات الوصفية والتجزئة) إلى قائمة انتظار الفهرسة من أجل تحديد حالة العنصر (MODIFIED وNEW_ITEM وDELETED). إليك التفاصيل:

   • عند إرسال البيانات، يتضمّن الموصل بشكل صريح عملية إرسال type أو contentHash.
   • إذا لم يتضمّن الموصّل السمة type، ستستخدم خدمة Cloud Search تلقائيًا السمة contentHash لتحديد حالة العنصر.
   • إذا كان العنصر غير معروف، يتم ضبط حالة العنصر على NEW_ITEM.
   • إذا كان العنصر متوفّرًا وتتطابق قيم التجزئة، تظل الحالة ACCEPTED.
   • إذا كان العنصر متوفّرًا وكانت رموز التجزئة مختلفة، ستتغيّر الحالة إلى MODIFIED.

   لمزيد من المعلومات حول كيفية تحديد حالة العنصر، راجِع نموذج الرمز Traversing the GitHub repositories في البرنامج التعليمي حول كيفية بدء استخدام Cloud Search.

   عادةً ما يكون الإرسال مرتبطًا بعمليات التنقّل في المحتوى و/أو رصد التغييرات في الموصل.

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

3. يستردّ الموصل هذه العناصر من المستودع وينشئ طلبات واجهة برمجة التطبيقات الخاصة بالفهرس.

4. يستخدم الموصّل items.index لفهرسة العناصر. لا تنتقل الحالة إلى ACCEPTED إلا بعد أن تنتهي Cloud Search من معالجة العنصر بنجاح.

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

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

نظرة عامة على استخدام قوائم انتظار الفهرسة لحذف عنصر

تستخدم استراتيجية التنقّل الكامل عملية تتضمّن قائمتَي انتظار لفهرسة العناصر ورصد عمليات الحذف. تعرض الصورة 2 خطوات حذف عنصر باستخدام قائمتَي انتظار للفهرسة. على وجه التحديد، يعرض الشكل 2 عملية الاجتياز الثانية التي تم تنفيذها باستخدام استراتيجية الاجتياز الكامل. تستخدِم هذه الخطوات طلبات REST API. للحصول على معلومات حول طلبات حزمة تطوير البرامج (SDK) المكافئة، يُرجى الرجوع إلى عمليات قائمة الانتظار (حزمة تطوير البرامج (SDK) الخاصة بأداة الربط).

الشكل 2. حذف العناصر

ملاحظة: في قائمة الخطوات التالية، لا تظهر الخطوات من 1 إلى 4 في الشكل 2 لأنّها مماثلة للخطوات من 1 إلى 4 في الشكل البياني السابق، وهي خارج نطاق هذا القسم. لا تظهر الخطوة 5 لأنّ استدعاء deleteQueueItems في قائمة انتظار فارغة لا يندرج ضمن نطاق هذا القسم. يركّز هذا الرسم البياني على عملية الزحف الثانية.

1. عند إجراء عملية الزحف الأولية، يستخدم موصّل المحتوى items.push لدفع العناصر (البيانات الوصفية والتجزئة) إلى قائمة انتظار الفهرسة، "قائمة الانتظار أ"، باعتبارها NEW_ITEM لأنّها غير متوفّرة في قائمة الانتظار. يتم تخصيص التصنيف "أ" لكل عنصر في "قائمة الانتظار أ". يتم فهرسة المحتوى في Cloud Search.

   ملاحظة: يمكن للموصل تعيين تصنيف قائمة انتظار باستخدام الحقل queue الخاص بالعنصر، إلى عنصر أثناء عملية item.push أو item.index. يمكن تعديل هذا التصنيف كلما تمت إعادة نشر العنصر أو إعادة فهرسته.

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

3. يستردّ الموصل هذه العناصر من المستودع وينشئ طلبات واجهة برمجة التطبيقات الخاصة بالفهرس.

4. يستخدم الموصّل items.index لفهرسة العناصر. لا تنتقل الحالة إلى ACCEPTED إلا بعد أن تنتهي Cloud Search من معالجة العنصر بنجاح.

5. يتم استدعاء الطريقة deleteQueueItems في "قائمة الانتظار B". ولكن لم تتم إضافة أي عناصر إلى قائمة الانتظار B، وبالتالي لا يمكن حذف أي عناصر.

6. في عملية الاجتياز الكاملة الثانية، يستخدم موصّل المحتوى items.push لنقل العناصر (البيانات الوصفية والتجزئة) إلى قائمة الانتظار B:

   • عند إرسال البيانات، يتضمّن الموصل بشكل صريح عملية إرسال type أو contentHash.
   • إذا لم يتضمّن الموصّل السمة type، ستستخدم خدمة Cloud Search تلقائيًا السمة contentHash لتحديد حالة العنصر.
   • إذا كان العنصر غير معروف، يتم ضبط حالة العنصر على NEW_ITEM وتغيير تصنيف قائمة الانتظار إلى "ب".
   • إذا كان العنصر متوفّرًا وتتطابق قيم التجزئة، تبقى الحالة ACCEPTED ويتم تغيير تصنيف قائمة الانتظار إلى "B".
   • إذا كان العنصر متوفّرًا وكانت رموز التجزئة مختلفة، ستتغيّر الحالة إلى MODIFIED وسيتم تغيير تصنيف قائمة الانتظار إلى "B".

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

8. يستردّ الموصل هذه العناصر من المستودع وينشئ طلبات واجهة برمجة التطبيقات الخاصة بالفهرس.

9. يستخدم الموصّل items.index لفهرسة العناصر. لا تنتقل الحالة إلى ACCEPTED إلا بعد أن تنتهي Cloud Search من معالجة العنصر بنجاح.

10. أخيرًا، يتم استدعاء deleteQueueItems في قائمة الانتظار A لحذف جميع عناصر CCloud Search التي تمت فهرستها سابقًا والتي لا يزال لديها تصنيف قائمة انتظار "A".

11. في عمليات الاجتياز الكاملة اللاحقة، يتم تبديل قائمة الانتظار المستخدَمة للفهرسة بقائمة الانتظار المستخدَمة للحذف.

عمليات قائمة الانتظار (حزمة تطوير البرامج (SDK) الخاصة بأداة الربط)

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

لتجميع عنصر وإرساله إلى قائمة انتظار، استخدِم فئة pushItems builder.

ليس عليك اتّخاذ أي إجراءات محدّدة لسحب عناصر من قائمة انتظار بغرض معالجتها. بدلاً من ذلك، تسحب حزمة SDK العناصر تلقائيًا من قائمة الانتظار حسب الأولوية باستخدام طريقة getDoc في فئة Repository.

عمليات قائمة الانتظار (REST API)

توفّر واجهة REST API الطريقتَين التاليتَين لإرسال العناصر إلى قائمة الانتظار واستردادها منها:

• لدفع عنصر إلى قائمة انتظار، استخدِم Items.push.
• لاستطلاع العناصر في قائمة الانتظار، استخدِم Items.poll.

يمكنك أيضًا استخدام Items.index لإضافة عناصر إلى قائمة الانتظار أثناء الفهرسة. لا تتطلّب العناصر التي يتم إرسالها إلى قائمة الانتظار أثناء الفهرسة type ويتم تلقائيًا تعيين الحالة ACCEPTED لها.

Items.push

تضيف طريقة Items.push المعرّفات إلى قائمة الانتظار. يمكن استدعاء هذه الطريقة باستخدام قيمة type محدّدة تحدّد نتيجة عملية الإرسال. للاطّلاع على قائمة بقيم type، راجِع حقل item.type في طريقة Items.push.

يؤدي إرسال معرّف جديد إلى إضافة إدخال جديد يتضمّن الرمز NEW_ITEM ItemStatus.

يتم دائمًا تخزين الحمولة الاختيارية والتعامل معها كقيمة مبهمة، كما يتم عرضها من خلال Items.poll.

عندما يتم استطلاع عنصر، يتم حجزه، ما يعني أنّه لا يمكن إرجاعه من خلال طلب آخر إلى Items.poll. باستخدام Items.push مع type كـ NOT_MODIFIED أو REPOSITORY_ERROR أو REQUEUE، يتم إلغاء حجز الإدخالات التي تم استطلاعها. لمزيد من المعلومات حول الإدخالات المحجوزة وغير المحجوزة، يُرجى الرجوع إلى قسم Items.poll.

Items.push مع قيم التجزئة

تتيح واجهة برمجة التطبيقات Google Cloud Search API تحديد قيم البيانات الوصفية وتجزئة المحتوى في طلبات Items.index. بدلاً من تحديد type، يمكن تحديد قيم البيانات الوصفية و/أو تجزئة المحتوى باستخدام طلب إرسال. يقارن "قائمة انتظار الفهرسة في Cloud Search" قيم التجزئة المقدَّمة بالقيم المخزَّنة المتوفّرة مع العنصر في مصدر البيانات. في حال عدم التطابق، يتم وضع علامة MODIFIED على هذا الإدخال. إذا لم يكن هناك عنصر مطابق في الفهرس، ستكون الحالة NEW_ITEM.

ملاحظة: لا يتم حفظ قيم التجزئة المقدَّمة مع طلبات Items.push مع السلعة. يتم استخدام هذه العناصر فقط لتحديد ما إذا تم تعديل العنصر.

Items.poll

يستردّ الأسلوب Items.poll الإدخالات ذات الأولوية القصوى من قائمة الانتظار. تشير قيم الحالة المطلوبة والمرتجعة إلى حالات قوائم الانتظار ذات الأولوية المطلوبة أو حالة المعرّفات المرتجعة.

بشكلٍ تلقائي، يمكن إرجاع الإدخالات من أي قسم في قائمة الانتظار، وذلك استنادًا إلى الأولوية. يكون كل إدخال تم عرضه محجوزًا، ولا يتم عرضه من خلال طلبات أخرى إلى Items.poll إلى أن يتم استيفاء إحدى الحالات التالية:

• تنتهي مهلة الحجز.
• يتم إعادة وضع الإدخال في قائمة الانتظار من خلال Items.index.
• يتم استدعاء Items.push بقيمة type تساوي NOT_MODIFIED أو REPOSITORY_ERROR أو REQUEUE.