Migracja z Content API v2 do wersji 2.1

W marcu 2019 r. udostępniliśmy Content API for Shopping w wersji 2.1, a w kwietniu 2021 r. ogłosiliśmy, że 30 września 2021 r. zakończymy obsługę wersji 2. Wersja 2 została wycofana. Jak najszybciej przejdź na wersję 2.1.

Migracja aplikacji

Migracja z wersji 2 do 2.1 polega na zaktualizowaniu adresów URL punktów końcowych, aby wywoływać nowe wersje 2.1, oraz zmodyfikowaniu aplikacji w celu uwzględnienia zmian powodujących niezgodność, które zostały wprowadzone w wersji 2.1.

Aktualizowanie wywołań interfejsu API w celu korzystania z punktów końcowych w wersji 2.1

Aby dzwonić do wersji 2.1, zaktualizuj żądania tak, aby używały nowych punktów końcowych w wersji 2.1.

Aby na przykład wywołać metodę products.get w wersji 2, użyj tego kodu:

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

W przypadku wersji 2.1 zaktualizuj adres URL na:

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

Pełne informacje o usługach i punktach końcowych w wersji 2.1 znajdziesz w dokumentacji API.

Wprowadzanie wymaganych zmian

Oprócz zaktualizowania adresów URL wywołań interfejsu API musisz też zaktualizować aplikację, aby uwzględnić kilka zmian powodujących niezgodność wsteczną wprowadzonych w wersji 2.1. Przejrzyj poniższe sekcje i w razie potrzeby zaktualizuj wniosek.

1. Aktualizowanie integracji z usługą inventory

Usługa w wersji 2inventory została usunięta, a jej odpowiednik jest dostępny w tych funkcjach w wersji 2.1:

  • Używaj nowych dodatkowych plików danych lub products.update do częściowych aktualizacji produktów. Aktualizacje są możliwe we wszystkich polach produktu, które można zmieniać, w tym we wszystkich polach zaktualizowanych wcześniej za pomocą inventory.set (z wyłączeniem pól dostępnych tylko w localinventory). Więcej informacji znajdziesz w artykule Migracja do dodatkowych plików danych.

  • Użyj nowej usługi localinventory do aktualizacji produktów dostępnych lokalnie.

2. Aktualizowanie wywołań usługi accounts

  • Wywołania metody accounts.update w wersji 2.1 całkowicie zastępują zasób accounts, a nie tylko aktualizują pola uwzględnione w żądaniu. Aby uniknąć usuwania pól w zasobie accounts, zaktualizuj wywołania, tak aby zawierały wszystkie pola.

  • Element reviewsUrl został usunięty.

  • Stan połączenia inactive został usunięty w przypadku tych elementów: adsLinks, googleMyBusinessLink i youtubeChannelLinks.

3. Aktualizowanie wywołań usługi products

  • Atrybuty niestandardowe nie zawierają już typu ani jednostki. Zamiast tego jednostki należy dołączyć do wartości, a typy powinny być wykrywane automatycznie.

  • Pole powtarzane productTypes zastąpiło pola productType i additionalProductTypes.

  • Pola powtarzane includedDestinations i excludedDestinations zastąpiły pole powtarzane destinations.

  • Zmieniliśmy nazwy tych pól związanych z AdWords:

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

  • Usunęliśmy te pola:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • Parametr includeInvalidInsertedItems został usunięty. W wersji 2.1 domyślnie zwracane są wszystkie produkty.

  • Teraz po wstawieniu produktu trzeba odczekać kilka minut, zanim będzie można go pobrać za pomocą products.get lub products.list.

  • Zwrócony ciąg offerId nie musi już być taki sam jak wejściowy ciąg offerId. Wersja 2.1 usuwa spacje na początku i na końcu w polu offerId oraz łączy wiele znaków odstępu w jeden. Ta zmiana nie ma wpływu na wartości offerId zgodne z zalecaną offerIdskładnią.

  • Ceny są teraz weryfikowane przed wstawieniem produktu. W ciągu wartości dozwolone są tylko te znaki: +, -, . i cyfry (np. 0–9). Przecinki nie są już akceptowane.

  • Odpowiedzi z wywołania products.insert lub products.update zawierają tylko te atrybuty:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • Opcja v2 includeAttributes została wycofana. Zamiast tego użyj products.get z ProductId, aby wyświetlić pełne informacje o produkcie.

4. Aktualizowanie wywołań usługi productstatuses

  • Atrybut product został usunięty wraz z parametrem includeAttributes. Aby pobrać atrybuty produktu odpowiadające danemu stanowi, użyj usługi products i przekaż wartość nowego pola productId.

  • Parametr includeInvalidInsertedItems został usunięty. productIdkażdego produktu jest teraz zwracany niezależnie od tego, czy produkt jest prawidłowy.

  • Pola intention, approvalStatus i approvalPending w destinationStatuses zostały zastąpione polem status, które jest ciągiem znaków i może przyjmować jedną z tych wartości: approved, disapproved lub pending.

  • dataQualityIssues została zastąpiona przez itemLevelIssues.

5. Aktualizowanie wywołań usługi datafeeds

  • Te pola docelowe zostały zastąpione:

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations i excludedDestinations

  • Usunięto pliki danych z contentType = "product inventory update".

6. Aktualizowanie wywołań usług orders i TestOrders

  • W wersji 2.1 wywołania nie powinny zawierać danych o podatku, ponieważ są one obliczane automatycznie. Jeśli zamówienie jest realizowane w stanie, w którym obowiązuje ustawa Marketplace Fairness Act (MFA) lub podobna, wywołania zawierające dane podatkowe nie powiodą się. Jeśli zamówienie jest realizowane w stanie, w którym nie obowiązuje podatek MFA, podatek jest obliczany na podstawie ustawień skonfigurowanych w Merchant Center. Jeśli nie zostanie skonfigurowany, obliczony podatek wyniesie 0.

  • Pola InStoreRefundLineItem i ReturnRefundLineItem amountPretax oraz amountTax zostały zastąpione polami priceAmount i taxAmount. priceAmount może być kwotą przed opodatkowaniem lub po opodatkowaniu w zależności od lokalizacji zamówienia.

  • Pola ShipLineItem – carrier, shipmentId i trackingId w żądaniu zostały przeniesione do shipmentInfos.

  • Pola billingAddress i predefinedBillingAddress są teraz polami najwyższego poziomu w przypadku odpowiednio orders i TestOrder.

  • customer.explicitMarketingPreference zostało zastąpione przez customer.marketingRightsInfo.

  • Pole netAmount zostało podzielone na netPriceAmount i netTaxAmount.

  • shippingOption została zastąpiona przez lineItems[].shippingDetails.

  • Pola CancelLineItem – amount, amountPretax i amountTax – w prośbie zostały usunięte. Zwracana kwota jest teraz obliczana automatycznie.

  • Usunięto CustomBatch.

  • Usunięto Refund. Zamiast tego użyj zdarzenia refundOrder lub refundItem.

  • Pole paymentMethod zostało usunięte.

  • Metody v2orders.returnlineitem i orders.refund zostały zastąpione przez metody orderreturns.creatOrderReturn i orderreturns.process.

  • Usunięto pola customer.email, channelType i lineItem.product.channel.

  • Pole promotions zostało usunięte z usługi TestOrder, a jego format został zmieniony w usłudze Order.

7. Aktualizowanie wywołań usługi orderinvoice

  • Pola amountPretax i amountTax zostały zastąpione odpowiednio polami priceAmount i taxAmount. Pole priceAmount może zawierać kwotę przed opodatkowaniem lub po opodatkowaniu w zależności od lokalizacji zamówienia.

  • Usunięto salda (sprzedawcy, klienta, Google) w invoiceSummary i pola związane z opłatami za promocję.

8. Usuwanie funkcji, które nie są uwzględnione w wersji 2.1

W wersji 2.1 Content API usunięto kilka innych funkcji. Sprawdź poniższą listę i w razie potrzeby zaktualizuj aplikację:

  • Format XML nie jest już obsługiwany. Więcej informacji o przejściu na JSON znajdziesz w artykule Wycofanie obsługi XML w Content API for Shopping.

  • Parametr dryRun został usunięty. Ta zmiana dotyczy wszystkich wywołań interfejsu API.

  • Wszystkie metody HTTP BATCH zostały usunięte. Zamiast niej używaj zasady customBatch.

  • Metoda patch została usunięta z tych usług:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • Usługa orderpayments została usunięta.

Testowanie migracji

Więcej informacji o testowaniu zmian w aplikacjach po migracji do wersji 2.1 znajdziesz w artykule Testowanie zastosowań Content API for Shopping. Jeśli podczas testowania aktualizacji napotkasz problemy, możesz skontaktować się z nami.

Dodatkowe zmiany w wersji 2.1

Oprócz zmian wymagających aktualizacji wersja 2.1 wprowadza też kilka nowych funkcji i zmian, które nie powodują przerw w działaniu:

  • Nowe usługi:

    • Nowa usługa localinventory umożliwia wprowadzanie aktualizacji produktów dostępnych lokalnie (zamiast usługi inventory w wersji 2).

    • Nowa usługa orderreturns ułatwia zarządzanie Kup przez Google (wcześniej znaną jako Shopping Actions), ponieważ umożliwia przetwarzanie zwrotów bez konieczności korzystania z usługi orders.

  • Dodatkowe pliki danych umożliwiają wprowadzanie częściowych aktualizacji produktów.

  • Dodatkowe zmiany w usłudze products:

    • products.insert nie zgłaszają już niekrytycznych ostrzeżeń ani błędów. Umożliwia to wstawianie produktów i wprowadzanie kolejnych aktualizacji w celu rozwiązywania problemów za pomocą reguł pliku danych w Merchant Center, tak samo jak w przypadku plików danych zarządzanych poza interfejsem Content API.

    • products.update, aby umożliwić wprowadzanie zmian w wybranym zestawie pól produktu. Więcej informacji o możliwych zastosowaniach znajdziesz w przewodniku.

    • Nieprawidłowe wartości tych atrybutów nie powodują już błędów wstawiania i są zwracane w ramach parametru itemLevelIssues przez usługę productstatus:

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

    • Atrybuty niestandardowe są teraz rekurencyjne, co eliminuje potrzebę stosowania grup niestandardowych.

    • Atrybuty niestandardowe mają teraz pole groupValues oprócz pierwotnego pola value. Musisz ustawić dokładnie jedno z tych pól.