שיטות מומלצות לשימוש ב-CSS API
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
במסמך הזה מפורטות כמה שיטות מומלצות לשימוש ב-CSS API. ההמלצות שמופיעות בדף הזה לא מחייבות לשימוש ב-API, אבל הן יכולות לעזור להבהיר חלק מהשימושים המיועדים.
הגדרת הסביבה
כדי להגדיר את סביבת הפיתוח, פועלים לפי השלבים שמפורטים בתיעוד ההפעלה המהירה.
- יצירה של קובץ JSON עם משתמשים והרשאות במסוף Google Cloud
- הפעלת CSS API במסוף Google Cloud
- מוסיפים את המשתמש עם הרשאות אדמין לחשבון ה-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 מיועד לקריאות מקבילות. תגלו שהביצועים של פעולות בודדות יכולים להיות איטיים, אבל הם יהיו מהירים הרבה יותר אם תקראו לאותה פעולה כמה פעמים במקביל. הדרך הכי טובה להשתמש בתכונה הזו היא להשתמש בפונקציונליות האסינכרונית של שפת התכנות.
דוגמאות מכמה שפות תכנות:
אפשר להשתמש בפונקציונליות האסינכרונית של שפת התכנות כדי להוסיף כמה מוצרים בו-זמנית. אין צורך לדאוג לגבי עומס יתר על המערכות שלנו – לשם כך קיימות מגבלות המכסה.
פרטים נוספים זמינים בדף הביצועים.
אימות של מטען ייעודי (payload)
כדי להימנע משגיאות נפוצות, חשוב לוודא שפורמט מטען ה-JSON תקין:
- עיון במסמכי התיעוד הרשמיים: תמיד כדאי לעיין במאמר העזרה העדכני בנושא CSS API כדי לקבל מידע על הגדרות השדות, סוגי הנתונים, המבנה של מטען הייעודי (payload) וסוגי המספור (enum).
- בדיקת מטענים לדוגמה: משווים את המטענים שלכם לדוגמאות הקוד שסיפקנו כדי לזהות אי התאמות.
- סוגי נתונים: חשוב לוודא שאתם משתמשים בסוגי הנתונים הנכונים (למשל, מחרוזות, אובייקטים, מערכים) כפי שמפורט במסמכי התיעוד.
- בדיקה מצטברת: מתחילים עם מטען ייעודי (payload) מינימלי ותקף כדי לאשר קישוריות בסיסית, ומוסיפים בהדרגה עוד מאפיינים.
עדכון מוצר
אחרי שמעלים מוצר, הוא נשאר במערכת שלנו עד שהוא מתעדכן, נמחק או שתוקף שלו פג.
- כדי לעדכן את המוצר כולו, שולחים שוב את הבקשה
InsertCssProductInput
באמצעות אותו raw_provided_id שבו השתמשתם בהתחלה. בשלב הזה, תצטרכו לשלוח את כל נתוני המוצר, גם אם רק חלק מהמאפיינים (למשל רק מחיר או זמינות) השתנו.
- אפשר לעדכן חלקים של מוצר באמצעות שיטת PATCH
UpdateCssProductInput, ציון שם המוצר וגוף JSON שמכיל את הנתונים שרוצים לעדכן במוצר. בניגוד ל-InsertCssProductInput, שבו צריך לספק את כל השדות הרלוונטיים, ב-UpdateCssProductInput צריך לציין רק את השדות שרוצים לשנות.
- אפשר למחוק מוצר באמצעות קריאה ל-
DeleteCssProductInput עם אותו raw_provided_id.
- התוקף של מוצרים פג אוטומטית כחודש אחרי העדכון האחרון.
מצב פעולה רציף
מצב פעולה רציף יכול להיראות כך:
- משתמשים במזהים פנימיים משלכם בתור
raw_provided_id.
- להעלות מחדש את כל המוצרים בלוח זמנים קבוע, למשל שבועי. כך תבטיחו שהמוצרים הפעילים לא יפוגו.
- כדאי לעדכן מוצרים ספציפיים ברגע שאתם מקבלים מהמוכרים את הנתונים המעודכנים.
- אם אתם לא יכולים להגיב לשינויים באופן מיידי, כדאי למצוא את כל המוצרים שהשתנו בתדירות גבוהה (אולי כל שעה) ולהעלות מחדש רק את המוצרים האלה.
- למוצרים שכבר לא זמינים, אפשר להשתמש בפקודה delete או להגדיר את מספר המוצרים הזמינים ל-0.
- אל תשלחו לנו מוצרים שלא השתנו בתדירות גבוהה. השיחות האלה ייספרו במכסת ה-API שלכם. מספיק לעדכן את הנתונים פעם בשבוע.
בחירת המוצר המרכזי בדף
המוצר המרכזי לא חייב להיות המוצר הראשון או הזול ביותר באתר, אבל הוא צריך להיות מוצג בצורה בולטת. אפשר להשתמש בזה במקרים שבהם המוצר המוביל משתנה במהירות: במקרה כזה, אפשר לבחור מוצר אחר שיותר יציב.
בדיקה חוזרת של המסמך מדי פעם
קיבלנו משוב על שיפור ה-API הזה, ואנחנו עובדים על הוספת חלק מהשיפורים האלה. הדף הזה יתעדכן כשיהיו תכונות חדשות שיפשטו את השימוש ב-CSS API.
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-13 (שעון UTC).
[[["התוכן קל להבנה","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 (שעון UTC)."],[[["\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."]]
