نمای کلی ادغام

تبلیغات خدمات محلی (LSA) برای مشارکت با جمع‌آورندگان برای نمایش فهرست‌ها (یا ارائه‌دهندگان) آنها در Google.com. در این راهنما، ما توضیح می‌دهیم که چگونه تجمیع‌کننده‌ها می‌توانند داده‌های ساختار یافته LSA را در مورد ارائه‌دهندگان خود ارائه دهند. به طور خاص، ما مجموعه ای از نقاط پایانی API را که باید برای ادغام با LSA پیاده سازی کنند، مستند می کنیم.

واژه نامه

جمع کننده (یا شریک) : اینها شرکای هستند که ارائه دهندگانی را که به آنها خدمات ارائه می دهند و داده های آنها ممکن است به LSA ارائه شود را جمع آوری می کنند.

ارائه‌دهنده 3P (یا فهرست) : اینها مشاغل کوچک فردی هستند (مثلاً لوله‌کشی جو) که ممکن است با جمع‌آوران رابطه تجاری داشته باشند. تجمیع‌کنندگان اطلاعات مربوط به این کسب‌وکارها را به خدمات محلی ارائه می‌کنند.

نمای کلی

تجمیع‌کنندگان با استفاده از فیدها، داده‌های مربوط به ارائه‌دهندگان (کسب‌وکار) خود را در اختیار خدمات محلی قرار می‌دهند. هر فید شامل داده‌هایی درباره چندین ارائه‌دهنده است. در یک فید، داده‌های مربوط به یک ارائه‌دهنده واحد توسط یک مورد فید محصور می‌شوند. هر خوراک همچنین یک مهر زمانی خوراک را مشخص می کند که نشان دهنده تازگی خوراک است. هر فید همچنین یک نوع فید را مشخص می‌کند: این ممکن است داده‌های مربوط به نمایه ارائه‌دهنده یا نظرات ارائه‌دهنده باشد که در زیر توضیح داده شده است.

انواع خوراک

برای ادغام اولیه، هر خوراک ممکن است یکی از انواع خوراک زیر باشد:

• فیدهای نمایه: این فید اطلاعاتی در مورد نمایه های ارائه دهنده ارائه می دهد. هر مورد فید اطلاعات نمایه مربوط به یک ارائه دهنده خاص را در بر می گیرد. این شامل یک شناسه کسب‌وکار منحصر به فرد، نام کسب‌وکار، مکان‌های ارائه خدمات، خدمات ارائه شده، ساعات کار و غیره می‌شود. مورد فید همچنین حاوی فراداده‌های ارائه‌شده برای این کسب‌وکار است (به‌عنوان مثال، میزان بودجه ماهانه، وضعیت آگهی و غیره).

• فیدهای بازبینی: این فید اطلاعاتی درباره نظرات ارائه‌دهنده ارائه می‌دهد. هر مورد خوراک فهرستی از بررسی های دقیق مصرف کنندگان از یک ارائه دهنده خاص را در بر می گیرد. هر نظر مصرف کننده شامل نام مصرف کننده، رتبه بندی (1 - 5)، متن بررسی، مهر زمانی بررسی و غیره است.

جزئیات بیشتر در مورد فیلدهای خاص و معنای آنها در فید نمایه و فید بررسی .

مصرف خوراک

داده های فید به صورت JSON سریال می شوند. برای ارسال داده ها، LSA فقط از مکانیزم کششی پشتیبانی می کند. برنامه های آتی برای حمایت از مکانیزم فشار وجود دارد.

مکانیزم کشش

در مکانیزم کشش، جمع‌کننده‌ها مجموعه‌ای از نقاط پایانی REST (URL) از پیش تعریف‌شده را پشتیبانی می‌کنند که اشیاء JSON را ارسال و دریافت می‌کنند. این مشابه میزبانی یک یا چند فایل در یک وب سرور است. LSA به صورت دوره ای درخواست های HTTP GET را برای این URL ها برای واکشی داده ها صادر می کند. جزئیات مربوط به URL های از پیش تعریف شده را می توان در بخش بعدی در نقاط انتهایی API یافت.

مکانیزم فشار

در مکانیزم فشار، LSA نقطه پایانی را برای جمع‌آوری‌کننده‌ها فراهم می‌کند تا بتوانند داده‌ها را فراخوانی کنند. از نظر معنایی، این همان کشش است، اما در مواردی که تجمیع‌کننده‌ها می‌خواهند داده‌های خاصی را به سرویس‌های محلی فشار دهند، انعطاف‌پذیری را فراهم می‌کند. تمام معنایی ها، قوانین یا محدودیت های شرح داده شده در پروتکل برای فشار و کشش به یک روش اعمال می شود.

نقاط پایانی API

نقاط پایانی زیر باید توسط تجمیع‌کننده‌ها پشتیبانی شوند: یکی برای فید نمایه و دیگری برای فید مرور.

مسیر نقاط پایانی توصیه شده

توصیه می کنیم نقاط پایانی حاوی اطلاعات نسخه مانند زیر باشد. ما با v1 شروع می کنیم.

نقطه پایانی	مسیر
فید نمایه	/feeds/{version}/profile
بررسی فید	/feeds/{version}/review

پارامتر نقطه پایانی

پارامترها	توضیحات
maxresults	این محدودیت برای تعداد موارد فید می تواند در یک صفحه درخواست شود.
nextpagetoken	نشانه صفحه بندی برای دریافت صفحه بعدی نتایج

احراز هویت نقطه پایانی

احراز هویت از احراز هویت دسترسی اولیه HTTP استفاده می کند: نام کاربری و رمز عبور کدگذاری شده با base64 برای احراز هویت. در زیر یک نمونه آورده شده است.

• username "Authorization" (برای اهداف توضیحی)
• password J9adfdsafc3RfMjpVU1yif5XMw” (برای اهداف توضیحی)

SFTP dropbox برای فشار

مسیر Dropbox: partnerupload.google.com:19321

اخطار: فایل‌های بارگذاری شده در این SFTP drop box به طور خودکار پس از 24 ساعت حذف می‌شوند.

احراز هویت نقطه پایانی

• جفت کلید عمومی/خصوصی (توصیه می شود)

  • از آموزش اینجا برای تولید جفت کلید استفاده کنید.
  • کلید عمومی را برای LSA ارسال کنید و کلید خصوصی را برای احراز هویت نگه دارید
  • LSA از کلید عمومی برای ایجاد نام کاربری و ارسال مجدد به جمع کننده استفاده می کند

• احراز هویت رمز عبور

  • LSA نام کاربری و رمز عبور را تولید می کند و به جمع کننده ارسال می کند

مرجع سریع فرمان SFTP

1. وارد شوید. از این دستور برای ورود استفاده کنید. (-i را کنار بگذارید اگر از کلید خصوصی استفاده نمی کنید).

   sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

2. کپی فایل فایل را در سیستم راه دور کپی کنید. می توانید lls/lcd به ls/cd در سیستم محلی خود برای یافتن فایل استفاده کنید. سپس فایل را از طریق:

   put <path_to_local_file>

3. تأیید کنید. از ls برای دیدن لیستی از پوشه ها و فایل ها در دایرکتوری SFTP استفاده کنید و تأیید کنید که فایل شما در سیستم راه دور کپی شده است.

دسته بندی خوراک

همانطور که قبلا ذکر شد، هر فید مشابه یک فایل است و از چندین آیتم خوراک تشکیل شده است. هر مورد فید داده‌های مربوط به یک ارائه‌دهنده خاص را در بر می‌گیرد (شناسه کسب‌وکار منحصر به فرد). هر فید همچنین دارای یک مهر زمانی است که نشان دهنده تازگی این فید است. Feed Category مشخص می کند که LSA چگونه فید داده شده را تفسیر می کند. دو دسته از فیدها وجود دارد که در زیر توضیح داده شده است.

فید اسنپ شات حاوی لیست کاملی از ارائه دهندگان (تحت یک جمع کننده) در یک مهر زمانی خاص است. پس از پردازش این فید عکس فوری، معنایی زیر اعمال می شود:

• برای هر ارائه‌دهنده‌ای که در فید وجود دارد، سیستم داده‌های این ارائه‌دهنده را در پایگاه داده LSA به‌روزرسانی می‌کند (به عنوان مثال، اگر برای اولین بار با آن مواجه می‌شوید، یک ارائه‌دهنده جدید ایجاد کنید، یا اگر ارائه‌دهنده در فید قبلی پردازش شده بود، داده‌های ارائه‌دهنده را به‌روزرسانی می‌کند).

• برای هر ارائه‌دهنده تحت جمع‌آوری که در حال حاضر در پایگاه داده LSA وجود دارد، اما در فید وجود ندارد، ارائه‌دهنده حذف خواهد شد.

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

• برای هر ارائه‌دهنده‌ای که در فید وجود دارد، اگر ارائه‌دهنده در فید فوری قبلی ایجاد شده باشد، سیستم داده‌های این ارائه‌دهنده را در پایگاه داده LSA به‌روزرسانی می‌کند. (مثلاً اگر برای اولین بار با یک ارائه‌دهنده مواجه می‌شوید، غیرفعال خواهد بود)

• برای هر ارائه‌دهنده‌ای که در حال حاضر در پایگاه داده LSA وجود دارد، اما در فید وجود ندارد، این یک غیرفعال است (یعنی هیچ تغییری در این ارائه‌دهنده وجود نخواهد داشت).

معناشناسی فید نمایه در مقابل نظرات کمی متفاوت است. برای جزئیات پردازش به معنای فید فردی مراجعه کنید.

فیدهای نمایه: * فیدهای Snapshot مبتنی بر Pull * فیدهای Snapshot مبتنی بر Push * فیدهای Update مبتنی بر Push فیدهای بررسی: * فیدهای Snapshot مبتنی بر Pull * فیدهای Snapshot مبتنی بر فشار

فیدهای نمایه جداگانه برای موارد زیر مورد نیاز است:

1. ارائه‌دهندگانی که واجد شرایط دریافت گارانتی Google یا نشان غربال‌شده Google هستند.

2. ارائه دهندگانی که واجد شرایط دریافت نشان نیستند.

نمونه ها

فیدهای عکس فوری

به یاد داشته باشید که یک فید فوری شامل لیست کاملی از ارائه دهندگان است. به عنوان مثال، اگر یک تجمیع کننده بخواهد 100 ارائه دهنده به LSA وارد شوند، فید عکس فوری باید آخرین وضعیت را برای همه 100 ارائه دهنده داشته باشد.

چگونه این کار می کند

در زیر یک مثال ساده نشان داده شده است که نحوه عملکرد دسته عکس فوری از فیدهای نمایه را نشان می دهد.

• اسنپ شات 1 دارای Pro 1، Pro 2 است
• Snapshot 2 دارای Pro 1, Pro 3 است

پس از پردازش اسنپ شات 1، دیتابیس LSA دارای Pro 1 و Pro 2 خواهد بود. در حین پردازش اسنپ شات 2، LSA پرو 1 را به روز می کند، Pro 3 را ایجاد می کند و پرو 2 را حذف می کند. یعنی پس از پردازش اسنپ شات 2، پایگاه داده LSA دارای Pro 1 و Pro 3 خواهد بود.

به روز رسانی (افزایشی) فیدها

به یاد داشته باشید که یک فید به‌روزرسانی حاوی فهرستی جزئی از ارائه‌دهندگان تحت یک جمع‌کننده است. به عنوان مثال، اگر یک جمع‌کننده فقط بخواهد 5 مورد از 100 ارائه‌دهنده قبلی خود را به‌روزرسانی کند، فید به‌روزرسانی فقط باید آخرین وضعیت این 5 ارائه‌دهنده را داشته باشد.

چگونه این کار می کند

در زیر یک مثال ساده نشان می دهد که چگونه دسته به روز رسانی "فیدهای پروفایل" کار می کند.

• به روز رسانی 1: Pro 1، Pro 2
• به روز رسانی 2: Pro 1، Pro 3

پس از پردازش به روز رسانی 1، پایگاه داده LSA دارای Pro 1 و Pro 2 خواهد بود. در طول پردازش به روز رسانی 2، LSA Pro 1 را به روز می کند و Pro 3 را ایجاد می کند. توجه داشته باشید که Pro 2 دست نخورده است. یعنی پس از پردازش به روز رسانی 2، پایگاه داده LSA دارای Pro1، Pro2 و Pro 3 خواهد بود.

مفاهیم Snapshot و Pull

مکانیسم تغذیه + کشش فوری شامل محدودیت های زیر است:

• ممکن است برای اضافه کردن یا حذف ارائه دهندگان، به روز رسانی اطلاعات نمایه، توقف موقت تبلیغات یا تغییر بودجه، شرکا چند ساعت تاخیر داشته باشند. تأخیر مستقیماً با فراوانی درخواست‌های کشش مرتبط است.
• برای به‌روزرسانی‌های فوری داده‌ها، ممکن است لازم باشد به‌صورت دستی از کشش یک‌باره/الحاقی پشتیبانی کنیم.

پیامدهای پشتیبانی افزایشی و فشاری

باز کردن فیدهای به‌روزرسانی + مکانیسم فشار شامل پیشرفت‌های زیر است:

• شرکا می توانند فید عکس فوری را به صورت فشاری یا کششی ارائه دهند. برای شرکایی که ترجیح می دهند نقطه پایانی را حفظ نکنند (برای کشش) می توانند به جای آن از فشار برای کاهش هزینه نگهداری نقطه پایانی استفاده کنند. فیدهای عکس فوری از قبل پشتیبانی شده توسط شریک در pull می توانند با خیال راحت به ارائه عکس های فوری در کشش ادامه دهند.
• شرکا می توانند برای به روز رسانی تنها زیرمجموعه ای از ارائه دهندگان با تغییرات نمایه از موارد افزایشی استفاده کنند. این امر تازگی داده های نمایه را بهبود می بخشد.
• از نظر نحوه انتخاب عکس فوری در مقابل افزایشی، فشار در مقابل کشش، برای رویکرد ادغام توصیه شده به این بخش مراجعه کنید.

رویکرد یکپارچه سازی توصیه شده

شرکا موظفند فیدهای عکس فوری دوره ای داشته باشند، چه از طریق فشار یا کشش. این به LSA اجازه می دهد تا در موارد اضطراری مانند بازگشت و بازیابی سیستم در صورت به روز رسانی از دست رفته رسیدگی کند.

• با مکانیسم فشار، شرکا باید فیدهای نمایه عکس فوری را هر 2 ساعت یکبار فشار دهند و فیدها را هر 6 ساعت یکبار بررسی کنند تا تازگی داده های پایه را تضمین کنند.
• با مکانیسم کشش، LSA هر 2 ساعت یکبار فیدهای نمایه عکس فوری را دریافت می کند و هر 6 ساعت یک بار فیدها را بررسی می کند تا تازگی داده های پایه را تضمین کند.
• شرکا فقط به یکی از مکانیسم‌ها (اعم از فشار یا کشیدن) نیاز دارند، اما نه به هر دو، برای ارائه فیدهای عکس فوری.

به صورت اختیاری، شرکایی که می خواهند تازگی داده ها را بهبود بخشند، می توانند فیدهای به روز رسانی را از طریق فشار ارسال کنند. LSA فیدهای به روز رسانی را نمی کشد.

• از فیدهای به روز رسانی برای انتشار موارد تغییر یافته از آخرین عکس فوری بدون انتظار برای عکس فوری بعدی استفاده می شود.
• LSA به ارائه دهندگان توصیه می کند که فاصله زمانی بین دو فشار بیش از 5 دقیقه داشته باشند.
• توصیه می شود موارد خوراکی را به طور معقولی در یک فید به روز قرار دهید. برای به‌روزرسانی 5 ارائه‌دهنده، LSA ترجیح می‌دهد ارائه‌دهندگان به جای فشار دادن 5 فید به‌روزرسانی با 1 خوراک در هر کدام، 1 فید به‌روزرسانی را با 5 فیدایت فشار دهند.
• LSA از فیدهای افزایشی فقط برای فیدهای نمایه پشتیبانی می کند، نه برای فیدهای مرور.

LSA فیلد feedTimestampMicros را در فراداده ها رعایت می کند تا ثبات داده ها را تضمین کند. اگر مورد تازه‌تری که همان حرفه‌ای را به‌روزرسانی می‌کند، از یک مورد فید با مهر زمانی قدیمی‌تر صرفنظر می‌شود تا از بیات شدن جلوگیری شود. این مسئولیت شریک است که با استفاده از feedTimestampMicros در فیدهای فوری و به‌روزرسانی، تازگی داده‌ها را به درستی منعکس کند.

شرکا باید از Reporting API برای دریافت اطلاعات در مورد سرنخ ها و هزینه های هر ارائه دهنده استفاده کنند.