Migracja z wersji v1beta do v1

Ten przewodnik pomoże Ci przejść z interfejsu API sprzedawcy 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 używać 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. Instrukcje znajdziesz w artykule Rejestrowanie konta dewelopera.

  • 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 w adresach URL, takie jak:

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

    • Jeśli nazwa produktu jest zgodna z contentLanguage~feedLabel~offerIdformatem i nie zawiera żadnych znaków używanych przez interfejs API Merchant ani znaków zarezerwowanych w adresach 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 podatku.

  • 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 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 lokalnego i regionalnego 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 regionalnych i lokalnych asortymentów: 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 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 wersji v1. Zamiast tego utwórz zasady zwrotów online za pomocą metody onlineReturnPolicy.create.

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 w procesie migracji jest jednorazowa rejestracja konta dewelopera (patrz Rejestrowanie konta dewelopera). Musisz wywołać metodę registerGcp dla każdego projektu Google Cloud, 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. przenosić 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 w wersjach 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 interfejs 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 interfejs Merchant API lub znaki zarezerwowane w adresie URL.
Product.gtin Product.gtins Zmieniliśmy nazwę pola dla kodów 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 nosi teraz nazwę productAttributes.
Wartości availability, condition, gender, includedDestinations i excludedDestinations w polach Product są reprezentowane jako strings (lub array wartości 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 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 ma teraz status 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 ma teraz status enums Zmieniono typ dostępności z string na enum.
LocalInventory.customAttributes Usunięto Atrybuty niestandardowe nie są już obsługiwane w przypadku lokalnego asortymentu.
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 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ęto Pole users zostało usunięte. Użyj pola user, aby dodać pierwszego administratora do konta.

Wstecz
Refactor code for concurrent requests
Dalej
Overview