מעבר מ-Content API לגרסה 2.1

במרץ 2019 השקנו את גרסה 2.1 של Content API for Shopping, ובאפריל 2021 הודענו שגרסה 2 תצא משימוש ב-30 בספטמבר 2021. גרסה v2 יצאה משימוש. צריך לעבור לגרסה 2.1 באופן מיידי.

העברת האפליקציה

כדי לבצע מיגרציה מגרסה 2 לגרסה 2.1, צריך לעדכן את כתובות ה-URL של נקודות הקצה כדי לקרוא לגרסאות החדשות של גרסה 2.1, ולשנות את האפליקציות כך שיתאימו לשינויים שעלולים לשבור את התאימות לאחור שהוצגו בגרסה 2.1.

עדכון הקריאות ל-API לשימוש בנקודות קצה בגרסה 2.1

כדי להתקשר לגרסה 2.1, צריך לעדכן את הבקשות כך שישתמשו בנקודות הקצה החדשות של גרסה 2.1.

לדוגמה, כדי להפעיל את השיטה products.get עם v2, משתמשים בפקודה הבאה:

GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId

בגרסה 2.1, מעדכנים את כתובת ה-URL לכתובת הבאה:

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId

מידע מלא על שירותים ונקודות קצה בגרסה 2.1 זמין בהפניית ה-API.

ביצוע השינויים הנדרשים

בנוסף לעדכון כתובות ה-URL של הקריאות ל-API, צריך גם לעדכן את האפליקציה כדי להתאים אותה לכמה שינויים משמעותיים שהוכנסו בגרסה 2.1. בודקים את הקטעים הבאים ומעדכנים את הבקשה לפי הצורך.

1. עדכון שילובים עם שירות inventory

שירות v2 inventory הוסר, ופונקציונליות שוות ערך זמינה בתכונות הבאות של גרסה v2.1:

  • כדי לעדכן חלק מנתוני המוצרים, אפשר להשתמש בפידים משלימים חדשים או ב-products.update. אפשר לעדכן את כל השדות של המוצרים שניתנים לשינוי, כולל כל השדות שעודכנו בעבר באמצעות inventory.set (לא כולל שדות שייחודיים ל-localinventory). פרטים נוספים זמינים במאמר בנושא מעבר לשימוש בפידים משלימים.

  • משתמשים בשירות החדש localinventory לעדכוני מוצרים בחנויות מקומיות.

2. עדכון שיחות לשירות accounts

  • קריאות ל-method ‏accounts.update בגרסה 2.1 מחליפות לחלוטין את המשאב accounts, במקום לעדכן רק את השדות שנכללים בבקשה. כדי למנוע מחיקה של שדות במשאב accounts, צריך לעדכן את בקשות הקריאה כך שיכללו את כל השדות.

  • הכרטיס reviewsUrl הוסר.

  • הסטטוס של הקישור inactive הוסר מהחשבונות adsLinks,‏ googleMyBusinessLink ו-youtubeChannelLinks.

3. עדכון שיחות לשירות products

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

  • השדה החוזר productTypes החליף את השדות productType ו-additionalProductTypes.

  • השדות החוזרים includedDestinations ו-excludedDestinations החליפו את השדה החוזר destinations.

  • השמות של השדות הבאים שקשורים ל-AdWords שונו:

    • ‫adwordsGrouping -> ‏adsGrouping
    • ‫adwordsLabels -> ‏adsLabels
    • ‫adwordsRedirect -> ‏adsRedirect

  • השדות הבאים הוסרו:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • הפרמטר includeInvalidInsertedItems הוסר. בגרסה 2.1, כל המוצרים מוחזרים כברירת מחדל.

  • עכשיו יש עיכוב של כמה דקות לפני שאפשר לאחזר מוצר שהוספתם באמצעות products.get או products.list.

  • הערך offerId שמוחזר לא בהכרח זהה לערך offerId שהוזן. בגרסה 2.1, המערכת חותכת רווחים בתחילת השורה או בסופה ב-offerId וממזגת כמה רווחים לרווח אחד. השינוי הזה לא משפיע על ערכי offerId שתואמים לתחביר המומלץ של offerId.

  • המחירים מאומתים עכשיו לפני הוספת המוצרים. מחרוזת הערך יכולה לכלול רק את התווים הבאים: +, -, . וספרות (כלומר, 0-9). אי אפשר יותר להשתמש בפסיקים.

  • תגובות מקריאה לפונקציה products.insert או products.update מכילות רק את המאפיינים הבאים:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • האפשרות v2‏ includeAttributes הוצאה משימוש. במקום זאת, אפשר להשתמש ב-products.get עם ProductId כדי לראות את פרטי המוצר המלאים.

4. עדכון שיחות לשירות productstatuses

  • המאפיין product הוסר, יחד עם הפרמטר includeAttributes. כדי לאחזר מאפיינים של המוצר שמתאימים לסטטוס, צריך להשתמש בשירות products ולהעביר את הערך של השדה החדש productId.

  • הפרמטר includeInvalidInsertedItems הוסר. productId של כל מוצר מוחזר עכשיו, בלי קשר לתוקף של המוצר.

  • השדות intention, ‏approvalStatus ו-approvalPending ב-destinationStatuses הוחלפו ב-status, שהוא מחרוזת שיכולה להיות אחת מהאפשרויות הבאות: approved, ‏disapproved או pending.

  • ‫dataQualityIssues הוחלף ב-itemLevelIssues.

5. עדכון שיחות לשירות datafeeds

  • השדות הבאים של היעד הוחלפו:

    • ‫contentLanguage -> ‏language
    • ‫targetCountry -> ‏country
    • ‫intendedDestinations -> includedDestinations ו-excludedDestinations

  • הוסרו פידים של נתונים עם contentType = "product inventory update".

6. עדכון הקריאות לשירותים orders ו-TestOrders

  • בגרסה 2.1, השיחות לא צריכות לכלול נתוני מס כי נתוני המס מחושבים באופן אוטומטי. אם ההזמנה מבוצעת במדינה שבה חל חוק ה-Marketplace Fairness Act (MFA) או חוק דומה, שיחות שכוללות נתוני מס נכשלות. אם ההזמנה מועברת למצב שבו לא נדרש אימות רב-שלבי, המס מחושב על סמך ההגדרות שנקבעו ב-Merchant Center. אם לא תגדירו ערך, סכום המס המחושב יהיה 0.

  • השדות InStoreRefundLineItem ו-ReturnRefundLineItem amountPretax ו-amountTax הוחלפו בשדות priceAmount ו-taxAmount, בהתאמה. priceAmount יכול להיות לפני מס או אחרי מס, בהתאם למיקום של ההזמנה.

  • השדות ShipLineItem carrier,‏ shipmentId ו-trackingId בבקשה הועברו אל shipmentInfos.

  • השדות billingAddress ו-predefinedBillingAddress הם עכשיו שדות ברמה העליונה ב-orders וב-TestOrder, בהתאמה.

  • ‫customer.explicitMarketingPreference הוחלף ב-customer.marketingRightsInfo.

  • השדה netAmount פוצל לשני שדות: netPriceAmount ו-netTaxAmount.

  • ‫shippingOption הוחלף ב-lineItems[].shippingDetails.

  • השדות CancelLineItem amount,‏ amountPretax ו-amountTax בבקשה הוסרו. הסכום שיוחזר מחושב עכשיו באופן אוטומטי.

  • CustomBatch הוסר.

  • Refund הוסר. במקומה, צריך להשתמש ב-refundOrder או ב-refundItem.

  • השדה paymentMethod הוסר.

  • השיטות v2orders.returnlineitem ו-orders.refund הוחלפו בשיטות orderreturns.creatOrderReturn ו-orderreturns.process.

  • השדות customer.email, channelType ו-lineItem.product.channel הוסרו.

  • השדה promotions הוסר מהשירות TestOrder והפורמט שלו השתנה ב-Order.

7. עדכון שיחות לשירות orderinvoice

  • השדות amountPretax ו-amountTax הוחלפו בשדות priceAmount ו-taxAmount, בהתאמה. הערך בשדה priceAmount יכול להיות לפני או אחרי ניכוי מס, בהתאם למיקום של ההזמנה.

  • הוסרו יתרות (של מוֹכר, לקוח ו-Google) ב-invoiceSummary ובשדות שקשורים לחיוב על מבצעים.

8. הסרת פונקציונליות שלא נכללת בגרסה 2.1

בגרסה 2.1 של Content API הוסרו כמה תכונות נוספות. צריך לבדוק את הרשימה הבאה ולעדכן את הבקשה לפי הצורך:

  • אין יותר תמיכה ב-XML. מידע נוסף על מעבר ל-JSON זמין במאמר בנושא הפסקת התמיכה ב-XML ב-Content API for Shopping.

  • הפרמטר dryRun הוסר. השינוי הזה חל על כל הקריאות ל-API.

  • כל השיטות של HTTP BATCH הוסרו. במקום זאת, אתם צריכים להשתמש ב-customBatch.

  • השיטה patch הוסרה מהשירותים הבאים:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • השירות orderpayments הוסר.

בדיקת ההעברה

למידע נוסף על בדיקת השינויים באפליקציות אחרי המעבר לגרסה 2.1, אפשר לעיין במאמר בדיקת השימוש ב-Content API for Shopping. אם נתקלים בבעיות במהלך בדיקת העדכונים, אפשר לפנות אלינו.

שינויים נוספים בגרסה 2.1

בנוסף לשינויים שדורשים עדכונים, גרסה 2.1 כוללת גם כמה תכונות חדשות ושינויים שלא גורמים לבעיות תאימות:

  • שירותים חדשים:

    • השירות החדש localinventory מאפשר לכם לבצע עדכונים של מוצרים מקומיים (במקום השירות inventory בגרסה 2).

    • שירות orderreturns החדש מאפשר לכם לנהל בקלות את התכונה 'קונים ב-Google' (לשעבר Shopping Actions) ולעבד החזרות בלי להשתמש בשירות orders.

  • פידים משלימים מאפשרים לעדכן חלק מנתוני המוצרים.

  • שינויים נוספים בשירות products:

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

    • products.update נוספה אפשרות לעדכן קבוצה נבחרת של שדות מוצר. מידע נוסף על אפשרויות השימוש מופיע במדריך.

    • ערכים לא תקינים במאפיינים הבאים כבר לא גורמים לשגיאות בהוספה, ומוחזרים כחלק מ-itemLevelIssues על ידי השירות productstatus:

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • המאפיינים המותאמים אישית הם עכשיו רקורסיביים, ולכן אין יותר צורך בקבוצות מותאמות אישית.

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