Migracja z wersji v1beta do v1

Ten przewodnik pomoże Ci przejść z Merchant API v1beta na v1, czyli pierwszą wersję dostępną ogólnie. 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 jednego 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ć możliwość korzystania z interfejsu API oraz otrzymywania aktualizacji i ogłoszeń związanych z Merchant API. Dopóki nie wykonasz tego kroku, nie będziesz mieć możliwości korzystania z interfejsów API v1 ani v1alpha. Więcej informacji o procesie rejestracji znajdziesz w sekcji Rejestracja.

  • Kodowanie nazwy produktu: 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 interfejs Merchant API lub znaki zarezerwowane dla adresu URL, takie jak:

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

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

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

  • Usuwanie informacji o podatkach na poziomie produktu: znaki taxes i taxCategory.

  • Product.attributes Zmiana nazwy: pole Product.attributes zostało zmienione na Product.productAttributes.

  • Usunięcie informacji o podatku na poziomie produktu: pola taxes i taxCategory zostały usunięte z obiektu Product.productAttributes. 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 obiekcie OrderTrackingSignals.lineItemDetails jest teraz polem array i zostało też 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 ostatecznie 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 regionalnego i lokalnego asortymentu:

    • Wszystkie pola RegionalInventory 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 sekcji RegionalInventory.regionalInventoryAttributes.price.
    • Wszystkie pola LocalInventory 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 sekcji LocalInventory.localInventoryAttributes.price.

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

  • Ulepszone tworzenie konta: z CreateAndConfigureAccountRequest usunięto zbędne pole users. Użyj pola w liczbie pojedynczej user, aby powiązać początkowego użytkownika z nowym kontem.

  • Niektóre typy atrybutów zostały zmienione 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 w celu lepszej weryfikacji danych (np. pole Product.ProductAttributes.condition jest teraz typu enum).

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

Jak przeprowadzić migrację

Wersja v1beta interfejsu Merchant API zostanie wycofana 28 lutego 2026 r. Więcej informacji o harmonogramie wycofywania znajdziesz w przewodniku po wersjach Merchant API.

  • Pierwszym krokiem w procesie migracji jest jednorazowa rejestracja konta dewelopera (patrz Rejestrowanie konta dewelopera). Musisz wywołać metodę registerGcp w przypadku każdego projektu w chmurze Google, którego używasz do uwierzytelniania, zanim zaczną działać jakiekolwiek metody v1.

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

Szczegółowe zmiany w polach

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 obsługiwane i wymagane w przypadku nazw produktów zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresie URL.
Product.name Product.name Unpadded base64url encoding obsługiwane i wymagane w przypadku nazw produktów zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresie URL.
Product.gtin Product.gtins Zmieniliśmy nazwę pola GTIN.
Product.taxes Usunięta Pole taxes zostało usunięte
Product.taxCategory Usunięta Pole taxCategory zostało usunięte
Product.channel Usunięta Pole channel zostało usunięte. W przypadku lokalnych przypadków użycia użyj pola legacyLocal.
Product.attributes Product.productAttributes Pole attributes nosi teraz nazwę productAttributes.
Pola availability, condition, gender, includedDestinations i excludedDestinations w polach Product są reprezentowane jako strings (lub array z strings). Te pola to teraz enums (lub array z enums). Pola z określoną krótką listą wartości zostały zmienione z typu string na enum.
price, salePrice, salePriceEffectiveDate i availability w RegionalInventory Przeniesiono do: RegionalInventory.regionalInventoryAttributes Te pola zostały przeniesione do sekcji regionalInventoryAttributes.
Pole RegionalInventory.availability to string RegionalInventory.regionalInventoryAttributes.availability to teraz enums Zmieniono typ dostępności 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 sekcji localInventoryAttributes.
Pole LocalInventory.availability to string LocalInventory.localInventoryAttributes.availability to teraz enums Zmieniono typ dostępności z string na enum.
LocalInventory.customAttributes Usunięta Atrybuty niestandardowe nie są już obsługiwane w przypadku lokalnego asortymentu.
RegionalInventory.customAttributes Usunięta Atrybuty niestandardowe nie są już obsługiwane w przypadku asortymentu regionalnego.
ProductInput.channel Usunięta Pole channel zostało usunięte. W przypadku lokalnych przypadków użycia użyj pola legacyLocal.
DataSource.channel Usunięta 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 miał przedrostek „local~”.
Niedostępne Product.legacyLocal Nowe pole logiczne wskazujące, że produkt jest sprzedawany tylko w sklepach lokalnych 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 lokalnych sklepach.
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ęta Pole users zostało usunięte. Użyj pola user, aby dodać pierwszego administratora konta.