Migracja usług

Merchant API to bardziej niezawodny i intuicyjny sposób zarządzania danymi produktów. Główna zmiana polega na rozdzieleniu danych produktów na 2 osobne 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.

Ten przewodnik omawia najważniejsze różnice, które pomogą Ci przenieść integrację z Content API for Shopping. Szczegółowy przewodnik po korzystaniu 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. Aby wstawiać, aktualizować i usuwać dane produktów, możesz użyć zasobu ProductInput. Możesz użyć zasobu tylko do odczytu Product, aby wyświetlić ostateczny produkt po przetworzeniu przez Google Twoich danych wejściowych, zastosowaniu reguł i połączeniu danych ze źródeł dodatkowych.

• Kodowanie nazw produktów: w przypadku pól ProductInput.name i Product.name możesz użyć 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. Musisz na przykład zakodować nazwy produktów, jeśli zawierają one 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 określone dane wejściowe produktu. Jest to znaczące ulepszenie w porównaniu z Content API for Shopping, w przypadku którego aktualizacje mogły być nieoczekiwanie zastępowane przez inne przesłane pliki danych. W Merchant API aktualizacja pozostaje do momentu ponownego zaktualizowania lub usunięcia danego produktu. Aktualizacje produktów są stosowane do zasobu ProductInput, a nie do przetworzonego zasobu Product.

• Wybierz źródło danych, aby ułatwić zarządzanie danymi: wszystkie operacje zapisu productInputswymagają teraz parametru zapytania dataSource, co sprawia, że jest jasne, 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 przez zasób RESTful name zamiast pola id. Format to accounts/{account}/products/{product}.

• Brak niestandardowych partii: 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.

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 przypadku jednego kanału gRPC, ponieważ zarządza wieloma połączeniami bazowymi. Więcej informacji znajdziesz w artykule Refaktoryzacja kodu na potrzeby żądań współbieżnych: zwiększanie przepustowości za pomocą pul kanałów

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

Kluczowe pojęcie: „Kradzież oferty” ma miejsce, gdy produkt zidentyfikowany za pomocą unikalnego klucza (language, feedlabel, offerID) jest wstawiany do innego podstawowego źródła danych niż to, do którego należy. Spowoduje 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 podany nieprawidłowy dataSource.

Zanim przeprowadzisz migrację źródeł 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:

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

• Konsolidowanie i używanie źródeł danych dla dowolnej etykiety źródła danych i języka: Merchant API umożliwia tworzenie źródła danych bez określania etykiety źródła danych i języka, a tym samym wstawianie 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 dowolnej etykiety i dowolnego języka.

• Chroń swoje produkty: jeśli używasz reguł źródła danych, wywołaj products.get w celu znalezienia dokładnego dataSource powiązanego z produktem przed jego zaktualizowaniem lub usunięciem. Dzięki temu masz pewność, że modyfikujesz właściwe źródło, i zapobiegasz przypadkowemu przejęciu oferty.

Uwaga: podczas wywoływania interfejsu Merchant API w przypadku tego samego produktu używaj tego samego offerId co w przypadku Content API for Shopping, aby nie utracić historii produktu. Sprawdź też 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ś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}
Uzyskiwanie 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
Zbiorcze przesyłanie 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 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 name zasobu REST. Format: accounts/{account}/products/{product}, gdzie {product} to contentLanguage~feedLabel~offerId. Przykład: accounts/12345/products/en~US~sku123. Kodowanie: zalecane jest kodowanie base64url bez dopełnienia, a w przypadku identyfikatorów produktów zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresie URL jest ono obowiązkowe.

Uwaga: pole channel nie występuje już w Merchant API. W przypadku produktów z atrybutem LOCALkanał w Content API for Shopping należy ustawić wartość legacy_local na „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	Zawiera listę gotowych, przetworzonych produktów.
products.insert	productInputs.insert	Wstawia dane wejściowe produktu. Wymaga subskrypcji 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 subskrypcji dataSource.
products.custombatch	Niedostępne	Używaj żądań asynchronicznych lub grupuj żądania HTTP.
productstatuses.get	products.get	Usługa productstatuses zostanie usunięta. Informacje o stanie są teraz częścią zasobu Product.
productstatuses.list	products.list	Usługa productstatuses zostanie 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

W tej tabeli znajdziesz 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 zawierających znaki używane przez Merchant API lub znaki zarezerwowane w adresie 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 w zasobach Product i ProductInput. Zapewnia to bardziej przejrzystą i uporządkowaną strukturę zasobów.
targetCountry	feedLabel	Nazwa zasobu używa teraz znaku 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. Używaj wartości legacy_local w przypadku produktów dostępnych tylko lokalnie.	Pola channel nie ma już w Merchant API. W przypadku produktów z atrybutem LOCAL kanał w Content API for Shopping należy ustawić wartość legacy_local na „true”.
Niedostępne	versionNumber	Nowe pole opcjonalne w ProductInput, które może być używane, aby zapobiegać wstawianiu danych w nieprawidłowej kolejności do podstawowych źródeł danych.
string pola typu ze zdefiniowanym zbiorem wartości,	enum pola typu ze zdefiniowanym zbiorem wartości,	Pola w atrybutach produktów z określonym zestawem wartości (np. excluded_destinations, availability) mają teraz typ enum.