أفضل ممارسات واجهة برمجة تطبيقات CSS
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يوضّح هذا المستند بعضًا من أفضل الممارسات المتعلّقة باستخدام 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.
تم تصميم CSS API لإجراء طلبات متوازية. ستلاحظ أنّ أداء العمليات الفردية قد يكون بطيئًا، ولكنّه سيكون أسرع بكثير عند استدعاء العملية نفسها عدة مرات بشكل متوازٍ. أفضل طريقة لاستخدام هذه الميزة هي الاستفادة من وظيفة async في لغة البرمجة.
أمثلة من بعض لغات البرمجة:
ابحث عن وظيفة Async في لغة البرمجة التي تستخدمها واستخدِمها لإدراج منتجات متعدّدة في الوقت نفسه. لا داعي للقلق بشأن إرهاق أنظمتنا، فهذا هو الغرض من حدود الحصة.
يمكنك الاطّلاع على مزيد من التفاصيل في صفحة الأداء.
التحقّق من صحة الحِزم
لتجنُّب الأخطاء الشائعة، تحقَّق من صحة تنسيق حمولات JSON باتّباع الخطوات التالية:
- الرجوع إلى المستندات الرسمية: يُرجى الرجوع دائمًا إلى أحدث مرجع CSS API للاطّلاع على تعريفات الحقول والقيم الثابتة وأنواع البيانات وبنية الحمولة.
- مراجعة عيّنات الحمولة: قارِن بين الحمولة الخاصة بك وعيّنات الرموز المقدَّمة لتحديد أي اختلافات.
- أنواع البيانات: تأكَّد من استخدام أنواع البيانات الصحيحة (مثل السلاسل والأغراض والمصفوفات) كما هو محدّد في المستندات.
- الاختبار بشكل تدريجي: ابدأ بأقل عدد من الحِزم الصالحة للتأكّد من إمكانية الاتصال الأساسية، ثم أضِف المزيد من السمات تدريجيًا.
تعديل منتج
بعد تحميل منتج، سيبقى في نظامنا إلى أن يتم تعديله أو حذفه أو تنتهي مدة صلاحيته.
- يمكنك تعديل المنتج الكامل عن طريق إرسال طلب
InsertCssProductInput
مرة أخرى باستخدام raw_provided_id نفسه الذي استخدمته في البداية. في الوقت الحالي، عليك إرسال بيانات المنتج الكاملة، حتى إذا تم تغيير بعض السمات فقط (ربما السعر أو التوفّر فقط).
- يمكنك تعديل أجزاء من منتج باستخدام طريقة PATCH
UpdateCssProductInput، وتحديد اسم المنتج، ونص JSON يتضمّن
البيانات التي تريد تعديلها للمنتج. على عكس InsertCssProductInput الذي يتطلّب توفير جميع الحقول السارية، لا يتطلّب UpdateCssProductInput سوى تحديد الحقول التي تريد تغييرها.
- يمكنك حذف منتج من خلال استدعاء
DeleteCssProductInput باستخدام raw_provided_id نفسه.
- تنتهي صلاحية المنتجات تلقائيًا بعد شهر واحد تقريبًا من آخر تحديث.
وضع التشغيل المستمر
قد يبدو وضع التشغيل المستمر على النحو التالي:
- استخدِم المعرّفات الداخلية الخاصة بك كـ
raw_provided_id.
- أعِد تحميل جميع المنتجات وفقًا لجدول زمني منتظم، ربما أسبوعيًا. سيضمن ذلك عدم انتهاء صلاحية المنتجات النشطة.
- عدِّل المنتجات الفردية فور تلقّي البيانات المعدَّلة من التجّار.
- إذا لم تتمكّن من التفاعل مع التغييرات على الفور، ابحث عن جميع المنتجات التي تم تغييرها بشكل متكرر (ربما كل ساعة) وأعِد تحميل هذه المنتجات فقط.
- بالنسبة إلى المنتجات التي لم تعُد متوفّرة، يمكنك إما استخدام
طلب الحذف أو ضبط عدد العروض المتوفّرة على 0.
- لا ترسِل إلينا منتجات لم تتغيّر بشكل متكرّر. وسيتم احتساب هذه الطلبات ضِمن حصتك من واجهة برمجة التطبيقات. ويكفي إجراء عملية إعادة تحميل أسبوعية.
اختيار العرض الرئيسي
ليس من الضروري أن يكون المنتج الرئيسي في الصفحة هو المنتج الأفضل أو الأرخص على موقعك الإلكتروني، ولكن يجب أن يكون معروضًا بشكل بارز. يمكنك استخدام هذه السمة في الحالات التي يتغيّر فيها العرض الترويجي الأبرز بسرعة، إذ يمكنك اختيار عرض ترويجي آخر أكثر استقرارًا.
إعادة فحص هذا المستند من حين لآخر
تلقّينا ملاحظات حول كيفية تحسين واجهة برمجة التطبيقات هذه، ونعمل على توفير بعض هذه التحسينات. سيتم تعديل هذه الصفحة عندما تتوفّر ميزات جديدة تسهّل استخدام CSS API.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-13 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-13 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThis document outlines best practices for utilizing the CSS API, including setup, testing methods, performance enhancement, product management, and headline offer selection.\u003c/p\u003e\n"],["\u003cp\u003eOptimize API performance by using asynchronous calls for parallel operations, especially for inserting multiple products simultaneously.\u003c/p\u003e\n"],["\u003cp\u003eMaintain product data by regularly re-uploading all products, updating individual products as needed, and managing product expiration or deletion.\u003c/p\u003e\n"],["\u003cp\u003eThe headline offer can be strategically chosen for prominence and stability, even if it's not the cheapest or top offer on your site.\u003c/p\u003e\n"],["\u003cp\u003eStay informed about API updates and improvements by revisiting this document periodically for new features and simplified usage guidelines.\u003c/p\u003e\n"]]],[],null,["# CSS API Best Practices\n\nThis document describes some of the best practices around using the CSS API. The\nadvice given on this page is not mandatory to use the API, but may help clarify\nsome of the intended use.\n\nSetup up your environment\n-------------------------\n\nTo setup your development environment, follow the steps given from the\n[Quickstart documentation](/comparison-shopping-services/api/guides/quickstart).\n\n- Generate a user and a permissions JSON file on the Google Cloud Console\n- Enable the CSS API in the Google Cloud Console\n- Add that user with Admin permissions to your CSS Account (CSS Group or CSS Domain)\n- Verify you are using the correct OAuth scope: `https://www.googleapis.com/auth/content`\n\nClient libraries are now in the standard repositories for most programming\nlanguage. You can find a list of them on our\n[client library](/comparison-shopping-services/api/client-libraries) page.\n\nUse correct IDs\n---------------\n\nUse the correct IDs with the correct API endpoints:\n\n- **CSS API (`css.googleapis.com`):** Use the **CSS Domain ID** when interacting with CSS products (e.g., `accounts/{cssDomainId}/cssProductInputs:insert`).\n- **Merchant API (`merchantapi.googleapis.com`):** Use the Merchant API for standard merchant products.\n\nMixing these up will lead to errors. Refer to the\n[CSS API Overview](/comparison-shopping-services/api/overview) for more details.\n\nGood methods to get started\n---------------------------\n\nWe recommend testing with the following methods:\n\n### ListChildAccounts\n\n[ListChildAccounts](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.AccountsService.ListChildAccounts)\nis a read-only call that lists all of your CSS Domains (if called for a\nCSS Group) or your Merchants (if called for a CSS Domain). It is therefore a\ngood method to test if everything is setup correctly.\n\n### Insert/List/Update/Delete a product\n\nOnce you know that the API itself works, try adding a product. Make sure you use\na `raw_provided_id` that you remember.\n\n- Insert a test product using [InsertCssProductInput](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductInputsService.InsertCssProductInput). We have [sample code](/comparison-shopping-services/api/code-samples/cssproducts/insert-css-product-input) if you need help on which attributes to send.\n- List all of your products using [ListCssProducts](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductsService.ListCssProducts). There is a small processing delay before a product shows up after insertion, so if you don't see it, try again after a few seconds.\n- Update a single product using [UpdateCssProductInput](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductInputsService.UpdateCssProductInput) using your `cssproductinput.name`. You need to send only the attributes required to be updated. Refer to [sample code](/comparison-shopping-services/api/code-samples/cssproducts/update-css-product-input) here.\n- Delete the test product using [DeleteCssProductInput](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductInputsService.DeleteCssProductInput). You will need to use the `raw_provided_id`.\n\nUse Async to improve performance\n--------------------------------\n\nThe CSS API is designed for parallel calls. You will find that the performance\nof single operations can be slow, but will be much faster when calling the same\noperation multiple times in parallel. The best way to use this feature is to use\nthe async functionality of your programming language.\n\nExamples from some programming languages:\n\n- For Java, use [insertCssProductInputCallable().futureCall()](https://cloud.google.com/java/docs/reference/google-shopping-css/latest/com.google.shopping.css.v1.CssProductInputsServiceClient#com_google_shopping_css_v1_CssProductInputsServiceClient_insertCssProductInputCallable__)\n- For Python, use [CssProductInputsServiceAsyncClient](https://googleapis.dev/python/google-shopping-css/latest/css_v1/css_product_inputs_service.html)\n- For C#, use [InsertCssProductInputAsync](https://googleapis.dev/dotnet/Google.Shopping.Css.V1/latest/api/Google.Shopping.Css.V1.CssProductInputsService.CssProductInputsServiceClient.html#Google_Shopping_Css_V1_CssProductInputsService_CssProductInputsServiceClient_InsertCssProductInputAsync_Google_Shopping_Css_V1_InsertCssProductInputRequest_Grpc_Core_CallOptions_)\n\nFind and use the Async functionality of your programming language to insert\nmultiple products at the same time. You don't need to worry about overloading\nour systems - this is what the\n[quota limits](/comparison-shopping-services/api/guides/limits) are for.\n\nMore details can be found on our [performance\npage](/comparison-shopping-services/api/guides/performance).\n\nValidate Your Payloads\n----------------------\n\nTo avoid common errors, verify your JSON payloads are correctly formatted:\n\n- **Consult Official Documentation:** Always refer to the latest [CSS API reference](/comparison-shopping-services/api/reference/rest) for field definitions, enums, data types, and payload structure.\n- **Review Sample Payloads:** Compare your payloads with the provided [code samples](/comparison-shopping-services/api/code-samples) to identify discrepancies.\n- **Data Types:** Make sure you are using the correct data types (e.g., strings, objects, arrays) as specified in the documentation.\n- **Test Incrementally:** Start with minimal valid payloads to confirm basic connectivity and gradually add more attributes.\n\nUpdate a product\n----------------\n\nOnce a product is uploaded, it will stay in our system until it is either\nupdated, deleted, or expired.\n\n- You can update the full product by sending the `InsertCssProductInput` request again, using the same `raw_provided_id` you used initially. For now, you will need to send the full product data, even if only some attributes (maybe only price/availablibilty) have changed.\n- You can update parts of a product, using PATCH method `UpdateCssProductInput`, specifying product name,and a JSON body containing the data you would like to update for the product. Unlike `InsertCssProductInput`, that requires all applicable fields to be provided, `UpdateCssProductInput` only requires you to specify the fields you would like to change.\n- You can delete a product by calling `DeleteCssProductInput` with the same `raw_provided_id`.\n- Products expire automatically approximately one month after the last update.\n\nContinuous operation mode\n-------------------------\n\nA continuous operation mode could look like the following:\n\n- Use your own internal IDs as `raw_provided_id`.\n- Re-upload all products on a regular schedule, maybe weekly. This will ensure that active products don't expire.\n- Update individual products as soon as you get the changed data from your merchants.\n - If you can't react to changes immediately, find all changed products frequently (maybe hourly) and re-upload only those products.\n - For products which are no longer available, you can either use the delete call or set the number of available offers to 0.\n - Don't send us unchanged products frequently. These calls would count against your API quota. A weekly refresh is sufficient.\n\nHeadline offer selection\n------------------------\n\nThe headline offer does not necessarily need to be the top offer or the\ncheapest offer on your site, but it does need to be featured prominently. You\ncan use this for cases where your top offer is changing fast: Here you could\nselect another offer which is more stable.\n\nRe-Check this document every once in a while\n--------------------------------------------\n\nWe have received feedback on how to improve this API, and are working on making\nsome of these improvements available. This page will be updated when we have new\nfeatures available that will simplify the usage of the CSS API."]]
