Migracja usług

Interfejs Merchant API wprowadza bardziej niezawodny i intuicyjny sposób zarządzania danymi produktów. Główna zmiana polega na rozdzieleniu danych produktów na 2 odrębne zasoby: ProductInput do przesyłania danych i Product do wyświetlania ostatecznej, przetworzonej wersji, w tym stanu produktu i problemów. Ta nowa struktura zapewnia bardziej przewidywalne i przejrzyste działanie.

Z tego przewodnika dowiesz się o najważniejszych różnicach, które pomogą Ci przenieść integrację z Content API for Shopping. Szczegółowy przewodnik dotyczący korzystania z nowych funkcji znajdziesz w artykule Zarządzanie produktami.

Najważniejsze różnice

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

• Osobne zasoby dla danych wejściowych i przetworzonych: Merchant API dzieli zarządzanie produktami na 2 zasoby. Za pomocą zasobu ProductInput możesz wstawiać, aktualizować i usuwać dane produktów. Za pomocą zasobu tylko do odczytu Product możesz wyświetlać ostateczny produkt 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 Merchant API lub znaki zarezerwowane w adresach URL, kodowanie jest obowiązkowe. Nazwy produktów musisz zakodować, jeśli zawierają one którykolwiek z tych znaków:

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

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

• Przewidywalne aktualizacje produktów: nowa productInputs.patch metoda bezpośrednio modyfikuje konkretne dane wejściowe produktu. Jest to znaczące 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 ponownej aktualizacji lub usunięcia konkretnych danych wejściowych produktu. Aktualizacje produktów są stosowane do ProductInput zasobu, a nie do przetworzonego Product zasobu.

• Wybierz źródło danych, aby ułatwić zarządzanie danymi: wszystkie productInputs operacje zapisu 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 wiele źródeł danych.

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

• Brak niestandardowych partii: metoda custombatch nie jest już dostępna. Aby wysłać wiele żądań w jednym wywołaniu HTTP, możesz użyć asynchronicznych żądań lub grupowania HTTP.

Wskazówka: zwiększ przepustowość dzięki pulom kanałów. Skonfiguruj pulę kanałów, aby zmaksymalizować przepustowość w przypadku operacji zbiorczych. Pozwala to ominąć typowy limit 100 strumieni w jednym kanale gRPC, zarządzając wieloma połączeniami bazowymi. Więcej informacji znajdziesz w artykule Refaktoryzacja kodu pod kątem równoczesnych żądań: zwiększanie przepustowości dzięki pulom kanałów.

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

Kluczowe pojęcie: „kradzież oferty” występuje, gdy produkt zidentyfikowany za pomocą unikalnego klucza (language, feedlabel, offerID) jest wstawiany do innego głównego źródła danych niż to, do którego należy. Powoduje to usunięcie produktu ze starego źródła i przeniesienie go do nowego, w którym mogą obowiązywać inne reguły źródła danych i ustawienia własności. Kradzież może być używana celowo do reorganizacji produktów, ale może też wystąpić przypadkowo, jeśli podczas wstawiania zostanie podane nieprawidłowe źródło danych dataSource.

Zanim przeprowadzisz migrację źródeł danych, zdecydowanie zalecamy wybranie strategii źródła danych .

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

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

• Konsoliduj i używaj źródeł danych dla dowolnej etykiety i języka: Merchant API umożliwia utworzenie źródła danych bez określania etykiety i języka, a tym samym wstawianie produktów z dowolną etykietą i językiem źródła danych. Rozważ użycie jednego źródła danych dla dowolnej etykiety i języka.

• Chroń swoje produkty: jeśli używasz reguł źródła danych, przed zaktualizowaniem lub usunięciem produktu wywołaj products.get , aby znaleźć dokładne dataSource powiązane z produktem. Dzięki temu masz pewność, że modyfikujesz zamierzone źródło, i zapobiegasz przypadkowej kradzieży oferty.

Uwaga: aby nie utracić historii produktu, podczas wywoływania Merchant API używaj tego samego offerId co w przypadku Content API for Shopping. Zapoznaj się też z sekcją Identyfikatory na tej stronie.

Żą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świetlanie listy produktów	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Wstawianie produktu	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}
Pobieranie 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 listy 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 HTTP

Identyfikatory

Format identyfikatorów produktów w 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 oddzielonych 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 zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresach URL.

Uwaga: Pole channel nie jest już dostępne w Merchant API. W przypadku produktów z kanałem LOCAL w Content API for Shopping należy ustawić pole legacy_local na wartość true.

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 parametru dataSource.
products.update	productInputs.patch	Działanie jest znacznie inne. Aktualizuje konkretne dane wejściowe produktu i jest trwałe.
products.delete	productInputs.delete	Usuwa konkretne dane wejściowe produktu. Wymaga parametru dataSource.
products.custombatch	Niedostępne	Używaj żądań asynchronicznych lub grupowania 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 HTTP.

Szczegółowe zmiany pól

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

Content API for Shopping	Merchant API	Opis
id	name	Głównym identyfikatorem produktu jest teraz nazwa zasobu REST name. Kodowanie base64url bez dopełnienia jest zalecane i obowiązkowe w przypadku nazw produktów zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresach URL.
Atrybuty specyfikacji danych produktów najwyższego poziomu (np. title, price, link)	Obiekt productAttributes	Atrybuty produktów, takie jak title, price i link, nie są już polami najwyższego poziomu. Są one teraz zgrupowane w obiekcie productAttributes w zasobach Product i ProductInput. Zapewnia to czystszą i bardziej uporządkowaną strukturę zasobów.
targetCountry	feedLabel	Nazwa zasobu używa teraz parametru feedLabel zamiast targetCountry, aby była zgodna z funkcjami Merchant Center.
feedId	dataSource (parametr zapytania)	Nazwa dataSource jest teraz wymaganym parametrem zapytania we wszystkich metodach zapisu productInputs (insert, update, delete).
channel	Niedostępne. W przypadku produktów dostępnych tylko lokalnie użyj parametru legacy_local.	Pole channel nie jest już dostępne w Merchant API. W przypadku produktów z kanałem LOCAL w Content API for Shopping należy ustawić pole legacy_local na wartość true.
Niedostępne	versionNumber	Nowe opcjonalne pole w ProductInput, które można wykorzystać do zapobiegania wstawianiu do głównych źródeł danych w nieprawidłowej kolejności.
Pola typu string z określonym zestawem wartości	Pola typu enum z określonym zestawem wartości	Pola w atrybutach produktów z określonym zestawem wartości (np. excluded_destinations, availability) są teraz typu enum.