يوضّح هذا المستند بعضًا من أفضل الممارسات المتعلّقة باستخدام CSS API. إنّ النصائح الواردة في هذه الصفحة ليست إلزامية لاستخدام واجهة برمجة التطبيقات، ولكنها قد تساعد في توضيح بعض الاستخدامات المقصودة.
إعداد البيئة
لإعداد بيئة التطوير، اتّبِع الخطوات الواردة في مستندات البدء السريع.
- إنشاء ملف JSON للمستخدمين والأذونات على Google Cloud Console
- تفعيل CSS API في Google Cloud Console
- أضِف هذا المستخدم مع أذونات المشرف إلى حسابك على CSS (مجموعة CSS أو نطاق CSS).
- تأكَّد من استخدام نطاق OAuth الصحيح:
https://www.googleapis.com/auth/content
تتوفّر مكتبات البرامج الآن في المستودعات العادية لمعظم لغات البرمجة. يمكنك العثور على قائمة بها في صفحة مكتبة البرامج الخاصة بنا.
استخدام المعرّفات الصحيحة
استخدِم المعرّفات الصحيحة مع نقاط نهاية واجهة برمجة التطبيقات الصحيحة:
- واجهة CSS API (
css.googleapis.com): استخدِم رقم تعريف نطاق CSS عند التفاعل مع منتجات CSS (مثلaccounts/{cssDomainId}/cssProductInputs:insert). - Merchant API (
merchantapi.googleapis.com): استخدِم Merchant API للمنتجات العادية الخاصة بالتجّار.
سيؤدي الخلط بينهما إلى حدوث أخطاء. لمزيد من التفاصيل، يُرجى الاطّلاع على نظرة عامة على واجهة CSS API.
طُرق جيدة للبدء
ننصحك بإجراء الاختبار باستخدام الطرق التالية:
ListChildAccounts
ListChildAccounts هي عملية قراءة فقط تعرض جميع نطاقات CSS (في حال طلبها لمجموعة CSS) أو جميع التجّار (في حال طلبها لنطاق CSS). لذلك، تُعدّ هذه الطريقة جيدة لاختبار ما إذا تم إعداد كل شيء بشكل صحيح.
إدراج منتج أو إدراجه في قائمة أو تعديله أو حذفه
بعد التأكّد من أنّ واجهة برمجة التطبيقات تعمل، حاوِل إضافة منتج. تأكَّد من استخدام raw_provided_id تتذكّرها.
- أدرِج منتجًا تجريبيًا باستخدام InsertCssProductInput. لدينا رمز نموذجي إذا كنت بحاجة إلى مساعدة بشأن السمات التي يجب إرسالها.
- أدرِج جميع منتجاتك باستخدام ListCssProducts. يحدث تأخير بسيط في المعالجة قبل ظهور المنتج بعد إدراجه، لذا إذا لم يظهر، أعِد المحاولة بعد بضع ثوانٍ.
- عدِّل منتجًا واحدًا باستخدام
UpdateCssProductInput
باستخدام
cssproductinput.name. عليك إرسال السمات المطلوب تعديلها فقط. يمكنك الرجوع إلى الرمز النموذجي هنا. - احذف المنتج التجريبي باستخدام
DeleteCssProductInput.
عليك استخدام
raw_provided_id.
استخدام Async لتحسين الأداء
تم تصميم CSS API لإجراء طلبات متوازية. ستلاحظ أنّ أداء العمليات الفردية قد يكون بطيئًا، ولكنّه سيكون أسرع بكثير عند استدعاء العملية نفسها عدة مرات بشكل متوازٍ. أفضل طريقة لاستخدام هذه الميزة هي الاستفادة من وظيفة async في لغة البرمجة.
أمثلة من بعض لغات البرمجة:
- بالنسبة إلى Java، استخدِم insertCssProductInputCallable().futureCall()
- بالنسبة إلى Python، استخدِم CssProductInputsServiceAsyncClient
- بالنسبة إلى C#، استخدِم InsertCssProductInputAsync
ابحث عن وظيفة Async في لغة البرمجة التي تستخدمها واستخدِمها لإدراج منتجات متعدّدة في الوقت نفسه. لا داعي للقلق بشأن إرهاق أنظمتنا، فهذا هو الغرض من حدود الحصة.
يمكنك الاطّلاع على مزيد من التفاصيل في صفحة الأداء.
التحقّق من صحة الحِزم
لتجنُّب الأخطاء الشائعة، تحقَّق من صحة تنسيق حمولات JSON باتّباع الخطوات التالية:
- الرجوع إلى المستندات الرسمية: يُرجى الرجوع دائمًا إلى أحدث مرجع CSS API للاطّلاع على تعريفات الحقول والقيم الثابتة وأنواع البيانات وبنية الحمولة.
- مراجعة عيّنات الحمولة: قارِن بين الحمولة الخاصة بك وعيّنات الرموز المقدَّمة لتحديد أي اختلافات.
- أنواع البيانات: تأكَّد من استخدام أنواع البيانات الصحيحة (مثل السلاسل والأغراض والمصفوفات) كما هو محدّد في المستندات.
- الاختبار بشكل تدريجي: ابدأ بأقل عدد من الحِزم الصالحة للتأكّد من إمكانية الاتصال الأساسية، ثم أضِف المزيد من السمات تدريجيًا.
تعديل منتج
بعد تحميل منتج، سيبقى في نظامنا إلى أن يتم تعديله أو حذفه أو تنتهي مدة صلاحيته.
- يمكنك تعديل المنتج الكامل عن طريق إرسال طلب
InsertCssProductInputمرة أخرى باستخدامraw_provided_idنفسه الذي استخدمته في البداية. في الوقت الحالي، عليك إرسال بيانات المنتج الكاملة، حتى إذا تم تغيير بعض السمات فقط (ربما السعر أو التوفّر فقط). - يمكنك تعديل أجزاء من منتج باستخدام طريقة PATCH
UpdateCssProductInput، وتحديد اسم المنتج، ونص JSON يتضمّن البيانات التي تريد تعديلها للمنتج. على عكسInsertCssProductInputالذي يتطلّب توفير جميع الحقول السارية، لا يتطلّبUpdateCssProductInputسوى تحديد الحقول التي تريد تغييرها. - يمكنك حذف منتج من خلال استدعاء
DeleteCssProductInputباستخدامraw_provided_idنفسه. - تنتهي صلاحية المنتجات تلقائيًا بعد شهر واحد تقريبًا من آخر تحديث.
وضع التشغيل المستمر
قد يبدو وضع التشغيل المستمر على النحو التالي:
- استخدِم المعرّفات الداخلية الخاصة بك كـ
raw_provided_id. - أعِد تحميل جميع المنتجات وفقًا لجدول زمني منتظم، ربما أسبوعيًا. سيضمن ذلك عدم انتهاء صلاحية المنتجات النشطة.
- عدِّل المنتجات الفردية فور تلقّي البيانات المعدَّلة من التجّار.
- إذا لم تتمكّن من التفاعل مع التغييرات على الفور، ابحث عن جميع المنتجات التي تم تغييرها بشكل متكرر (ربما كل ساعة) وأعِد تحميل هذه المنتجات فقط.
- بالنسبة إلى المنتجات التي لم تعُد متوفّرة، يمكنك إما استخدام طلب الحذف أو ضبط عدد العروض المتوفّرة على 0.
- لا ترسِل إلينا منتجات لم تتغيّر بشكل متكرّر. وسيتم احتساب هذه الطلبات ضِمن حصتك من واجهة برمجة التطبيقات. ويكفي إجراء عملية إعادة تحميل أسبوعية.
اختيار العرض الرئيسي
ليس من الضروري أن يكون المنتج الرئيسي في الصفحة هو المنتج الأفضل أو الأرخص على موقعك الإلكتروني، ولكن يجب أن يكون معروضًا بشكل بارز. يمكنك استخدام هذه السمة في الحالات التي يتغيّر فيها العرض الترويجي الأبرز بسرعة، إذ يمكنك اختيار عرض ترويجي آخر أكثر استقرارًا.
إعادة فحص هذا المستند من حين لآخر
تلقّينا ملاحظات حول كيفية تحسين واجهة برمجة التطبيقات هذه، ونعمل على توفير بعض هذه التحسينات. سيتم تعديل هذه الصفحة عندما تتوفّر ميزات جديدة تسهّل استخدام CSS API.