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

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

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

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

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

כדי לבצע קריאות לגרסה 2.1, צריך לעדכן את הבקשות לשימוש בנקודות הקצה החדשות של v2.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

השירות inventory של גרסה 2 הוסר, והפונקציונליות המקבילה זמינה עם התכונות הבאות של 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. v2.1 חותכת רווחים לבנים בתחילת הטקסט ובסופו של offerId וממזגת כמה תווי רווח לבן לאחד. השינוי הזה לא משפיע על ערכי offerId שתואמים לתחביר offerId המומלץ.

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

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

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • האפשרות includeAttributes לגרסה 2 הוצאה משימוש. במקום זאת, צריך להשתמש ב-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 (MFA) או פעולה דומה, קריאות שכוללות נתוני מס ייכשלו. אם ההזמנה מולאה במצב שאינו 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 הוסר.

  • השיטות orders.returnlineitem ו-orders.refund של גרסה 2 מוחלפות ב-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

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

  • התמיכה ב-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. אם תיתקלו בבעיות במהלך בדיקת העדכונים, תוכלו לפרסם את הבעיה בפורום של Content API.

שינויים נוספים בגרסה 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 המקורי. צריך להגדיר בדיוק אחד מהשדות.