בחירה בין פידים של קבצים לבין Merchant API

אתם יכולים להעלות נתוני מוצרים ל-Merchant Center באמצעות פידים מבוססי-קובץ, Merchant API או שילוב של שניהם:

  • פידים של מוצרים שמבוססים על קבצים: אפשר להעלות קובצי CSV,‏ TSV או XML באמצעות SFTP,‏ Google Cloud Storage,‏ Google Sheets או שליפות מתוזמנות.
  • ‫Merchant API: אתם יכולים לשלוח בקשות פרוגרמטיות ישירות מהקצה העורפי שלכם כדי לבצע עדכונים מצטברים כשנתוני המוצרים משתנים, לצד סנכרונים תקופתיים של הקטלוג המלא.

במדריך הזה אנחנו משווים בין שתי הגישות, מסבירים מתי כדאי להשתמש בכל אחת מהן (או בשתיהן יחד) ומספקים מדריך מפורט להעברת נתונים למקרה שתחליטו להעביר חלק מהמוצרים או את כולם מפידים של קבצים ל-API.

בחירת הגישה למקור הנתונים

כדי להחליט אם להשתמש ב-Merchant API, בפידים של קבצים או בהגדרה משולבת, כדאי לבדוק את התנודתיות של הקטלוג, את ארכיטקטורת הקצה העורפי ואת תהליכי העבודה התפעוליים.

מתי כדאי להשתמש ב-Merchant API

כדאי להשתמש במקור נתונים ראשי של API אם:

  • שילוב פרוגרמטי ישיר: אתם מעדיפים להפעיל API ישירות מה-backend במקום ליצור קבצים ולנהל צינורות עיבוד נתונים להעברת קבצים (כמו SFTP או Google Cloud Storage).
  • תנודתיות גבוהה במחירים ובמלאי: המחירים או רמות המלאי של המוצרים משתנים לעיתים קרובות במהלך היום.
  • עדכונים מיידיים כשהנתונים משתנים: אתם רוצים לשלוח ל-Google שינויים במוצרים ברגע שהם מתרחשים בקצה העורפי, במקום לחכות ליצירה ולהעלאה הבאות של הקובץ המתוזמן.
  • עדכונים מצטברים של הקטלוג: אתם רוצים להוסיף, לעדכן או למחוק מוצרים ספציפיים כשהם משתנים, בלי להעלות מחדש את כל הקטלוג בכל פעם.
  • עדכונים חלקיים של מאפיינים: אתם רוצים לעדכן שדות ספציפיים של מוצר (כמו price או availability באמצעות productInputs.patch) בלי לשלוח מחדש את כל המטען הייעודי (payload) של המוצר.

מתי כדאי להשתמש בפידים של קבצים

כדאי להשתמש במקור נתונים ראשי מבוסס-קובץ אם:

  • קטלוג סטטי: נתוני המוצרים משתנים לעיתים רחוקות (לדוגמה, פעם ביום או פחות).
  • קצה עורפי של תמונת מצב בלבד ללא מעקב אחר שינויים: הקצה העורפי שלכם מייצא רק תמונות מצב מלאות של הקטלוג, ולא יכול לעקוב אחר שינויים ברמת הפריט או מחיקות מפורשות של מוצרים.
  • תהליכי עבודה שמבוססים על גיליונות אלקטרוניים: צוותים שאינם צוותי הנדסה אוספים או משנים נתוני מוצרים ישירות בקובצי Google Sheets או CSV.
  • תפעול פשוט: אתם מעדיפים לייצא קבצים לפי לוח זמנים, כך ש-Merchant Center יטפל באחזור ובעיבוד של תמונת המצב, במקום להפעיל שילוב API עם קצב בקשות, טיפול בניסיונות חוזרים וסנכרון תקופתי של הקטלוג המלא.

מתי כדאי להשתמש בשניהם

אתם יכולים לשלב פידים של קבצים ו-Merchant API באותו חשבון Merchant Center בתרחישים הבאים:

  • קטלוגים מפוצלים של מוצרים: אתם משתמשים ב-Merchant API בשביל מוצרים שמשתנים במהירות (כמו מבצעים לזמן מוגבל או מלאי עם תחלופה גבוהה) ובפידים של קבצים בשביל פלחים סטטיים של הקטלוג או קווי מוצרים נפרדים. ודאו שכל מוצר מועלה רק על ידי מקור נתונים ראשי אחד (ראו שימוש מקביל ובעלות על מקור נתונים ראשי).
  • מקור נתונים ראשי של API עם פידים משלימים שמבוססים על קבצים: אתם מנהלים את נתוני המוצרים העיקריים באמצעות מקור נתונים ראשי של API, וצוותים שאינם צוותי הנדסה או שותפי צד שלישי מספקים מאפיינים נוספים באמצעות פידים משלימים שמבוססים על קבצים (כמו קובצי Google Sheets או CSV) בשילוב עם כללי מאפיינים, או להיפך.
  • העברה חלקית או הדרגתית: אתם מעבירים שווקים, קטגוריות או חשבונות משנה ספציפיים ל-API, ומשאירים את שאר הקטלוג בפידים של קבצים.

אם אתם מחליטים להעביר חלק מהמוצרים או את כולם מפידים של קבצים אל Merchant API, אתם יכולים לפעול לפי המדריך המפורט להעברת נתונים.

הבדלים מרכזיים בארכיטקטורה

יש הבדל בין פידים של קבצים לבין Merchant API מבוסס-דחיפה באופן שבו Google מעבדת ומנהלת את נתוני המוצרים:

קונספט פידים של קבצים Merchant API
מודל השילוב העברת קובץ אופליין: אתם מייצאים את הקטלוג לקובץ ומעבירים אותו באמצעות SFTP,‏ Google Cloud Storage,‏ Google Sheets או שליפות מתוזמנות. שילוב פרוגרמטי ישיר: הבק-אנד שולח בקשות ישירות לנקודת קצה ל-API.
רמת הפירוט של המוטציה עיבוד בכמות גדולה: כדי לשנות פריט אחד, בדרך כלל צריך לעבד מחדש את הקובץ כולו. עסקאות פרטניות: אתם יכולים להוסיף, לתקן או למחוק רק את המוצרים שהשתנו.
תזמון הסנכרון סנכרון באצווה: השינויים ממתינים בקצה העורפי עד למחזור הבא של ייצוא והעברת קבצים. קריאות מיידיות או מתוזמנות: אתם יכולים לשלוח שינויים מצטברים מיד כשהם מתרחשים, לצד סנכרונים מלאים תקופתיים.
התנהגות המחיקה משתמע (תמונת מצב): כל קובץ הוא תמונת מצב מלאה. הסרת שורה מהקובץ הראשי מוחקת את המוצר. מפורש: אין קונספט של תמונת מצב. צריך להפעיל את productInputs.delete כדי להסיר מוצר שהייצור שלו הופסק.
ייצוג משאבים מצב יחיד: השורות בקובץ מייצגות את הקלט הגולמי. הפרדה בין נתונים גולמיים למעובדים: ה-API מפצל את הנתונים ל-ProductInput (הקלט הגולמי) ול-Product (המצב המעובד הסופי).
כללי מאפיינים (פיד) הכללים מוחלים על עמודות הקובץ הגולמי בממשק המשתמש של Merchant Center. נתמך בממשק המשתמש של Merchant Center. חובה כשממזגים נתוני API עם קבצים משלימים של צד שלישי. אופציונלי לטרנספורמציות של מקור יחיד אם הן מטופלות בקצה העורפי.

שימוש מקביל ובעלות על מקור הנתונים הראשי ("העדכון האחרון קובע")

אפשר להשתמש גם בפידים של קבצים וגם ב-API באותו חשבון Merchant Center, אבל אנחנו ממליצים מאוד להשתמש רק בשיטה אחת כדי להוסיף מוצר מסוים.

מערכת Merchant Center פועלת לפי המודל "העדכון האחרון קובע". מקור הנתונים הראשי (API או פיד קבצים) שדרכו נשלחה ההוספה האחרונה של המוצר מקבל בעלות ראשית על נתוני המוצר:

  • כשהמוצר שייך למקור נתונים מסוג קובץ: אם לא תכללו את המוצר בהעלאת קובץ הבאה, הוא יימחק באופן משתמע ויוסר מ-Merchant Center.
  • כשהמוצר משויך למקור נתוני ה-API: אם תשמיטו את המוצר מהקובץ שאתם מעלים, זה לא ישפיע על המוצר כי הוא כבר לא משויך לפיד הקובץ. כדי להסיר אותו, צריך להתקשר למספר accounts.productInputs.delete.
  • סיכון להחזרת הבעלות בטעות: אם פיד קבצים מעודכן פועל אחרי דחיפת API ומכיל את המוצר, מקור הנתונים של הקובץ מקבל בחזרה את הבעלות. אם תשמיטו את המוצר מהקובץ, הוא יימחק באופן לא צפוי.

כדי למנוע מחיקות לא צפויות או אובדן של עדכוני API, אל תבצעו עדכונים בו-זמנית באותם מוצרים באמצעות API ובאמצעות מקורות נתונים ראשיים של קבצים.

שיקולים מרכזיים לגבי ה-API

לפני שמתחילים להטמיע את Merchant API, חשוב להבין את ההתנהגויות הקריטיות הבאות:

מקורות נתונים גמישים (בלי שפה או תווית)

בניגוד לפידים של קבצים, שבהם צריך להגדיר מראש תווית פיד יעד ושפה ספציפיים, ב-Merchant API אפשר ליצור מקורות נתונים ראשיים בלי לציין feedLabel או contentLanguage.

  • העלאות גמישות: אתם יכולים להעלות מוצרים עם כל שילוב של שפה או תווית פיד למקור נתונים אחד.
  • ניהול פשוט יותר: אתם לא צריכים ליצור ולנהל מקורות נתונים נפרדים לכל שוק יעד. הערה: למידע נוסף על בחירת אסטרטגיה של מקור נתונים, ראו בחירת אסטרטגיה של מקור נתונים.

אסטרטגיית סנכרון ומכסות

בניגוד לפיד קבצים שבו אתם מעלים את כל הקטלוג בבת אחת, כשאתם משתמשים ב-Merchant API אתם צריכים לתכנן את השילוב כך שיכלול גם עדכונים מצטברים וגם סנכרונים מלאים בקצב קבוע:

  • לשלב עדכונים מצטברים עם סנכרונים מלאים תקופתיים: שולחים בקשות productInputs.insert או productInputs.patch כשהמאפיינים של המוצרים משתנים בקצה העורפי. הסתמכות על עדכונים מצטברים בלבד עלולה לגרום לכך שהנתונים לא יהיו מסונכרנים לאורך זמן, לכן כדאי להפעיל גם סנכרונים מלאים מדי פעם כדי להתאים את הקטלוג למקור המידע המהימן (פעולה שגם מרעננת את תפוגת המוצר של 30 יום). התדירות שבה מפעילים סנכרון מלא תלויה בגודל הקטלוג ובמכסת ה-API הזמינה.
  • התאימו את קצב הבקשות למכסות ה-API: אל תשלחו קריאות ל-API עבור כל המוצרים בבת אחת. אפשר לשלוח שינויים מצטברים כשהם מתרחשים, אבל כדאי לפרוס את הבקשות לסנכרון מלא באופן שווה לאורך היום כדי לא לחרוג מהמכסות היומיות והמכסות לדקה של הפעלות ה-method. פרטים נוספים זמינים במאמרים מכסות ומגבלות ועדכון תכוף של המוצרים.

בדיקת השילוב

לפני שמעבירים את לוגיקת השילוב לסביבת הייצור, חשוב לאמת אותה בסביבה בטוחה.

שימוש בחשבונות בדיקה

לפני שתבצעו שינויים בסביבת הייצור, מומלץ לבצע את השלבים הראשונים של ההעברה בחשבון בדיקה בארגז חול:

  1. יצירת חשבון בדיקה: מגדירים חשבון בדיקה מבודד כדי להתנסות בבטחה בלי להשפיע על מודעות פעילות או על כרטיסי מוצר חינמיים.
  2. יצירת מקור נתונים של API: תרגול של יצירת מקור נתונים ראשי של API.
  3. בדיקת כללי מאפיינים: אימות של טרנספורמציות נתונים וצירוף פידים משלימים.
  4. אימות של מטעני נתונים ומפתחות מוצרים: שולחים מוצרים לדוגמה כדי לוודא שהאותיות הרישיות, הקידוד והטיפול בשגיאות של המק"טים תקינים.

פרטים נוספים זמינים במאמר שלב 1: יצירת חשבונות לבדיקה ובמדריך בנושא חשבונות לבדיקה.

אימות ההתאמה של מפתח המוצר

חשוב לוודא שמפתח המוצר של המטען הייעודי (payload) הפרוגרמטי תואם בדיוק למק"טים של פיד הקבצים. ‫Google מזהה מוצרים על ידי שילוב של:

  • offerId (נקרא id בפידים של קבצים, תלוי אותיות רישיות)
  • contentLanguage (לדוגמה, en)
  • feedLabel (לדוגמה, US)

תווים מיוחדים וקידוד

אם מזהי המוצרים שלכם מכילים תווים כמו /,‏ % או ~, השתמשו בפורמט מקודד (קידוד base64url ללא ריפוד) בקריאות ל-API. מידע נוסף זמין במאמר ProductInput.name.

בקרת בו-זמניות

בשילוב בזמן אמת, העדכונים יכולים להגיע בסדר לא נכון בגלל זמן אחזור ברשת. כדי למנוע מעדכונים ישנים יותר להחליף נתונים חדשים יותר, משתמשים בשדה versionNumber במשאב ProductInput.

מדריך מפורט להעברה

אם אתם מחליטים להעביר חלק מהמוצרים או את כולם מפידים של קבצים אל Merchant API, כדאי לפעול לפי ההוראות במדריך הזה כדי להעביר את המוצרים בלי לאבד חשיפות או את היסטוריית ההצגה.

1. תרגול ההעברה בחשבון בדיקה

לפני שמבצעים שינויים בסביבת הייצור, יוצרים חשבון בדיקה בארגז חול באמצעות השיטה accounts.createTestAccount (ראו את המדריך חשבונות בדיקה). חשבונות בדיקה מספקים סביבה מבודדת שבה המוצרים מאושרים כברירת מחדל, לא נדרש אימות דומיין והנתונים אף פעם לא מוצגים באופן ציבורי.

אתם יכולים להשתמש בחשבון הבדיקה כדי לשקף את הגדרת הייצור ולתרגל את ההעברה מקצה לקצה:

  1. שכפול הגדרת פיד המוצרים של הקובץ: יוצרים מקור נתונים ראשי של קובץ (וכל מקור נתונים משלים) בחשבון הבדיקה ומעלים דוגמה של קובץ הפיד בסביבת הייצור.
  2. יצירת מקור נתונים וכללים לבדיקת ה-API: יוצרים מקור נתונים ראשי ל-API ומגדירים את כללי המאפיינים הנדרשים או את הפידים המשלימים שרוצים לצרף.
  3. בדיקת העברת הבעלות והתאמת המפתחות: שולחים productInputs.insert בקשות למוצרים לדוגמה ומוודאים שמקור הנתונים של ה-API מקבל בעלות על הפריטים הקיימים בלי ליצור מוצרים כפולים.
  4. אימות עדכונים ומחיקות: בודקים עדכונים חלקיים באמצעות productInputs.patch והסרות באמצעות productInputs.delete, ובוחנים את המשאבים שנוצרו באמצעות products.get.

2. יצירת מקורות נתונים של Products API בסביבת הייצור

לפני שמעבירים נתונים, צריך ליצור בחשבון מקור נתונים ראשי מסוג API.

יצירת מקור נתונים ראשי ל-API

כדי ליצור מקור נתונים שמקבל דחיפות API, שולחים בקשת POST לנקודת הקצה dataSources. פרטים נוספים זמינים במאמר יצירת מקור ראשי של נתוני מוצרים.

3. העברת כללי מאפיינים מותאמים אישית

כללי מאפיינים מותאמים אישית מקושרים למקורות נתונים ספציפיים, והם לא מועברים אוטומטית ממקור הנתונים של הקובץ למקור הנתונים החדש של ה-API.

האופן שבו מעבירים את כללי המאפיינים תלוי במטרה שלהם:

  • מיזוג בין מקורות ופידים משלימים של צד שלישי: אם אתם משלבים נתוני API ראשיים עם מקורות נתונים משלימים חיצוניים (כמו קבצים של ספקים מצד שלישי, גיליונות אלקטרוניים של מלאי או פידים של מבצעים), אתם צריכים ליצור מחדש את כללי המאפיינים בממשק המשתמש של Merchant Center ולצרף אותם למקור נתוני ה-API החדש. עיבוד מראש בצד הלקוח לא יכול להחליף כללים שמחברים נתונים ממקורות עצמאיים מרובים.
  • טרנספורמציות של נתונים ממקור יחיד: כדי לנקות נתונים, להגדיר ערכי ברירת מחדל או לשנות את הפורמט של מחרוזות בנתוני הקטלוג הראשי, בוחרים באחת מהאפשרויות הבאות:
    • טרנספורמציות בקצה העורפי (מומלץ): החלת טרנספורמציות במערכת שלכם לפני הקריאה ל-API. כך אתם יכולים לשלוט טוב יותר באופן פרוגרמטי, לבצע בדיקות בקלות רבה יותר ולפשט את תהליך ניפוי הבאגים.
    • כללי מאפיינים ב-Merchant Center: אם אתם רוצים ש-Merchant Center ימשיך לנהל את כללי השינוי באופן אוטומטי, אתם צריכים ליצור אותם מחדש בממשק המשתמש של Merchant Center בשביל מקור הנתונים החדש של ה-API.

4. הפעלת השילוב של ה-API

מפעילים את שילוב ה-Products API בסביבת הייצור כדי להתחיל להוסיף, לעדכן ולמחוק מוצרים במקור הנתונים הראשי החדש של ה-API:

  • הוספה ועדכון של מוצרים (העברת בעלות): שולחים בקשות productInputs.insert ו-productInputs.patch מהאינטגרציה. כשמוסיפים מוצר באמצעות ה-API עם אותו מפתח (offerId,‏ contentLanguage,‏ feedLabel) כמו של מוצר קיים בפיד קבצים, מקור הנתונים של ה-API מקבל בעלות על המוצר הזה ושומר את היסטוריית ההצגה שלו. למידע נוסף, קראו את המאמרים הוספת מוצר והוספה וניהול של מוצרים.

  • מחיקת מוצרים שהייצור שלהם הופסק: הגדירו את השילוב כך שיפעיל באופן מפורש את productInputs.delete בכל פעם שמוצר מוסר מהקטלוג.

  • הטמעה הדרגתית: אם יש לכם קטלוגים גדולים, כדאי להפעיל את השילוב בכל פעם בחשבון משנה אחד של Merchant Center או במקור נתונים אחד.

  • הגדרת בו-זמניות: אם אתם שולחים הרבה בקשות, הגדירו את הלקוח כך שיטפל בבקשות מקבילות וינהל כמה חיבורים. איך משנים את הקוד כדי לטפל בבקשות בו-זמניות

5. השהיית העדכונים של מקור נתונים מסוג קובץ

אחרי שהשילוב של ה-API פעיל, צריך להפסיק את עדכוני הקבצים לפני ההפעלה המתוזמנת הבאה של הקובץ, כדי שמקור הנתונים של הקובץ לא יחליף את עדכוני ה-API:

  1. מפסיקים להעלות קבצים חדשים למיקום SFTP או FTP, ל-Google Cloud Storage או ל-Google Sheets.
  2. בממשק המשתמש של Merchant Center, עוברים למקור הנתונים של הקובץ ומשהים את השליפה המתוזמנת שלו.
  3. מוצרים קיימים שנמצאים בבעלות של מקור הנתונים מהקובץ נשארים פעילים למשך עד 30 יום, עד ששילוב ה-API מוסיף אותם.

6. מחכים שההעברה תסתיים ומאמתים

מחכים עד שכל המוצרים הפעילים יועברו ממקור הנתונים של הקובץ למקור הנתונים של ה-API. עדכונים מצטברים מעבירים מוצרים כשהם משתנים, אבל הפעלת סנכרון מלא של הקטלוג בקצב קבוע דרך האינטגרציה הרגילה מזרזת את ההעברה של כל הקטלוג (ראו אסטרטגיית סנכרון ומכסות).

בשלב הזה:

  1. בממשק המשתמש של Merchant Center, עוקבים אחרי מספר הפריטים. צריך לחכות עד שמספר מקורות הנתונים של הקבצים ירד ל-0 ומספר מקורות הנתונים של ה-API יהיה זהה למספר הקטלוגים הפעילים.
  2. משתמשים ב-products.get כדי לוודא שהמאפיינים והכללים של המאפיינים המותאמים אישית מתמזגים כמו שצריך.
  3. כדי לעקוב אחרי שיעורי השגיאות והביצועים של ה-API, כדאי להשתמש בכלי אבחון API בממשק המשתמש של Merchant Center.

7. הוצאה משימוש של מקור נתונים מסוג קובץ

אחרי שהמעבר יושלם ומספר הפריטים בפיד הקבצים יהיה 0:

  1. מוודאים שהעדכונים משתקפים בזמן אמת.
  2. כדי למנוע מצב שבו עדכונים מבוססי-קובץ יחליפו בטעות את נתוני ה-API, מחקו את מקור הנתונים של הקובץ הקודם בממשק המשתמש של Merchant Center.
הקודם
Migrate Local Inventory Ads settings