שיטות מומלצות לשימוש ב-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.

שימוש ב-Async לשיפור הביצועים

ממשק 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.

הקודם
מדריך למתחילים
הבא
מיפויי קוד