Migracja usług

Merchant API to bardziej niezawodny i intuicyjny sposób zarządzania danymi produktów. Główną zmianą jest rozdzielenie danych produktów na 2 różne zasoby: ProductInput do przesyłania danych i Product do wyświetlania ostatecznej, przetworzonej wersji, w tym stanu produktu i problemów. Nowa struktura zapewnia bardziej przewidywalne i przejrzyste działanie.

W tym przewodniku omawiamy najważniejsze różnice, aby pomóc Ci przenieść integrację z Content API for Shopping. Szczegółowe instrukcje korzystania z nowych funkcji znajdziesz w artykule Zarządzanie produktami.

Najważniejsze różnice

Oto najważniejsze zmiany w sposobie zarządzania produktami w interfejsie Merchant API w porównaniu z Content API for Shopping:

• Specjalne zasoby na dane wejściowe i przetworzone: interfejs Merchant API dzieli zarządzanie produktami na 2 zasoby. Aby wstawiać, aktualizować i usuwać dane produktów, możesz użyć zasobu ProductInput. Możesz użyć zasobu Product tylko do odczytu, aby wyświetlić produkt końcowy po przetworzeniu przez Google danych wejściowych, zastosowaniu reguł i połączeniu danych z dodatkowych źródeł.

• Kodowanie nazw produktów: w przypadku pól ProductInput.name i Product.name możesz używać kodowania base64url bez dopełnienia (RFC 4648, sekcja 5). Jeśli nazwy produktów zawierają znaki używane przez interfejs Merchant API lub znaki zarezerwowane dla adresów URL, kodowanie jest obowiązkowe. Musisz na przykład zakodować nazwy produktów, jeśli zawierają którykolwiek z tych znaków:

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

• Stan zintegrowanej usługi: usługa productstatuses została usunięta. Problemy z weryfikacją produktów i stany miejsc docelowych są teraz bezpośrednio uwzględniane w zasobie Product w polu productStatus, co upraszcza pobieranie danych.

• Przewidywalne aktualizacje produktów: nowa metoda productInputs.patch bezpośrednio modyfikuje konkretne dane wejściowe produktu. To znaczne ulepszenie w porównaniu z Content API for Shopping, gdzie aktualizacje mogły zostać nieoczekiwanie zastąpione przez inne przesłane pliki danych. W Merchant API aktualizacja pozostaje do momentu, gdy dane wejściowe konkretnego produktu zostaną ponownie zaktualizowane lub usunięte. Aktualizacje produktów są stosowane do zasobu ProductInput, a nie do zasobu Product.

• Wybierz źródło danych, aby ułatwić zarządzanie danymi: wszystkie operacje zapisu w productInputs wymagają teraz parametru zapytania dataSource, co pozwala jednoznacznie określić, które źródło danych modyfikujesz. Jest to szczególnie przydatne, jeśli masz kilka źródeł danych.

• Nowe identyfikatory zasobów: produkty są teraz identyfikowane za pomocą zasobu RESTful name zamiast pola id. Format to accounts/{account}/products/{product}.

• Brak niestandardowych grup: metoda custombatch nie jest już dostępna. Możesz używać żądań asynchronicznych lub grupowania żądań HTTP, aby wysyłać wiele żądań w jednym wywołaniu HTTP.

.

Wytyczne dotyczące źródeł danych podczas migracji

Zanim przeniesiesz źródła danych, zdecydowanie zalecamy wybranie strategii dotyczącej źródeł danych.

Aby zapewnić płynną migrację i zapobiec problemom, takim jak kradzież ofert, postępuj zgodnie z tymi zaleceniami:

• Uzupełnij bazę danych: zamiast wywoływać metodę dataSources.list przed każdą operacją na produkcie, zdecydowanie zalecamy jednorazowe uzupełnienie lokalnej bazy danych. Dodaj pole nazwy dataSource do każdego rekordu produktu, aby móc podawać prawidłowy identyfikator bezpośrednio w żądaniach.

• Konsolidacja i używanie źródeł danych dla dowolnej etykiety źródła danych i języka: Merchant API umożliwia utworzenie źródła danych bez określania etykiety źródła danych i języka, co pozwala na dodawanie produktów z dowolną etykietą źródła danych i językiem źródła danych. Rozważ użycie jednego źródła danych dla każdej etykiety i każdego języka.

• Ochrona produktów: jeśli używasz reguł źródła danych, wywołaj metodę products.get, aby znaleźć dokładny identyfikator dataSource powiązany z produktem, zanim go zaktualizujesz lub usuniesz. Dzięki temu masz pewność, że modyfikujesz właściwe źródło, i zapobiegasz przypadkowemu przejęciu oferty.

Żądania

W tej sekcji porównujemy formaty żądań w Content API for Shopping i Merchant API.

Opis prośby	Content API for Shopping	Merchant API
Pobieranie produktu	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Wyświetl listę produktów	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Wstaw produkt	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
Aktualizowanie produktu	PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Usuwanie produktu	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Sprawdzanie stanu produktu	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Wyświetlanie stanów produktów	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Grupowanie wielu żądań	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	Używanie żądań asynchronicznych lub grupowania żądań HTTP

Identyfikatory

Format identyfikatorów produktów w interfejsie Merchant API został zmieniony na standardową nazwę zasobu REST.

Opis identyfikatora	Content API for Shopping	Merchant API
Identyfikator produktu	Ciąg znaków składający się z segmentów rozdzielonych dwukropkiem (:). Format: channel:contentLanguage:targetCountry:offerId lub channel:contentLanguage:feedLabel:offerId. Przykład: online:en:US:sku123	Ciąg znaków zasobu REST name. Format: accounts/{account}/products/{product}, gdzie {product} to contentLanguage~feedLabel~offerId. Przykład: accounts/12345/products/en~US~sku123. Kodowanie: kodowanie base64url bez dopełnienia jest zalecane i obowiązkowe w przypadku identyfikatorów produktów, które zawierają znaki używane przez interfejs Merchant API lub znaki zarezerwowane dla adresów URL.

Metody

Ta tabela zawiera metody Content API for Shopping i ich odpowiedniki w Merchant API.

Metoda Content API for Shopping	Metoda Merchant API	Dostępność i uwagi
products.get	products.get	Pobiera ostateczny, przetworzony produkt.
products.list	products.list	Wyświetla listę ostatecznych, przetworzonych produktów.
products.insert	productInputs.insert	Wstawia dane wejściowe produktu. Wymaga dataSource.
products.update	productInputs.patch	Zachowanie znacznie się różni. Aktualizuje konkretne dane wejściowe produktu i jest trwały.
products.delete	productInputs.delete	Usuwa konkretne dane wejściowe produktu. Wymaga dataSource.
products.custombatch	Niedostępne	Używaj żądań asynchronicznych lub grupowania żądań HTTP.
productstatuses.get	products.get	Usługa productstatuses została usunięta. Informacje o stanie są teraz częścią zasobu Product.
productstatuses.list	products.list	Usługa productstatuses została usunięta. Informacje o stanie są teraz częścią zasobu Product.
productstatuses.custombatch	Niedostępne	Używaj żądań asynchronicznych lub grupowania żądań HTTP.

Szczegółowe zmiany w polach

Ta tabela zawiera ważne pola, które zostały zmienione, dodane lub usunięte w interfejsie Merchant API.

Content API for Shopping	Merchant API	Opis
id	name	Głównym identyfikatorem produktu jest teraz zasób REST name. Kodowanie base64url bez dopełnienia jest zalecane i obowiązkowe w przypadku nazw produktów, które zawierają znaki używane przez interfejs Merchant API lub znaki zarezerwowane dla adresów URL.
Atrybuty specyfikacji danych produktów najwyższego poziomu (np. title, price, link)	productAttributes obiekt	Atrybuty produktów takie jak title, price i link nie są już polami najwyższego poziomu. Są one teraz zgrupowane w obiekcie productAttributes zarówno w zasobach Product, jak i ProductInput. Zapewnia to bardziej przejrzystą i uporządkowaną strukturę zasobów.
targetCountry	feedLabel	Nazwa zasobu używa teraz feedLabel zamiast targetCountry, aby dostosować się do funkcji Merchant Center.
feedId	dataSource (parametr zapytania)	Nazwa dataSource jest teraz wymaganym parametrem zapytania we wszystkich metodach zapisu productInputs (insert, update, delete).
channel	Niedostępne. Użyj wartości legacy_local w przypadku produktów dostępnych tylko lokalnie.	Pole channel nie jest już dostępne w Merchant API. W przypadku produktów z kanałem LOCAL w Content API for Shopping pole legacy_local powinno być ustawione na wartość „true”.
Niedostępne	versionNumber	Nowe opcjonalne pole w ProductInput, które może służyć do zapobiegania nieprawidłowemu wstawianiu danych do podstawowych źródeł danych.
Pola typu string ze zdefiniowanym zestawem wartości	Pola typu enum ze zdefiniowanym zestawem wartości	Pola w atrybutach produktów ze zdefiniowanym zestawem wartości (np. excluded_destinations, availability) mają teraz typ enum.
gtin	productAttributes.gtins	Zmieniono z pojedynczego ciągu znaków (gtin) na powtarzający się ciąg znaków (gtins).
sizes	productAttributes.size	Zmieniono powtarzający się ciąg znaków (sizes) na pojedynczy ciąg znaków (size).
sizeType, additionalSizeType	productAttributes.sizeTypes	Zastąpiono sizeType i additionalSizeType powtarzanym typem wyliczeniowym SizeType (sizeTypes), który może mieć maksymalnie 2 wartości (np. ["PETITE", "MATERNITY"]).