أفضل الممارسات

يقدّم هذا المستند إرشادات حول أفضل الممارسات. راجِع نصائح الأداء للحصول على مزيد من المعلومات.

حالات استخدام واجهة برمجة التطبيقات

لإرسال الطلبات آليًا

سواء كنت تفضّل تنفيذ كل جزء من سير العمل بشكل مبرمَج أو إنشاء عنصر ربط في نظام تخطيط موارد المؤسسات (ERP)، تتيح لك Content API إرسال آخر الأخبار فور تغيُّر مستودعك.

لتلقي ملاحظات فورية

في Content API، يمكنك تلقّي ردّ على كل طلب على الفور، بدلاً من ملخّص عن طريق البريد الإلكتروني بعد معالجة خلاصات البيانات. من المتوقع أن يكون وقت الاستجابة من خمس إلى عشر ثوانٍ لطلبات الدفعة الكبيرة.

لتغيير بيانات منتجاتك بشكل متكرّر

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

لإدارة عدة حسابات فرعية

حسابات Merchant Center التي تم إنشاؤها حديثًا هي حسابات فردية، تحتفظ بمجموعتها الخاصة من بيانات المنتجات. هذا الأمر يعمل بشكل جيد في معظم الحالات، ولكن مع نمو حسابك، قد تجد أنك بحاجة إلى نظام إدارة أكثر تعقيدًا لمنتجاتك. إذا كان الأمر كذلك بالنسبة لك، ننصحك باستخدام حساب متعدّد العملاء أو MCA. يمكن إدارة حساب متعدّد العملاء على مستوى واجهة برمجة التطبيقات من خلال خدمة "الحسابات"، ما يسمح بإضافة الحسابات الفرعية وإدارتها بشكل آلي. يمكنك العثور هنا على مزيد من المعلومات حول كيفية الحصول على حساب متعدّد العملاء.

كيفية استخدام واجهة برمجة التطبيقات

عدم استخدام واجهة برمجة التطبيقات (API) مثلما تستخدم خلاصات البيانات

تجنَّب إجراء تعديلات يومية على خلاصة المنتجات بأكملها عند استخدام مورد products. بدلاً من ذلك، احرص على تحديث المنتجات التي تغيّرت بياناتها على وجه التحديد. يؤدي إرسال خلاصة البيانات بالكامل عبر مورد products إلى استهلاك المزيد من الوقت والموارد لكلّ من Google ولك.

لا تستخدِم واجهة برمجة التطبيقات لاسترداد معلومات المنتجات التي حمّلتها بانتظام.

إذا كنت مسؤولاً عن الاحتفاظ بمعلومات المنتجات في حساب معيّن على Merchant Center، تجنَّب طلب معلومات المنتجات من Content API عبر طريقة products.get أو طريقة products.list بشكل منتظم. بالنسبة إلى العملاء الذين يحمّلون المعلومات، يمكن أن تساعدك هذه الطرق في تصحيح الأخطاء عند تصميم الحلول التي تستخدم Content API. ومع ذلك، فهي غير مخصصة لاسترداد معلومات المنتجات بشكل منتظم من قِبل هؤلاء العملاء. يجب أن يكون لديك مصدر آخر لمعلومات المنتجات، مثل قاعدة بيانات المنتجات المحلية، ويجب أن تعكس المنتجات في Merchant Center محتوى ذلك المصدر.

لا تستخدِم خلاصات البيانات وContent API لإرسال سلع المنتجات.

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

هل هناك طريقة لاستخدام واجهة برمجة التطبيقات وخلاصات البيانات معًا بأمان؟

يمكنك معالجة خلاصات البيانات باستخدام خدمة خلاصة البيانات في واجهة برمجة التطبيقات. سيسهّل ذلك إدارة خلاصة البيانات على نطاق واسع، ولكن يُرجى العلم أنّه يجب عدم إدراج المنتجات أو تعديلها باستخدام واجهة برمجة التطبيقات بالتزامن مع الخلاصات، لأنّه قد تظهر نتائج غير متوقّعة.

في ما يلي بعض الأمثلة الأخرى على الطرق المقبولة لاستخدام الخلاصات وواجهة برمجة التطبيقات بشكل مشترك:

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

  • استخدام واجهة برمجة التطبيقات لإدارة حساباتك الفرعية (حسابات الخدمة) و/أو إعدادات الشحن والضرائب على مستوى الحساب (Accounttax Service و Shippingsettings Service). هذه ليست من الدوال التي يمكن أن توفّرها خلاصات البيانات، وبالتالي ليس هناك تعارض مع استخدام واجهة برمجة التطبيقات لإدارة هذه الدوال.

كيف أنتقل من استخدام خلاصات البيانات إلى استخدام واجهة برمجة التطبيقات فقط أو العكس؟

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

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

كيف أستهدِف بلدانًا متعددة من خلال المنتجات التي تستخدم Content API for Shopping؟

لاستهداف بلدان متعددة من خلال إعلانات وبيانات منتجات مجانية يتم إرسالها عبر Content API، يجب ضبط بلدان إضافية في خلاصة Content API الأساسية في Merchant Center أو إضافة تلك البلدان الإضافية عبر الحقل shipping في المورد products.

إليك مثال على كيفية تعديل إعدادات الخلاصة الأساسية لـ Content API أدناه.

لمزيد من المعلومات، يُرجى الاطّلاع على المقالة: استهداف إعلانات Shopping والبيانات المجانية في بلدان متعددة.

الحرص على أن تكون مكتبات العملاء محدّثة

إذا كنت تستخدم مكتبة عملاء Google للتفاعل مع Content API، احرص على استخدام مدير الحزم للغة البرمجة التي اخترتها وتأكّد من تحديث إصدار المكتبة. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على دليل المطوّر للّغة التي اخترتها في عيّنات والمكتبات.

يُرجى الحرص على استخدام سمات الوجهات لتحديد المنتجات التي تظهر في برامج التسوّق المختلفة.

تستخدم Content API تلقائيًا الإعدادات التلقائية لخلاصة Content API، كما تم ضبطها في Merchant Center. يمكنك استخدام سمتَي المنتج includedDestinations أو excludedDestinations للتحكّم في المشاركة في البرنامج على مستوى المنتج ضمن خلاصة أو عبر Content API.

إذا تم تفعيل خلاصة واجهة برمجة التطبيقات في برنامج، مثل "الشراء على Google" (المعروف سابقًا باسم Shopping Actions)، ولكنك تريد استبعاد منتجات معيّنة، استخدِم السمة excludedDestinations وحدِّد Shopping Actions كقيمة. سيؤدي هذا الإجراء إلى استبدال إعدادات الخلاصة التلقائية في Merchant Center شرط عدم عرض أي أخطاء، ولن تظهر هذه السلعة بالتحديد في "الشراء على Google" (المعروف سابقًا باسم Shopping Actions). وفي المقابل، إذا لم تكن خلاصتك مفعّلة في برنامج، مثل Shopping، يمكنك تضمين سلع فردية باستخدام السمة includedDestinations وShopping_ads كقيمة، وستظهر السلعة في إعلانات Shopping.

لمزيد من المعلومات حول سمتَي المنتج includedDestinations وexcludedDestinations، يمكنك الاطّلاع على مركز المساعدة.

احرص على تعديل السلع قبل انتهاء صلاحيتها.

في حال عدم تغيّر المنتج قبل انتهاء صلاحيته، أي بعد 30 يومًا من تاريخ آخر تعديل، أو عند تاريخ انتهاء الصلاحية المحدَّد إذا كان تاريخ انتهاء صلاحيته سابقًا، عليك تعديل السلعة لتجنُّب إيقافها. إذا كنت بحاجة إلى تحديث العديد من العناصر، بسبب عدم حدوث أي تغيير أو بسبب عدم إمكانية تتبع وقت آخر تحديث لها، لا تُحدِّث جميع العناصر في الوقت نفسه، بل وزِّع الحمل بالتساوي على مدار عدة أيام.

يجب عدم حذف خلاصة Content API وإلا قد تختفي منتجاتك.

في المرّة الأولى التي تحمِّل فيها منتجًا باستخدام channel:online عبر Content API، ستظهر خلاصة جديدة في Merchant Center بعنوان Content API. في المرّة الأولى التي تحمِّل فيها منتجًا باستخدام channel:local عبر Content API، ستظهر خلاصة جديدة في Merchant Center بعنوان Content API بعنوان فرعي المنتجات المحلّية. يُرجى الحرص على عدم حذف خلاصة Content API المحلية أو على الإنترنت عن طريق الخطأ. بناءً على الخلاصة التي تحذفها، ستتم إزالة المنتجات المتوفرة على الإنترنت أو المنتجات المحلية التي أضفتها إلى Merchant Center عبر Content API.

تجميع طلبات متعددة للخدمة نفسها باستخدام طريقة الدفعة المخصصة

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

لا ترسِل تحديثات متعددة لعنصر واحد في دفعة واحدة.

سيؤدي ذلك إلى نتائج غير متوقّعة بسبب عدم التأكّد من تسلسل التحديثات، ما قد يؤدي إلى حدوث خطأ متعارض.

عدم إرسال تحديثات للعناصر التي لم يتم تغييرها

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

استخدِم الخلاصات التكميلية إذا تغيّرت الأسعار و/أو مدى التوفّر بسرعة.

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

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

حالات استخدام الرمز المميّز لإعادة التحميل

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