Migracja z wersji v1beta do v1

Ten przewodnik pomoże Ci przejść z interfejsu Merchant API v1beta na v1, czyli pierwszą wersję ogólnodostępną. Wersja 1 wprowadza kilka aktualizacji i zmian, które mogą wymagać aktualizacji kodu. Te zmiany mają na celu uproszczenie interfejsu API i ułatwienie zarządzania kontem Merchant Center.

Najważniejsze różnice

Oto najważniejsze zmiany, o których musisz pamiętać podczas migracji z v1beta na v1:

  • Jednorazowa rejestracja co najmniej 1 programisty interfejsu API, który będzie korzystać z Merchant API: musisz wywołać metodę registerGcp (tylko raz w przypadku każdego projektu w chmurze Google używanego do uwierzytelniania), aby podać swoje dane kontaktowe. Dzięki temu będziesz mieć dostęp do interfejsu API oraz otrzymywać aktualizacje i ogłoszenia związane z Merchant API. Dopóki nie wykonasz tego kroku, nie będziesz mieć dostępu do żadnego interfejsu API w wersji v1 ani v1alpha. Więcej informacji o procesie rejestracji znajdziesz w artykule Rejestracja.

  • Kodowanie nazw produktów: pola ProductInput.name i Product.name obsługują kodowanie base64url bez dopełnienia (RFC 4648 sekcja 5). Postępuj zgodnie z tymi wskazówkami:

    • Przed zakodowaniem ciąg znaków musi być zgodny z formatem contentLanguage~feedLabel~offerId.

    • Kodowanie jest obowiązkowe , jeśli nazwa produktu zawiera znaki używane przez Merchant API lub znaki zarezerwowane w adresach URL, takie jak:

      % . + / : ~ , ( * ! ) & ? = @ # $

    • Jeśli nazwa produktu jest zgodna z contentLanguage~feedLabel~offerId formatem i nie zawiera znaków używanych przez Merchant API ani znaków zarezerwowanych w adresach URL, możesz użyć zwykłego formatu bez kodowania.

    • Aby zapewnić spójne i prawidłowe parsowanie, zalecamy używanie kodowania base64url bez dopełnienia w przypadku wszystkich nazw produktów.

  • Usuwanie informacji podatkowych na poziomie produktu: pola taxes i taxCategory.

  • Product.attributes zmieniono nazwę: pole Product.attributes zostało zmienione na Product.productAttributes.

  • Usuwanie informacji podatkowych na poziomie produktu: pola taxes i taxCategory zostały usunięte z Product.productAttributes obiektu. Więcej informacji znajdziesz w artykule pomocy Google Merchant Center na temat podatków.

  • Zmiany w polu GTIN: pole gtin w obiekcie Product.productAttributes zostało zmienione na gtins, aby lepiej odzwierciedlać fakt, że może ono zawierać wiele wartości. Pole gtin w OrderTrackingSignals.lineItemDetails obiekcie jest teraz array i zostało zmienione na gtins.

  • Usunięcie pola kanału: pole channel zostało usunięte z produktów, danych wejściowych produktów i źródeł danych. Wprowadziliśmy nowe pole logiczne legacyLocal, aby wyraźnie oznaczać produkty sprzedawane wyłącznie w sklepach stacjonarnych. Uwaga: pole legacyLocal jest polem pomocniczym, które ułatwia migrację. Zostanie ono wycofane, gdy metody marketingowe online i lokalne będą mogły być w pełni kierowane za pomocą jednego źródła produktów. Więcej informacji znajdziesz w tabeli w następnej sekcji.

  • Nowe pola atrybutów asortymentu regionalnego i lokalnego:

    • Wszystkie RegionalInventory pola z wyjątkiem name, account i region są teraz zawarte w nowym obiekcie o nazwie regionalInventoryAttributes . Na przykład atrybut RegionalInventory.price znajduje się teraz w RegionalInventory.regionalInventoryAttributes.price.
    • Wszystkie LocalInventory pola z wyjątkiem name, account i storeCode są teraz zawarte w nowym obiekcie o nazwie localInventoryAttributes . Na przykład atrybut LocalInventory.price znajduje się teraz w LocalInventory.localInventoryAttributes.price.

  • Usunięcie customAttributes z asortymentu regionalnego i lokalnego: Pole customAttributes zostało usunięte z zasobów RegionalInventory i LocalInventory.

  • Ulepszone tworzenie konta: zbędne pole users zostało usunięte z CreateAndConfigureAccountRequest. Aby powiązać pierwszego użytkownika z nowym kontem, użyj pola pojedynczego user.

  • Zmiana niektórych typów atrybutów z ciągów znaków na wyliczenia: niektóre pola w zasobach Product i Inventory z określoną krótką listą wartości zostały zmienione z typu string na typ enum, aby poprawić sprawdzanie poprawności danych (na przykład pole Product.ProductAttributes.condition jest teraz enum).

  • Usunięcie metody aktualizacji zasad zwrotów online: metoda onlineReturnPolicy.update została usunięta w wersji v1. Zamiast tego utwórz zasady zwrotów online za pomocą onlineReturnPolicy.create metody.

Jak przeprowadzić migrację

Wycofanie wersji v1beta interfejsu Merchant API jest zaplanowane na 28 lutego 2026 r. Więcej informacji o harmonogramie wycofywania znajdziesz w przewodniku po wersjach Merchant API.

  • Pierwszym krokiem migracji jest jednorazowa rejestracja programisty (patrz Rejestrowanie konta dewelopera. Zanim zaczną działać jakiekolwiek metody v1, musisz wywołać metodę registerGcp w przypadku każdego projektu Google Cloud używanego do uwierzytelniania.

  • Niezależnie od tego, jak wywołujesz interfejsy API (za pomocą REST, gRPC lub za pomocą bibliotek klienta), możesz przeprowadzić migrację etapami. Oznacza to, że możesz aktualizować i migrować kod po jednym interfejsie API (na przykład, przenieść interfejs Products API do wersji v1, a interfejs Accounts API pozostawić w wersji v1beta) bez konieczności jednoczesnej aktualizacji całej integracji.

Szczegółowe zmiany pól

W tej tabeli znajdziesz szczegółowe porównanie pól, które uległy zmianie między wersjami v1beta i v1.

v1beta v1 Opis
ProductInput.name ProductInput.name Unpadded base64url encoding jest obsługiwane i obowiązkowe w przypadku nazw produktów zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresach URL.
Product.name Product.name Unpadded base64url encoding jest obsługiwane i obowiązkowe w przypadku nazw produktów zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresach URL.
Product.gtin Product.gtins Zmieniono nazwę pola GTIN.
Product.taxes Usunięto Pole taxes zostało usunięte.
Product.taxCategory Usunięto Pole taxCategory zostało usunięte.
Product.channel Usunięto Pole channel zostało usunięte. W przypadku lokalnych przypadków użycia użyj pola legacyLocal.
Product.attributes Product.productAttributes Pole attributes zostało zmienione na productAttributes.
availability, condition, gender, includedDestinations i excludedDestinations w polach Product są reprezentowane jako strings (lub array strings). Te pola są teraz enums (lub array z enums) Pola z określoną krótką listą wartości zostały zmienione z typu string na typ enum.
price, salePrice, salePriceEffectiveDate i availability w RegionalInventory Przeniesiono do RegionalInventory.regionalInventoryAttributes Te pola zostały przeniesione do regionalInventoryAttributes.
Pole RegionalInventory.availability jest string. RegionalInventory.regionalInventoryAttributes.availability jest teraz enums. Typ dostępności został zmieniony z string na enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla i instoreProductLocation w LocalInventory Przeniesiono do LocalInventory.localInventoryAttributes Te pola zostały przeniesione do localInventoryAttributes.
Pole LocalInventory.availability jest string. LocalInventory.localInventoryAttributes.availability jest teraz enums. Typ dostępności został zmieniony z string na enum.
LocalInventory.customAttributes Usunięto Atrybuty niestandardowe nie są już obsługiwane w przypadku asortymentu lokalnego.
RegionalInventory.customAttributes Usunięto Atrybuty niestandardowe nie są już obsługiwane w przypadku asortymentu regionalnego.
ProductInput.channel Usunięto Pole channel zostało usunięte. W przypadku lokalnych przypadków użycia użyj pola legacyLocal.
DataSource.channel Usunięto Pole channel zostało usunięte. W przypadku lokalnych przypadków użycia użyj pola legacyLocal.
Niedostępne ProductInput.legacyLocal Nowe pole logiczne wskazujące, że produkt może być kierowany tylko na lokalne metody marketingowe. Identyfikator zasobu produktu będzie mieć prefiks „local~”.
Niedostępne Product.legacyLocal Nowe pole logiczne wskazujące, że produkt jest sprzedawany tylko w sklepach stacjonarnych i nie jest dostępny do zakupu online.
Niedostępne DataSource.legacyLocal Nowe pole logiczne wskazujące, że źródło danych zawiera produkty sprzedawane tylko w sklepach stacjonarnych.
OrderTrackingSignals.LineItemDetails.gtin OrderTrackingSignals.LineItemDetails.gtins Pole gtin zostało zmienione na gtins i jest teraz tablicą ciągów znaków (zamiast ciągu znaków).
CreateAndConfigureAccountRequest.users Usunięto Pole users zostało usunięte. Aby dodać pierwszego administratora do konta, użyj pola user.

Wstecz
Refactor code for concurrent requests
Dalej
Overview