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

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

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

مجمّع (أو شريك): هم شركاء يجمعون مقدّمي الخدمات الذين يقدّمون لهم الخدمات، وقد يتم تقديم بياناتهم إلى "مقدّمي الخدمات المحلّيين".

مزوّد الطرف الثالث (أو بطاقة بيانات): يشير ذلك إلى الأنشطة التجارية الصغيرة الفردية (مثل (مثل شركة Joe’s plumbing) الذين قد تكون لديهم علاقة تجارية مع جهات تجميع. تقدّم المواقع المجمّعة إلى "الخدمات المحلّية" معلومات عن هذه الأنشطة التجارية.

نظرة عامة

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

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

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

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

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

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

نقل الخلاصة

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

آلية السحب

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

آلية الإشعارات الفورية

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

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

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

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

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

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

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

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

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

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

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

صندوق تحميل SFTP لخدمة Push

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

تحذير: يتم حذف الملفات التي يتم تحميلها إلى صندوق الإيداع هذا عبر SFTP تلقائيًا بعد 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 والتأكّد من أنّه تم نسخ ملفك إلى النظام البعيد.

فئات الخلاصة

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

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

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

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

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

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

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

تختلف دلالات الملف التجاري عن خلاصة المراجعات قليلاً. راجِع دلالات الخلاصات الفردية لمعرفة تفاصيل المعالجة.

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

يجب توفير خلاصات ملفات شخصية منفصلة لما يلي:

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

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

أمثلة

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

تذكَّر أنّ خلاصة اللقطة ستتألف من قائمة كاملة بمقدّمي الخدمة. على سبيل المثال، إذا أراد أحد مزوّدي خدمات التجميع إدخال 100 مقدّم خدمة إلى "إعلانات الخدمات المحلية"، يجب أن تحتوي خلاصة اللقطة على أحدث حالة لجميع مقدّمي الخدمات الـ 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 المنتج 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.

تأثيرات ميزة "اللقطة" و"السحب"

يشير آلية خلاصات اللقطات + السحب إلى القيود التالية:

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

تأثيرات دعم التحديثات التزايدية والتحديثات الإجبارية

يؤدي فتح آلية تعديل الخلاصات + الإشعارات الفورية إلى التحسينات التالية:

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

طريقة الدمج المقترَحة

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

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

يمكن للشركاء الذين يريدون تحسين تعديل البيانات إرسال خلاصات معدَّلة عبر الإرسال الفوري. لن تسحب "حسابات المؤسسات المحلية" خلاصات التحديثات.

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

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

على الشركاء استخدام Reporting API للحصول على معلومات حول العملاء المحتملين والرسوم لكل مقدّم خدمة.