بهترین روش های CSS API
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این سند برخی از بهترین شیوه‌های استفاده از CSS API را شرح می‌دهد. توصیه های ارائه شده در این صفحه برای استفاده از API اجباری نیست، اما ممکن است به روشن شدن برخی از کاربردهای مورد نظر کمک کند.
محیط خود را تنظیم کنید
برای راه‌اندازی محیط توسعه خود، مراحل داده‌شده در اسناد شروع سریع را دنبال کنید.
- یک کاربر و یک فایل JSON مجوزها در Google Cloud Console ایجاد کنید
- CSS API را در Google Cloud Console فعال کنید
- آن کاربر را با مجوزهای Admin به حساب CSS خود اضافه کنید (گروه CSS یا دامنه CSS)
- بررسی کنید که از دامنه OAuth صحیح استفاده می کنید:
https://www.googleapis.com/auth/content
کتابخانه های مشتری اکنون در مخازن استاندارد اکثر زبان های برنامه نویسی قرار دارند. می توانید لیستی از آنها را در صفحه کتابخانه مشتری ما پیدا کنید.
از شناسه های صحیح استفاده کنید
از شناسه های صحیح با نقاط پایانی API صحیح استفاده کنید:
- 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 فراخوانی شده‌اند) را فهرست می‌کند. بنابراین یک روش خوب برای آزمایش اینکه آیا همه چیز به درستی تنظیم شده است یا خیر.
درج / لیست / به روز رسانی / حذف یک محصول
هنگامی که متوجه شدید که خود API کار می کند، سعی کنید محصولی را اضافه کنید. مطمئن شوید که از یک raw_provided_id استفاده می کنید که به خاطر دارید.
- یک محصول آزمایشی را با استفاده از InsertCssProductInput وارد کنید. اگر به کمک نیاز دارید که کدام ویژگی ها را ارسال کنید، کد نمونه داریم.
- همه محصولات خود را با استفاده از ListCssProducts فهرست کنید. قبل از نمایش محصول پس از قرار دادن، تاخیر کمی در پردازش وجود دارد، بنابراین اگر آن را مشاهده نکردید، پس از چند ثانیه دوباره امتحان کنید.
- یک محصول را با استفاده از UpdateCssProductInput با استفاده از
cssproductinput.name خود به روز کنید. شما باید فقط ویژگی های مورد نیاز برای به روز رسانی را ارسال کنید. به نمونه کد اینجا مراجعه کنید. - محصول آزمایشی را با استفاده از DeleteCssProductInput حذف کنید. شما باید از
raw_provided_id استفاده کنید.
CSS API برای تماس های موازی طراحی شده است. متوجه خواهید شد که عملکرد یک عملیات می تواند کند باشد، اما زمانی که یک عملیات را چندین بار به صورت موازی فراخوانی کنید، بسیار سریعتر خواهد بود. بهترین راه برای استفاده از این ویژگی، استفاده از قابلیت همگام زبان برنامه نویسی خود است.
نمونه هایی از برخی از زبان های برنامه نویسی:
قابلیت Async زبان برنامه نویسی خود را پیدا کنید و از آن برای درج چندین محصول به طور همزمان استفاده کنید. لازم نیست نگران بارگذاری بیش از حد سیستم‌های ما باشید - محدودیت‌های سهمیه برای این کار است.
جزئیات بیشتر را می توانید در صفحه عملکرد ما پیدا کنید.
بارهای خود را اعتبارسنجی کنید
برای جلوگیری از خطاهای رایج، مطمئن شوید که بارهای JSON شما به درستی قالب بندی شده اند:
- با اسناد رسمی مشورت کنید: همیشه به آخرین مرجع CSS API برای تعاریف فیلدها، enums، انواع داده ها و ساختار محموله مراجعه کنید.
- بررسی Sample Payloads: محموله های خود را با نمونه کد ارائه شده مقایسه کنید تا مغایرت ها را شناسایی کنید.
- انواع داده ها: مطمئن شوید که از انواع داده های صحیح (مانند رشته ها، اشیاء، آرایه ها) همانطور که در مستندات مشخص شده است استفاده می کنید.
- تست افزایشی: با حداقل بارهای معتبر شروع کنید تا اتصال اولیه را تأیید کنید و به تدریج ویژگی های بیشتری را اضافه کنید.
یک محصول را به روز کنید
هنگامی که یک محصول آپلود شد، تا زمانی که به روز شود، حذف شود یا منقضی شود، در سیستم ما می ماند.
- می توانید با ارسال مجدد درخواست
InsertCssProductInput ، با استفاده از همان raw_provided_id که در ابتدا استفاده می کردید، محصول کامل را به روز کنید. در حال حاضر، باید اطلاعات کامل محصول را ارسال کنید، حتی اگر فقط برخی از ویژگی ها (شاید فقط قیمت/در دسترس بودن) تغییر کرده باشند. - می‌توانید بخش‌هایی از یک محصول را با استفاده از روش PATCH
UpdateCssProductInput ، با مشخص کردن نام محصول و بدنه JSON حاوی داده‌هایی که می‌خواهید برای محصول به‌روزرسانی کنید، به‌روزرسانی کنید. برخلاف InsertCssProductInput ، که نیاز به ارائه تمام فیلدهای قابل اجرا دارد، UpdateCssProductInput فقط از شما می خواهد که فیلدهایی را که می خواهید تغییر دهید مشخص کنید. - می‌توانید با تماس با
DeleteCssProductInput با همان raw_provided_id یک محصول را حذف کنید. - محصولات تقریباً یک ماه پس از آخرین به روز رسانی به طور خودکار منقضی می شوند.
حالت کار مداوم
یک حالت کار مداوم می تواند به شکل زیر باشد:
- از شناسه های داخلی خود به عنوان
raw_provided_id استفاده کنید. - همه محصولات را در یک برنامه منظم، شاید به صورت هفتگی، دوباره آپلود کنید. این تضمین می کند که محصولات فعال منقضی نمی شوند.
- به محض دریافت داده های تغییر یافته از بازرگانان خود، تک تک محصولات را به روز کنید.
- اگر نمی‌توانید فوراً به تغییرات واکنش نشان دهید، همه محصولات تغییر یافته را مرتباً (شاید ساعتی) پیدا کنید و فقط آن محصولات را دوباره آپلود کنید.
- برای محصولاتی که دیگر در دسترس نیستند، می‌توانید از حذف تماس استفاده کنید یا تعداد پیشنهادات موجود را روی 0 تنظیم کنید.
- محصولات بدون تغییر را مرتبا برای ما ارسال نکنید. این تماس‌ها جزو سهمیه API شما محسوب می‌شوند. یک تجدید هفتگی کافی است.
انتخاب پیشنهاد سرفصل
پیشنهاد سرفصل لزوماً نباید بهترین پیشنهاد یا ارزان ترین پیشنهاد در سایت شما باشد، اما باید به طور برجسته نشان داده شود. می توانید از این برای مواردی استفاده کنید که پیشنهاد برتر شما به سرعت در حال تغییر است: در اینجا می توانید پیشنهاد دیگری را انتخاب کنید که پایدارتر باشد.
هر چند وقت یکبار این سند را دوباره بررسی کنید
ما بازخوردهایی در مورد چگونگی بهبود این API دریافت کرده‌ایم و در حال کار روی ارائه برخی از این بهبودها هستیم. این صفحه زمانی به روز می شود که ویژگی های جدیدی در دسترس داشته باشیم که استفاده از CSS API را ساده می کند.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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."]]
