صف های نمایه سازی Google Cloud Search

رابط توسعه نرم‌افزار (SDK) و رابط برنامه‌نویسی کاربردی جستجوی ابری گوگل (Google Cloud Search API) امکان ایجاد صف‌های نمایه‌سازی جستجوی ابری (Cloud Search Indexing Queues) را فراهم می‌کنند که برای انجام وظایف زیر استفاده می‌شوند:

• وضعیت هر سند (وضعیت، مقادیر هش و غیره) را حفظ کنید که می‌تواند برای همگام‌سازی شاخص شما با مخزن شما استفاده شود.

• فهرستی از مواردی که باید در طول فرآیند پیمایش، نمایه‌سازی شوند را نگهداری کنید.

• اقلام موجود در صف‌ها را بر اساس وضعیت آنها اولویت‌بندی کنید.

• اطلاعات وضعیت اضافی مانند نقاط بازرسی، توکن تغییر و غیره را برای یکپارچه‌سازی کارآمد حفظ کنید.

صف، برچسبی است که به یک آیتم اندیس‌گذاری شده اختصاص داده می‌شود، مانند "پیش‌فرض" برای صف پیش‌فرض یا "B" برای صف B.

وضعیت و اولویت

اولویت یک سند در صف بر اساس کد ItemStatus آن است. در زیر کدهای ItemStatus ممکن به ترتیب اولویت (از اولین مورد رسیدگی شده تا آخرین مورد رسیدگی شده) آمده است:

• ERROR - مورد در طول فرآیند فهرست‌بندی با خطای ناهمزمان مواجه شده و نیاز به فهرست‌بندی مجدد دارد.

• MODIFIED - موردی که قبلاً ایندکس شده و از آخرین ایندکس‌گذاری در مخزن اصلاح شده است.

• NEW_ITEM - آیتمی که ایندکس نشده است.

• ACCEPTED - سندی که قبلاً نمایه‌سازی شده و از آخرین نمایه‌سازی در مخزن تغییر نکرده است.

وقتی دو آیتم در یک صف وضعیت یکسانی دارند، اولویت بالاتر به آیتم‌هایی داده می‌شود که مدت زمان بیشتری در صف بوده‌اند.

مروری بر استفاده از صف‌های اندیس‌گذاری برای اندیس‌گذاری یک آیتم جدید یا تغییر یافته

شکل ۱ مراحل اندیس‌گذاری یک آیتم جدید یا تغییر یافته با استفاده از صف اندیس‌گذاری را نشان می‌دهد. این مراحل فراخوانی‌های REST API را نشان می‌دهند. برای فراخوانی‌های معادل SDK، به عملیات صف (Connector SDK) مراجعه کنید.

شکل ۱. مراحل ایندکس‌گذاری برای افزودن یا به‌روزرسانی یک آیتم

1. رابط محتوا از items.push برای قرار دادن آیتم‌ها (فراداده و هش) در یک صف نمایه‌سازی استفاده می‌کند تا وضعیت آیتم ( MODIFIED ، NEW_ITEM ، DELETED ) را تعیین کند. به طور خاص:

   • هنگام ارسال، کانکتور به صراحت type ارسال یا contentHash را در نظر می‌گیرد.
   • اگر کانکتور شامل type نباشد، جستجوی ابری به‌طور خودکار از contentHash برای تعیین وضعیت آیتم استفاده می‌کند.
   • اگر کالا ناشناخته باشد، وضعیت کالا روی NEW_ITEM تنظیم می‌شود.
   • اگر مورد وجود داشته باشد و مقادیر هش مطابقت داشته باشند، وضعیت به صورت ACCEPTED حفظ می‌شود.
   • اگر آیتم وجود داشته باشد و هش‌ها متفاوت باشند، وضعیت به MODIFIED تغییر می‌کند.

   برای اطلاعات بیشتر در مورد نحوه تعیین وضعیت آیتم، به نمونه کد Traversing the GitHub repositories در آموزش شروع جستجوی ابری مراجعه کنید.

   معمولاً، فشار با پیمایش محتوا و/یا فرآیندهای تشخیص تغییر در کانکتور مرتبط است.

2. رابط محتوا از items.poll برای نظرسنجی از صف و تعیین مواردی که باید فهرست شوند استفاده می‌کند. جستجوی ابری به رابط می‌گوید کدام موارد بیشترین نیاز به فهرست‌بندی را دارند، که ابتدا بر اساس کد وضعیت و سپس بر اساس زمان حضور در صف مرتب شده‌اند.

3. کانکتور این موارد را از مخزن بازیابی می‌کند و درخواست‌های API شاخص را می‌سازد.

4. کانکتور از items.index برای فهرست‌بندی اقلام استفاده می‌کند. اقلام فقط پس از اینکه Cloud Search با موفقیت پردازش آنها را به پایان رساند، وارد حالت ACCEPTED می‌شوند.

یک رابط همچنین می‌تواند در صورتی که یک آیتم دیگر در مخزن وجود نداشته باشد، آن را حذف کند، یا در صورتی که آیتمی تغییر نکرده باشد یا خطایی در مخزن منبع وجود داشته باشد، آن را دوباره ارسال کند. برای اطلاعات بیشتر در مورد حذف آیتم‌ها، به بخش بعدی مراجعه کنید.

نکته: برخی از استراتژی‌های پیمایش، مانند پیمایش کامل، از بیش از یک صف اندیس‌گذاری استفاده می‌کنند. برای مثالی از نحوه استفاده از دو صف، به بخش بعدی مراجعه کنید.

مروری بر استفاده از صف‌های اندیس‌گذاری برای حذف یک آیتم

استراتژی پیمایش کامل از یک فرآیند دو صفی برای فهرست‌بندی اقلام و تشخیص حذف‌ها استفاده می‌کند. شکل 2 مراحل حذف یک مورد را با استفاده از دو صف فهرست‌بندی نشان می‌دهد. به طور خاص، شکل 2 پیمایش دوم انجام شده با استفاده از یک استراتژی پیمایش کامل را نشان می‌دهد. این مراحل از فراخوانی‌های REST API استفاده می‌کنند. برای فراخوانی‌های معادل SDK، به عملیات صف (Connector SDK) مراجعه کنید.

شکل ۲. حذف موارد

توجه: در فهرست مراحل زیر، مراحل ۱ تا ۴ در شکل ۲ نشان داده نشده‌اند، زیرا مشابه مراحل ۱ تا ۴ در نمودار قبلی هستند و در محدوده این بخش قرار نمی‌گیرند. مرحله ۵ نشان داده نشده است زیرا فراخوانی تابع deleteQueueItems روی یک صف خالی در محدوده این بخش نیست. این نمودار بر پیمایش دوم تمرکز دارد.

1. در پیمایش اولیه، رابط محتوا از items.push برای قرار دادن آیتم‌ها (فراداده و هش) در یک صف نمایه‌سازی استفاده می‌کند، "صف A" به عنوان NEW_ITEM زیرا در صف وجود ندارد. به هر آیتم برچسب "A" برای "صف A" اختصاص داده می‌شود. محتوا در جستجوی ابری نمایه‌سازی می‌شود.

   نکته: رابط می‌تواند با استفاده از فیلد queue آیتم، در حین عملیات item.push یا item.index ، یک برچسب صف به یک آیتم اختصاص دهد. این برچسب را می‌توان هر زمان که آیتم دوباره نمایش داده یا دوباره فهرست‌بندی می‌شود، تغییر داد.

2. رابط محتوا از items.poll برای نظرسنجی از صف A و تعیین مواردی که باید فهرست شوند استفاده می‌کند. Cloud Search به رابط می‌گوید کدام موارد بیشترین نیاز به فهرست‌بندی دارند، که ابتدا بر اساس کد وضعیت و سپس بر اساس زمان حضور در صف مرتب شده‌اند.

3. کانکتور این موارد را از مخزن بازیابی می‌کند و درخواست‌های API شاخص را می‌سازد.

4. کانکتور از items.index برای فهرست‌بندی اقلام استفاده می‌کند. اقلام فقط پس از اینکه Cloud Search با موفقیت پردازش آنها را به پایان رساند، وارد حالت ACCEPTED می‌شوند.

5. متد deleteQueueItems در صف B فراخوانی می‌شود. اما هیچ آیتمی به صف B منتقل نشده است، بنابراین نمی‌توان چیزی را حذف کرد.

6. در دومین پیمایش کامل، رابط محتوا از items.push برای ارسال آیتم‌ها (فراداده و هش) به صف B استفاده می‌کند:

   • هنگام ارسال، کانکتور به صراحت type ارسال یا contentHash را در نظر می‌گیرد.
   • اگر کانکتور شامل type نباشد، جستجوی ابری به‌طور خودکار از contentHash برای تعیین وضعیت آیتم استفاده می‌کند.
   • اگر کالا ناشناخته باشد، وضعیت کالا روی NEW_ITEM تنظیم می‌شود و برچسب صف به "B" تغییر می‌یابد.
   • اگر آیتم وجود داشته باشد و مقادیر هش مطابقت داشته باشند، وضعیت به صورت ACCEPTED حفظ می‌شود و برچسب صف به "B" تغییر می‌یابد.
   • اگر آیتم وجود داشته باشد و هش‌ها متفاوت باشند، وضعیت به MODIFIED تغییر می‌کند و برچسب صف به "B" تغییر می‌یابد.

7. رابط محتوا از items.poll برای نظرسنجی از صف و تعیین مواردی که باید فهرست شوند استفاده می‌کند. جستجوی ابری به رابط می‌گوید کدام موارد بیشترین نیاز به فهرست‌بندی را دارند، که ابتدا بر اساس کد وضعیت و سپس بر اساس زمان حضور در صف مرتب شده‌اند.

8. کانکتور این موارد را از مخزن بازیابی می‌کند و درخواست‌های API شاخص را می‌سازد.

9. کانکتور از items.index برای فهرست‌بندی اقلام استفاده می‌کند. اقلام فقط پس از اینکه Cloud Search با موفقیت پردازش آنها را به پایان رساند، وارد حالت ACCEPTED می‌شوند.

10. در نهایت، تابع deleteQueueItems در صف A فراخوانی می‌شود تا تمام آیتم‌های CCloud Search که قبلاً ایندکس شده‌اند و هنوز برچسب صف "A" را دارند، حذف کند.

11. با پیمایش‌های کامل بعدی، صف مورد استفاده برای اندیس‌گذاری و صف مورد استفاده برای حذف، جایشان عوض می‌شود.

عملیات صف (SDK کانکتور)

کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) عملیات‌هایی را برای ارسال آیتم‌ها به صف و دریافت آیتم‌ها از آن فراهم می‌کند.

برای بسته‌بندی و ارسال یک آیتم به صف، از کلاس سازنده‌ی pushItems استفاده کنید.

برای استخراج آیتم‌ها از صف پردازش، نیازی به انجام کار خاصی ندارید. در عوض، SDK به طور خودکار آیتم‌ها را به ترتیب اولویت و با استفاده از متد getDoc کلاس Repository از صف استخراج می‌کند.

عملیات صف (REST API)

REST API دو روش زیر را برای ارسال و دریافت آیتم‌ها از یک صف ارائه می‌دهد:

• برای قرار دادن یک آیتم در صف، از Items.push استفاده کنید.
• برای نظرسنجی از آیتم‌های موجود در صف، Items.poll استفاده کنید.

همچنین می‌توانید از Items.index برای ارسال آیتم‌ها به صف در حین ایندکس‌گذاری استفاده کنید. آیتم‌هایی که در حین ایندکس‌گذاری به صف ارسال می‌شوند نیازی به type ندارند و به طور خودکار وضعیت ACCEPTED به آنها اختصاص داده می‌شود.

Items.push

متد Items.push شناسه‌ها را به صف اضافه می‌کند. این متد را می‌توان با یک مقدار type خاص که نتیجه عملیات push را تعیین می‌کند، فراخوانی کرد. برای مشاهده لیستی از مقادیر type ، به فیلد item.type در متد Items.push مراجعه کنید.

اضافه کردن یک شناسه جدید منجر به اضافه شدن یک ورودی جدید با کد NEW_ITEM ItemStatus می‌شود.

مقدار اختیاری payload همیشه ذخیره می‌شود، به عنوان یک مقدار مبهم در نظر گرفته می‌شود و از Items.poll برگردانده می‌شود.

وقتی یک آیتم مورد نظرخواهی قرار می‌گیرد، رزرو شده است، به این معنی که نمی‌توان آن را با فراخوانی دیگری به Items.poll برگرداند. استفاده از Items.push با type NOT_MODIFIED ، REPOSITORY_ERROR یا REQUEUE ، ورودی‌های مورد نظرخواهی را از حالت رزرو خارج می‌کند . برای اطلاعات بیشتر در مورد ورودی‌های رزرو شده و رزرو نشده، به بخش Items.poll مراجعه کنید.

Items.push با هش‌ها

API جستجوی ابری گوگل از تعیین مقادیر هش فراداده و محتوا در درخواست‌های Items.index پشتیبانی می‌کند. به جای تعیین type ، می‌توان مقادیر هش فراداده و/یا محتوا را با یک درخواست ارسالی مشخص کرد. صف نمایه‌سازی جستجوی ابری، مقادیر هش ارائه شده را با مقادیر ذخیره شده موجود در آیتم در منبع داده مقایسه می‌کند. در صورت عدم تطابق، آن ورودی به عنوان MODIFIED علامت‌گذاری می‌شود. اگر آیتم مربوطه در ایندکس وجود نداشته باشد، وضعیت NEW_ITEM است.

نکته: مقادیر هش ارائه شده با درخواست‌های Items.push همراه با آیتم ذخیره نمی‌شوند. این آیتم‌ها فقط برای تعیین اینکه آیا آیتم تغییر داده شده است یا خیر، استفاده می‌شوند.

Items.poll

متد Items.poll ورودی‌های با بالاترین اولویت را از صف بازیابی می‌کند. مقادیر وضعیت درخواستی و بازگشتی، وضعیت صف(های) اولویت‌دار درخواستی یا وضعیت شناسه‌های بازگشتی را نشان می‌دهند.

به طور پیش‌فرض، ورودی‌های هر بخش از صف می‌توانند بر اساس اولویت بازگردانده شوند. هر ورودی بازگردانده شده رزرو شده است و تا زمانی که یکی از موارد زیر برآورده نشود، توسط سایر فراخوانی‌های Items.poll بازگردانده نمی‌شود:

• مهلت رزرو به پایان رسیده است.
• ورودی دوباره توسط Items.index در صف قرار می‌گیرد.
• Items.push با مقداری از type NOT_MODIFIED ، REPOSITORY_ERROR یا REQUEUE فراخوانی می‌شود.