نظرة عامة على عملية الدمج

عقدت "إعلانات الخدمات المحلّية" (LSA) شراكة مع العارضين لعرض بياناتهم (أو مقدّمي الخدمات) على Google.com. في هذا الدليل، نوضّح كيف يمكن للعارضين تقديم بيانات منظَّمة لإعلانات LSA عن مقدّمي الخدمات. وعلى وجه التحديد، نوثّق مجموعة برامج نقاط نهاية واجهة برمجة التطبيقات التي يجب تنفيذها لدمجها مع "التطبيقات الأقل أمانًا".

مسرد المصطلحات

المُجمِّع (أو الشريك): هؤلاء هم الشركاء الذين يجمعون مقدّمي الخدمات الذين يقدّمون خدمات لهم ويمكن تقديم بياناتهم إلى "اتفاقية LSA".

مقدّم خدمة تابع لطرف ثالث (أو البيانات): هذه هي الأنشطة التجارية الصغيرة الفردية (مثل سمير لخدمات السباكة) التي قد تربطها علاقة تجارية مع مجمِّعي السلع. يوفّر مجمِّع السلع معلومات عن "الخدمات المحلّية" حول هذه الأنشطة التجارية.

نظرة عامة

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

أنواع الخلاصات

بالنسبة إلى عملية الدمج الأولية، يمكن أن تكون كل خلاصة من أنواع الخلاصات التالية:

• خلاصات الملفات الشخصية: توفّر هذه الخلاصة معلومات عن الملفات الشخصية لمقدّمي الخدمات. يلخّص كل عنصر في الخلاصة معلومات الملف الشخصي عن مقدّم خدمة معيّن. ويتضمّن ذلك معرّفًا فريدًا للنشاط التجاري واسمًا للنشاط التجاري ومواقع عرض الخدمات والخدمات المقدَّمة وساعات العمل وما إلى ذلك. ويتضمّن عنصر الخلاصة أيضًا بيانات وصفية للعرض لهذا النشاط التجاري (مثل مبلغ الميزانية الشهرية وحالة الإعلان وغير ذلك).

• خلاصات المراجعة: توفّر هذه الخلاصة معلومات عن مراجعات موفّري الخدمة. يتضمّن كل عنصر في الخلاصة قائمة بالمراجعات المفصّلة للمستهلكين لمقدّم خدمة محدّد. تتكون كل مراجعة من المستهلكين من اسم المستهلك والتقييم (1 - 5)، ونص المراجعة، والطابع الزمني للمراجعة، وما إلى ذلك.

يمكنك الاطّلاع على المزيد من التفاصيل حول الحقول المحدّدة ودلالاتها في خلاصة الملف الشخصي ومراجعة الخلاصة.

عرض الخلاصة

يتم إنشاء تسلسل بيانات الخلاصة على شكل JSON. لإرسال البيانات، يمكن استخدام آلية السحب الآلي فقط. تتوفّر خطط مستقبلية لإتاحة آلية إرسال الدفعات.

آلية السحب

في آلية السحب، تتيح العارضات استخدام مجموعة من نقاط نهاية REST المحدّدة مسبقًا (عناوين URL) التي ترسل كائنات JSON وتتلقّاها. ويشبه ذلك استضافة ملف واحد أو أكثر على خادم الويب. وستُصدِر "إعلانات LSA" طلبات HTTP GET بشكل دوري إلى عناوين URL هذه لجلب البيانات. يمكن العثور على تفاصيل حول عناوين URL المحددة مسبقًا في القسم التالي حول نقاط نهاية واجهة برمجة التطبيقات.

آلية الدفع

في آلية الدفع، ستوفّر أداة LSA نقطة نهاية للمُجمِّعين للاتصال والبيانات. دلاليًا هو نفسه السحب، ولكنه يوفّر المرونة في الحالات التي يريد فيها العارضين إرسال بيانات محدّدة إلى "الخدمات المحلّية". جميع دلالات القواعد أو القواعد والقيود الموضّحة في البروتوكول تنطبق على كلٍّ من الدفع والسحب بالطريقة نفسها.

نقاط نهاية واجهة برمجة التطبيقات

يجب أن تتوافق نقاط النهاية التالية مع العارضين: نقطة واحدة لخلاصة الخلاصة والأخرى للمراجعة.

مسار نقاط النهاية المقترحة

ننصح بأن تحتوي نقاط النهاية على معلومات الإصدار كما هو موضّح أدناه. نبدأ بـ v1.

نقطة النهاية	المسار
خلاصة الملف الشخصي	/feeds/{version}/profile
مراجعة الخلاصة	/feeds/{version}/review

معلمة نقطة النهاية

المعلمات	الوصف
maxresults	هذا هو الحد الأقصى لعدد عناصر الخلاصة التي يمكن طلبها في الصفحة الواحدة.
nextpagetoken	الرمز المميّز للتقسيم على صفحات للحصول على الصفحة التالية من النتائج

مصادقة نقاط النهاية

تستخدم المصادقة مصادقة الوصول الأساسي إلى HTTP: اسم المستخدم المشفّر base64 وكلمة المرور للمصادقة. في ما يلي مثال على ذلك.

• username"تفويض" (لأغراض توضيحية)
• password J9adfdsafc3RfMjpVU1yif5XMw (لأغراض توضيحية)

صندوق إسقاط بروتوكول النقل الآمن للملفات (SFTP) لإرسال البيانات

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

تحذير: يتم تلقائيًا حذف الملفات التي تم تحميلها إلى هذا الصندوق بعد مرور 24 ساعة.

مصادقة نقاط النهاية

• مفتاحا تشفير عام/خاص (مقترَح)

  • استخدِم البرنامج التعليمي هنا لإنشاء أزواج من المفاتيح.
  • أرسِل LSA المفتاح العام واحتفِظ بالمفتاح الخاص للمصادقة.
  • ستستخدم LSA المفتاح العام لإنشاء اسم مستخدم وإرساله مرة أخرى إلى العارض

• مصادقة كلمة المرور

  • ستنشئ LSA اسم المستخدم وكلمة المرور وترسل المُجمِّع مرة أخرى.

مرجع سريع لأمر بروتوكول النقل الآمن للملفات (SFTP)

1. تسجيل الدخول: استخدِم هذا الأمر لتسجيل الدخول. (يُرجى عدم استخدام مفتاح خاص <i في حال عدم استخدامه't.

   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) وتحقّق من نسخ ملفك إلى النظام البعيد.

فئات الخلاصة

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

تحتوي خلاصة اللقطة على قائمة كاملة بمقدّمي الخدمات (ضمن مجمّع سلع) في طابع زمني محدّد. بعد معالجة خلاصة اللقطة هذه، تنطبق الدلالات التالية:

• بالنسبة إلى أي موفّر خدمة في الخلاصة، سيُعدّل النظام بيانات مقدّم الخدمة في قاعدة بيانات "إعلانات Google" (مثل إنشاء موفّر جديد إذا تم رصده للمرة الأولى، أو تعديل بيانات مقدّم الخدمة في حال معالجة مقدّم الخدمة في خلاصة سابقة).

• بالنسبة إلى أي مقدّم خدمة ضمن المجمِّع الموجود حاليًا في قاعدة بيانات "إعلانات Google"، ولكن لا تتوفّر في الخلاصة، سيتم حذف مقدّم الخدمة.

تحتوي خلاصة التعديل (أو المتزايدة) على قائمة جزئية بمقدّمي الخدمات (ضمن مجمّع سلع) في طابع زمني محدّد. بعد معالجة خلاصة تدريجيّة، ستُطبَّق الدلالة التالية:

• عند تحديث أي مقدّم خدمة في الخلاصة، سيُعدِّل النظام بيانات هذا الموفّر في قاعدة بيانات "إعلانات Google" إذا كان قد تم إنشاؤه في خلاصة سابقة. (على سبيل المثال، إذا واجه مقدّم خدمة التطبيق للمرة الأولى، سيكون

• بالنسبة إلى أي مقدّم خدمة حالي في قاعدة بيانات LSA، ولكن غير متوفّر في الخلاصة، هذه عمليّة مستقلة (أي لن يحدث أي تغيير في مقدّم الخدمة).

دلالات الملف الشخصي للملف الشخصي مقابل خلاصة المراجعات مختلفة قليلاً. يُرجى الاطّلاع على دلالات الخلاصة الفردية للحصول على تفاصيل المعالجة.

خلاصات الملفات الشخصية: * خلاصات ميزة "لمحة" استنادًا إلى السحب * خلاصات "لمحة" المستندة إلى السحب * خلاصات "تحديث" مستندة إلى الإشعارات مراجعة الخلاصات: * خلاصات "لمحة" مستندة إلى السحب * خلاصات "لمحة" مستندة إلى الدفع

يجب ضبط خلاصات ملفات شخصية منفصلة لما يلي:

1. مقدّمو الخدمات الذين يُعتبرون مؤهّلين للحصول على شارة بضمان من Google أو تم تقييم الخدمة من قِبل Google.

2. مقدّمو الخدمات غير المؤهَّلين للحصول على الشارة.

أمثلة

خلاصات اللقطة

تذكّر أنّ خلاصة اللقطة ستتألف من قائمة كاملة بمقدّمي الخدمات. على سبيل المثال، إذا كان مجمّع الطلبات يريد نقل 100 مقدّم خدمة إلى LSA، يجب أن تحتوي خلاصة لقطة الشاشة على أحدث حالة لجميع 100 مقدّم خدمة.

آلية العمل

في ما يلي مثال بسيط يوضّح آلية عمل فئة النبذة عن خلاصات الملف الشخصي.

• لقطة 1 تحتوي على Pro 1 وPro 2
• لقطة 2 تحتوي على Pro 1، Pro 3

بعد معالجة Snapshot 1، ستحتوي قاعدة بيانات LSA على Pro 1 وPro 2. أثناء معالجة اللقطة 2، ستُحدِّث أداة LSA Pro 1 وتنشئ Pro 3 وتحذف Pro 2. وهذا يعني أنه بعد معالجة Snapshot 2، سيكون لدى قاعدة بيانات LSA Pro 1 وPro 3.

تعديل الخلاصات (المتزايدة)

تذكّر أنّ خلاصة التحديث تحتوي على قائمة جزئية من موفّري الخدمة ضمن مجمّع. على سبيل المثال، إذا كان مجمِّع الموسيقى يريد تعديل 5 من بين 100 مقدّم خدمة سبق أن تمت إضافته، يجب أن تحتوي خلاصة التحديث على أحدث حالة لهؤلاء المزوّدين الخمسة.

آلية العمل

في ما يلي مثال بسيط يوضّح طريقة عمل فئة التعديل "خلاصات الملف الشخصي".

• التحديث 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.

الآثار المترتبة على اللقطة والسحب

تتطلّب آلية لقطات Snap" و"السحب" الحصول على القيود التالية:

• قد يتأخر الشركاء في إضافة مقدّمي الخدمات أو حذفهم أو تعديل معلومات الملف الشخصي أو إيقاف الإعلانات مؤقتًا أو تغيير الميزانيات لبضع ساعات. التأخير مرتبط مباشرةً بمعدل تكرار طلبات السحب.
• ولإجراء تعديلات عاجلة على البيانات، قد نحتاج إلى دعم سحب لمرة واحدة/الدفع اليدوي.

الآثار المترتبة على الدعم المتزايد والإعلانات الفورية

يعني فتح آلية تحديث الخلاصات + الإرسال التحسينات التالية:

• يمكن للشركاء عرض خلاصة اللقطة إما بالدفع أو السحب. بالنسبة إلى الشركاء الذين يفضّلون عدم الحفاظ على نقطة النهاية (في السحب) يمكنهم استخدام الدفع بدلاً من ذلك لخفض تكلفة صيانة نقطة النهاية. يوفّر الشريك خلاصات هذه اللقطات في هذا المنتج باستمرار، لذا يُرجى مواصلة تقديم لقطات.
• يمكن للشركاء استخدام الإضافات بشكل تدريجي لتعديل مجموعة فرعية فقط من مقدّمي الخدمات باستخدام تغييرات الملفات الشخصية. ويساهم ذلك في تحسين مدى حداثة بيانات الملف التجاري.
• من حيث كيفية اختيار لقطة في مقابل التزايدات، والضغط مقابل السحب، اطّلع على هذا القسم لمعرفة نهج الدمج المقترح.

نهج الدمج المقترح

يجب أن يحصل الشركاء على خلاصات لقطات دورية، سواءً عن طريق الدفع أو السحب. ويسمح هذا الإجراء لتطبيق "إعلانات Google" بالتعامل مع حالات الطوارئ، مثل العودة إلى الحالة السابقة واسترداد النظام في حال توفّر تحديثات مفقودة.

• وفقًا لآلية الإرسال التلقائي، يجب على الشركاء إرسال خلاصات الملفات الشخصية للقطات فيديو كل ساعتين ومراجعة الخلاصات كل 6 ساعات لضمان حداثة البيانات الأساسية.
• باستخدام آلية السحب، ستسحب LSA خلاصات الملف الشخصي كل ساعتين وتراجع الخلاصات كل 6 ساعات لضمان حداثة البيانات المرجعية.
• يحتاج الشركاء إلى إحدى الآليات (إما الدفع أو السحب)، ولكن ليس كليهما، لإرسال خلاصات اللقطة.

اختياريًا، يمكن للشركاء الذين يريدون تحسين حداثة البيانات إرسال خلاصات التعديلات عبر إرسال البيانات. لن تُسحب LSA خلاصات التحديث.

• تُستخدم خلاصات التحديث لنشر العناصر التي تم تغييرها منذ آخر لقطة بدون انتظار اللقطة التالية.
• تنصحك "إعلانات Google" بأن يكون لدى مقدّمي الخدمة فاصل زمني أكبر من 5 دقائق بين عمليتَي إرسال.
• وننصحك بتجميع عناصر الخلاصة بشكل معقول في خلاصة تعديل. لتحديث 5 مقدّمي خدمات، يفضّل المورّدون إرسال خلاصة تعديل واحدة تتضمّن 5 عناصر في الخلاصة بدلاً من إرسال 5 خلاصات تعديل مع إضافة خلاصة واحدة في كل خلاصة.
• تتيح "إعلانات LSA" الخلاصات التدريجيّة فقط لخلاصات الملفات الشخصية، وليس لخلاصات المراجعة.

ستتضمّن LSA الحقل feedTimestampMicros في البيانات الوصفية لضمان اتّساق البيانات. وسيتم تخطّي عنصر في الخلاصة يتضمّن طابعًا زمنيًا قديمًا لتجنّب حدوث مشاكل إذا تم عرض سلعة أحدث تعمل على تعديل الخبير نفسه. ويتحمّل الشريك مسؤولية حداثة البيانات بشكلٍ صحيح باستخدام feedTimestampMicros في كلٍّ من الخلاصات الخاصة بالخلاصات المعدّلة.

وعلى الشركاء استخدام واجهة برمجة التطبيقات لإعداد التقارير للحصول على معلومات حول العملاء المحتملين والرسوم لكل مقدّم خدمة.