Migracja z Content API v2 do wersji 2.1

W marcu 2019 roku opublikowaliśmy wersję 2.1 Content API for Shopping, a w kwietniu 2021 roku ogłosiliśmy, że 30 września 2021 r. wycofamy wersję 2. Wersja 2 została wycofana. Natychmiast przejdź na wersję 2.1.

Migracja aplikacji

Migracja z wersji 2 do 2.1 obejmuje zaktualizowanie adresów URL punktów końcowych w celu wywoływania nowych wersji v2.1 i zmodyfikowanie aplikacji w taki sposób, aby uwzględnić zmiany powodujące niezgodność wprowadzone w wersji 2.1.

Zaktualizuj wywołania interfejsu API, aby używały punktów końcowych w wersji 2.1

Aby móc wywoływać wersję 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 za pomocą wersji 2, musisz użyć:

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

W przypadku wersji 2.1 zaktualizuj adres URL do:

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

Więcej informacji o usługach i punktach końcowych w wersji 2.1 znajdziesz w dokumentacji interfejsu API.

Wprowadzanie wymaganych zmian

Oprócz aktualizacji adresów URL wywołań interfejsu API musisz też zaktualizować swoją aplikację, uwzględniając w niej kilka zmian powodujących niezgodność wprowadzonych w wersji 2.1. Zapoznaj się z sekcjami poniżej i w razie potrzeby zaktualizuj swoją aplikację.

1. Aktualizuj integracje z usługą inventory

Usługa inventory w wersji 2 została usunięta i jest dostępna jej odpowiednik z tymi funkcjami w wersji 2.1:

• Użyj nowych dodatkowych plików danych lub products.update w przypadku częściowych aktualizacji produktów. Można aktualizować wszystkie zmienne pola produktów, w tym pola, które zostały wcześniej zaktualizowane za pomocą pola inventory.set (z wyjątkiem pól dostępnych tylko dla pola localinventory). Więcej informacji znajdziesz w artykule Przejście na dodatkowe pliki danych.

• Do aktualizowania produktów dostępnych lokalnie używaj nowej usługi localinventory.

2. Zaktualizuj wywołania usługi accounts

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

• Element reviewsUrl został usunięty.

• Stan połączenia inactive został usunięty z usług adsLinks, googleMyBusinessLink i youtubeChannelLinks.

3. Zaktualizuj wywołania usługi products

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

• Pole powtarzane productTypes zastąpiło zarówno pole productType, jak 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 wszystkie produkty są domyślnie zwracane.

• Występuje teraz kilka minut opóźnienia, zanim będzie można pobrać wstawiony produkt za pomocą usługi products.get lub products.list.

• Nie ma już gwarancji, że zwrócona wartość offerId będzie taka sama jak podana w danych wejściowych offerId. Wersja 2.1 usuwa odstępy na początku i na końcu ciągu offerId oraz scala wiele znaków odstępu w jeden. Ta zmiana nie ma wpływu na wartości offerId zgodne z zalecaną składnią offerId.

• Ceny są teraz weryfikowane przed wstawieniem produktu. W ciągu wartości dozwolone są tylko te znaki: +, -, . i cyfry (tj. 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 includeAttributes w wersji 2 została wycofana. Zamiast tego używaj atrybutu products.get razem z atrybutem ProductId, aby wyświetlać pełne informacje o produkcie.

4. Zaktualizuj wywołania usługi productstatuses

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

• Parametr includeInvalidInsertedItems został usunięty. Zwracana jest teraz wartość productId każdego produktu niezależnie od tego, czy jest on prawidłowy.

• Pola intention, approvalStatus i approvalPending w tabeli destinationStatuses zostały zastąpione ciągiem status, który może być jednym z tych elementów: approved, disapproved lub pending.

• Tabela dataQualityIssues została zastąpiona przez itemLevelIssues.

5. Zaktualizuj wywołania usługi datafeeds

• Te pola docelowe zostały zastąpione:

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

• Pliki danych z contentType = "product inventory update" zostały usunięte.

6. Zaktualizuj połączenia z usługami orders i TestOrders

• W wersji 2.1 wywołania nie powinny zawierać danych podatnika, ponieważ są one obliczane automatycznie. Jeśli zamówienie zostanie zrealizowane w stanie, w którym obowiązuje ustawa o uczciwości platformy handlowej (MFA) lub podobny stan, żądania z danymi podatkowymi zakończą się niepowodzeniem. Jeśli zamówienie zostanie zrealizowane w stanie innym niż MFA, podatek zostanie obliczony na podstawie ustawień skonfigurowanych w Merchant Center. Jeśli nie skonfigurujesz tej zasady, obliczony podatek będzie wynosić 0.

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

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

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

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

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

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

• Pola CancelLineItem amount, amountPretax i amountTax w żądaniu zostały usunięte. Zwrócona kwota jest teraz obliczana automatycznie.

• Zasób CustomBatch został usunięty.

• Zasób Refund został usunięty. Użyj w zamian zasady refundOrder lub refundItem.

• Pole paymentMethod zostało usunięte.

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

• Pola customer.email, channelType i lineItem.product.channel zostały usunięte.

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

7. Zaktualizuj wywołania usługi orderinvoice

• Pola amountPretax i amountTax zostały zastąpione odpowiednio przez priceAmount i taxAmount. W zależności od lokalizacji zamówienia pole priceAmount może zawierać wartość przed opodatkowaniem lub po opodatkowaniu.

• Usunięto salda (sprzedawca, klient, Google) w polach invoiceSummary i związanych z opłatami promocyjnymi.

8. Usuń funkcję, która nie jest dostępna w wersji 2.1

Kilka innych funkcji zostało usuniętych z Content API w wersji 2.1. Przejrzyj tę listę i w razie potrzeby zaktualizuj zgłoszenie:

• Kod XML nie jest już obsługiwany. Więcej informacji o przechodzeniu na format JSON znajdziesz w artykule na temat wycofania 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. Użyj w zamian 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 użycia Content API for Shopping. Jeśli podczas testowania aktualizacji napotkasz problemy, możesz je zgłosić na forum Content API.

Dodatkowe zmiany w wersji 2.1

Oprócz zmian wymagających aktualizacji wersja 2.1 wprowadza również kilka nowych funkcji i nienaruszających zmian:

• Nowe usługi:

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

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

• Dodatkowe pliki danych umożliwiają częściowe aktualizacje produktów.

• Dodatkowe zmiany w usłudze products:

  • Żądania products.insert nie zgłaszają już ostrzeżeń ani błędów niekrytycznych. Dzięki temu możesz wstawiać produkty i wprowadzać późniejsze aktualizacje w celu rozwiązywania problemów za pomocą reguł pliku danych w Merchant Center, tak jak w przypadku plików danych zarządzanych poza Content API.

  • Dodaliśmy products.update, aby umożliwić Ci aktualizowanie wybranego zestawu pól produktu. Więcej informacji o możliwym wykorzystaniu znajdziesz w przewodniku.

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

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

  • Atrybuty niestandardowe mają teraz charakter rekurencyjny, dzięki czemu nie trzeba tworzyć grup niestandardowych.

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