Wybór między plikami danych a interfejsem Merchant API

Dane produktów możesz przesyłać do Merchant Center za pomocą plików danych, interfejsu Merchant API lub kombinacji obu tych metod:

  • Pliki danych o produktach oparte na plikach: przesyłaj pliki CSV, TSV lub pliki XML za pomocą SFTP, Google Cloud Storage, Arkuszy Google lub zaplanowanego pobierania.
  • Merchant API: wysyłaj żądania automatyczne bezpośrednio z backendu, aby przeprowadzać aktualizacje przyrostowe w miarę zmian danych produktów, a także okresowo synchronizować cały katalog.

W tym przewodniku porównujemy oba podejścia, wyjaśniamy, kiedy używać jednego, a kiedy drugiego (lub obu jednocześnie), oraz udostępniamy szczegółowy przewodnik po migracji, jeśli zdecydujesz się przenieść niektóre lub wszystkie produkty z plików danych do interfejsu API.

Wybieranie podejścia do źródła danych

Oceń zmienność katalogu, architekturę backendu i przepływy pracy, aby zdecydować, czy używać interfejsu Merchant API, plików danych czy konfiguracji hybrydowej.

Kiedy używać interfejsu Merchant API

Użyj źródła danych interfejsu API, jeśli:

  • Bezpośrednia integracja z interfejsem API: wolisz wywoływać interfejs API bezpośrednio z backendu zamiast generować pliki i zarządzać potokami transferu plików (np. SFTP lub Google Cloud Storage).
  • Duża zmienność cen i stanu magazynowego: ceny produktów lub poziomy zapasów często zmieniają się w ciągu dnia.
  • Natychmiastowe aktualizacje po zmianie danych: chcesz wysyłać zmiany produktów do Google, gdy tylko pojawią się w Twoim backendzie, zamiast czekać na następne zaplanowane generowanie plików i przesłanie.
  • Przyrostowe aktualizacje katalogu: chcesz wstawiać, aktualizować lub usuwać poszczególne produkty w miarę ich zmian, bez konieczności ponownego przesyłania całego katalogu za każdym razem.
  • Częściowe aktualizacje atrybutów: chcesz zaktualizować określone pola produktu (takie jak price lub availability za pomocą productInputs.patch) bez ponownego wysyłania pełnych danych produktu.

Kiedy używać plików danych

Użyj podstawowego źródła danych opartego na pliku, jeśli:

  • Katalog statyczny: dane produktów zmieniają się rzadko (np. raz dziennie lub rzadziej).
  • Backend tylko ze zrzutami bez śledzenia zmian: backend eksportuje tylko pełne zrzuty katalogu i nie może śledzić zmian na poziomie produktu ani jawnych usunięć produktów.
  • Procesy oparte na arkuszach kalkulacyjnych: zespoły nietechniczne wybierają lub zastępują dane produktów bezpośrednio w Arkuszach Google lub plikach CSV.
  • Operacje wymagające niewielkiej konserwacji: wolisz zaplanowany eksport plików, w którym Merchant Center zajmuje się pobieraniem i przetwarzaniem migawek, zamiast integracji interfejsu API z tempem żądań, obsługą ponownych prób i okresową synchronizacją pełnego katalogu.

Kiedy używać obu tych opcji

Możesz połączyć pliki danych i interfejs Merchant API na tym samym koncie Merchant Center w tych sytuacjach:

  • Podzielone katalogi produktów: używasz interfejsu Merchant API w przypadku produktów, które szybko się zmieniają (np. wyprzedaże błyskawiczne lub asortyment o wysokiej rotacji), oraz plików danych w przypadku statycznych segmentów katalogu lub oddzielnych linii produktów. Upewnij się, że każdy produkt jest przesyłany tylko przez jedno podstawowe źródło danych (patrz Równoległe korzystanie i własność podstawowego źródła danych).
  • Podstawowe dane API z dodatkowymi plikami danych opartymi na plikach: zarządzasz podstawowymi danymi produktów za pomocą podstawowego źródła danych API, podczas gdy zespoły nietechniczne lub partnerzy zewnętrzni dostarczają dodatkowe atrybuty za pomocą dodatkowych plików danych opartych na plikach (takich jak Arkusze Google lub pliki CSV) połączonych z regułami atrybutów lub odwrotnie.
  • Częściowa lub etapowa migracja: przenosisz do interfejsu API określone rynki, kategorie lub subkonta, a resztę katalogu pozostawiasz w plikach danych.

Jeśli zdecydujesz się przenieść niektóre lub wszystkie produkty z plików danych do interfejsu Merchant API, postępuj zgodnie z instrukcjami podanymi w scenariuszu migracji krok po kroku.

Najważniejsze różnice architektoniczne

Pliki danych i interfejs Merchant API oparty na przesyłaniu różnią się sposobem, w jaki Google przetwarza dane produktów i nimi zarządza:

Pomysł Pliki danych Merchant API
Model integracji Zrzut pliku offline: eksportujesz katalog do pliku i przesyłasz go za pomocą SFTP, Google Cloud Storage, Arkuszy Google lub zaplanowanego pobierania. Bezpośrednia integracja zautomatyzowana: Twój backend wysyła żądania bezpośrednio do punktu końcowego interfejsu API.
Szczegółowość mutacji Przetwarzanie zbiorcze: zmiana jednego elementu zwykle wymaga ponownego przetworzenia całego pliku. Transakcje szczegółowe: możesz wstawiać, poprawiać lub usuwać tylko te produkty, które uległy zmianie.
Czas synchronizacji Synchronizacja zbiorcza: zmiany czekają w backendzie do następnego zaplanowanego cyklu eksportu i przesyłania plików. Połączenia natychmiastowe lub zaplanowane: możesz wysyłać zmiany przyrostowe natychmiast po ich wystąpieniu, a także okresowo przeprowadzać pełne synchronizacje.
Zachowanie usuwania Pośrednie (zdjęcie): każdy plik jest kompletnym zdjęciem. Usunięcie wiersza z pliku podstawowego powoduje usunięcie produktu. Jawne: nie ma koncepcji zrzutu. Aby usunąć wycofany produkt, wywołaj productInputs.delete.
Prezentacja zasobów Pojedynczy stan: wiersze pliku reprezentują nieprzetworzone dane wejściowe. Oddzielne dane nieprzetworzone i przetworzone: interfejs API dzieli dane na ProductInput (nieprzetworzone dane wejściowe) i Product (ostateczny stan przetworzony).
Reguły atrybutów (pliku danych) Zastosowane do kolumn nieprzetworzonego pliku w interfejsie Merchant Center. Obsługiwane w interfejsie Merchant Center. Wymagany podczas scalania danych interfejsu API z plikami dodatkowymi innych firm. Opcjonalny w przypadku przekształceń z jednego źródła, jeśli są one obsługiwane w backendzie.

Równoległe korzystanie i własność głównego źródła danych („ostatnia aktualizacja wygrywa”)

Chociaż możesz używać zarówno plików danych, jak i interfejsu API na tym samym koncie Merchant Center, zdecydowanie zalecamy używanie tylko jednej metody do przesyłania danego produktu.

Merchant Center działa w modelu „ostatnia aktualizacja wygrywa”. Podstawowe źródło danych (interfejs API lub plik danych), które przesłało najnowszy produkt, uzyskuje podstawowe prawo własności do danych tego produktu:

  • Gdy źródło danych w pliku jest właścicielem produktu: pominięcie produktu w kolejnym przesłanym pliku powoduje jego usunięcie z Merchant Center.
  • Gdy źródło danych interfejsu API jest właścicielem produktu: pominięcie produktu w przesłanym pliku nie ma wpływu, ponieważ plik danych nie jest już właścicielem produktu. Aby go usunąć, musisz wywołać metodę accounts.productInputs.delete.
  • Ryzyko przypadkowego ponownego przejęcia własności: jeśli zaktualizowany plik danych zostanie uruchomiony po przesłaniu danych przez interfejs API i będzie zawierał produkt, źródło danych pliku odzyska własność. Późniejsze pominięcie produktu w pliku spowoduje jego nieoczekiwane usunięcie.

Aby uniknąć nieoczekiwanego usunięcia lub utraty aktualizacji interfejsu API, nie przeprowadzaj jednoczesnych aktualizacji tych samych produktów za pomocą interfejsu API i podstawowych źródeł danych w pliku.

Najważniejsze kwestie dotyczące interfejsu API

Zanim zaczniesz implementację, zapoznaj się z tymi kluczowymi zachowaniami interfejsu Merchant API:

Elastyczne źródła danych (bez języka i etykiety)

W przeciwieństwie do plików danych, które wymagają wcześniejszego zdefiniowania konkretnej etykiety i języka docelowego pliku danych, interfejs Merchant API umożliwia tworzenie podstawowych źródeł danych bez określania atrybutu feedLabel lub contentLanguage.

  • Elastyczne przesyłanie: umożliwia przesyłanie produktów z dowolną kombinacją języka lub etykiety pliku danych do jednego źródła danych.
  • Uproszczone zarządzanie: nie musisz tworzyć osobnych źródeł danych dla każdego rynku docelowego ani nimi zarządzać. Uwaga: więcej informacji o wyborze strategii dotyczącej źródeł danych znajdziesz w artykule Wybieranie strategii dotyczącej źródeł danych.

Strategia synchronizacji i limity

W przeciwieństwie do pliku danych, w którym przesyłasz cały katalog w jednej partii, integrację z interfejsem Merchant API należy zaprojektować tak, aby obejmowała zarówno aktualizacje przyrostowe, jak i pełne synchronizacje:

  • Połącz aktualizacje przyrostowe z okresową pełną synchronizacją: wysyłaj żądania productInputs.insert lub productInputs.patch, gdy atrybuty produktów zmieniają się w backendzie. Poleganie wyłącznie na aktualizacjach przyrostowych może z czasem spowodować utratę synchronizacji danych, dlatego należy również okresowo przeprowadzać pełną synchronizację, aby uzgodnić katalog ze źródłem informacji (co powoduje też odświeżenie 30-dniowego okresu ważności produktu). Częstotliwość przeprowadzania pełnej synchronizacji zależy od rozmiaru katalogu i dostępnego limitu interfejsu API.
  • Dostosuj tempo wysyłania żądań do limitów interfejsu API: nie wywołuj interfejsu API dla wszystkich produktów naraz. Zmiany przyrostowe można wysyłać na bieżąco, ale żądania pełnej synchronizacji należy rozłożyć równomiernie w ciągu dnia, aby nie przekroczyć limitów wywołań metod na minutę i na dzień. Szczegółowe informacje znajdziesz w artykułach Limity i Częste aktualizowanie produktów.

Testowanie integracji

Przed przejściem do środowiska produkcyjnego sprawdź poprawność logiki integracji w bezpiecznym środowisku.

Używanie kont testowych

Zanim wprowadzisz zmiany w środowisku produkcyjnym, zalecamy wykonanie początkowych kroków migracji na koncie testowym w piaskownicy:

  1. Utwórz konto testowe: skonfiguruj odizolowane konto testowe, aby bezpiecznie eksperymentować bez wpływu na aktywne reklamy lub bezpłatne informacje.
  2. Tworzenie źródła danych interfejsu API: przećwicz tworzenie podstawowego źródła danych interfejsu API.
  3. Testowanie reguł atrybutów: sprawdzanie przekształceń danych i połączeń z plikami dodatkowymi.
  4. Sprawdzanie ładunków i kluczy produktów: prześlij przykładowe produkty, aby sprawdzić wielkość liter w SKU, kodowanie i obsługę błędów.

Szczegółowe informacje znajdziesz w artykule Krok 1. Utwórz konta testowe i w przewodniku Konta testowe.

Sprawdzanie zgodności klucza produktu

Upewnij się, że klucz produktu w automatyzacji jest dokładnie taki sam jak kody SKU w pliku danych. Google identyfikuje produkty, łącząc:

  • offerId (w plikach danych nazywany id, wielkość liter ma znaczenie)
  • contentLanguage (na przykład en)
  • feedLabel (na przykład US)

Znaki specjalne i kodowanie

Jeśli identyfikatory produktów zawierają znaki takie jak /, % lub ~, w wywołaniach interfejsu API użyj zakodowanego formatu (kodowanie base64url bez dopełnienia). Więcej informacji znajdziesz w artykule ProductInput.name.

Kontrola równoczesności

W przypadku integracji w czasie rzeczywistym aktualizacje mogą docierać w nieprawidłowej kolejności z powodu opóźnień sieci. Aby zapobiec zastępowaniu nowszych danych przez starsze aktualizacje, użyj pola versionNumber w zasobie ProductInput.

Szczegółowy przewodnik po migracji

Jeśli zdecydujesz się przenieść niektóre lub wszystkie produkty z plików danych do interfejsu Merchant API, postępuj zgodnie z tym przewodnikiem, aby przenieść produkty bez utraty wyświetleń i historii wyświetlania.

1. Przećwicz migrację na koncie testowym

Zanim wprowadzisz zmiany w środowisku produkcyjnym, utwórz konto testowe w piaskownicy za pomocą metody accounts.createTestAccount (patrz przewodnik Konta testowe). Konta testowe zapewniają odizolowane środowisko, w którym oferty są domyślnie zatwierdzane, weryfikacja domeny nie jest wymagana, a dane nigdy nie są udostępniane publicznie.

Użyj konta testowego, aby odzwierciedlić konfigurację produkcyjną i przećwiczyć migrację od początku do końca:

  1. Odzwierciedl konfigurację pliku danych: utwórz podstawowe źródło danych pliku (i wszelkie dodatkowe źródła danych) na koncie testowym i prześlij próbkę pliku danych produkcyjnych.
  2. Utwórz testowe źródło danych interfejsu API i reguły: utwórz podstawowe źródło danych interfejsu API i skonfiguruj wymagane reguły atrybutów lub połączenia z plikami dodatkowymi.
  3. Przetestuj przejęcie własności i dopasowanie kluczy: wyślij żądania productInputs.insert dotyczące przykładowych produktów i sprawdź, czy źródło danych interfejsu API przejmuje własność istniejących produktów bez tworzenia produktów zduplikowanych.
  4. Sprawdź aktualizacje i usunięcia: przetestuj częściowe aktualizacje za pomocą productInputs.patch i usunięcia za pomocą productInputs.delete, a następnie sprawdź wynikowe zasoby za pomocą products.get.

2. Tworzenie produkcyjnych źródeł danych interfejsu API

Zanim prześlesz dane, utwórz na koncie podstawowe źródło danych typu API.

Tworzenie podstawowego źródła danych interfejsu API

Aby utworzyć źródło danych, które akceptuje żądania push interfejsu API, wyślij żądanie POST do punktu końcowego dataSources. Więcej informacji znajdziesz w artykule Tworzenie podstawowego źródła danych o produktach.

3. Przenoszenie reguł atrybutów niestandardowych

Niestandardowe reguły atrybutów są powiązane z konkretnymi źródłami danych i nie są automatycznie przenoszone z pliku źródła danych do nowego źródła danych API.

Sposób przeniesienia reguł atrybutów zależy od ich celu:

  • Scalanie danych z różnych źródeł i dodatkowe pliki danych innych firm: jeśli łączysz podstawowe dane interfejsu API z zewnętrznymi dodatkowymi źródłami danych (takimi jak pliki dostawców zewnętrznych, arkusze kalkulacyjne asortymentu lub pliki danych o promocjach), musisz ponownie utworzyć reguły atrybutów w interfejsie Merchant Center i dołączyć je do nowego źródła danych interfejsu API. Wstępne przetwarzanie po stronie klienta nie może zastąpić reguł, które łączą dane z wielu niezależnych źródeł.
  • Przekształcenia danych z jednego źródła: w przypadku czyszczenia danych z jednego źródła, wartości domyślnych lub formatowania ciągów znaków w danych katalogu podstawowego wybierz jedną z tych opcji:
    • Przekształcenia backendu (zalecane): zastosuj przekształcenia we własnym systemie przed wywołaniem interfejsu API. Dzięki temu zyskujesz większą kontrolę programową, łatwiejsze testowanie i uproszczone debugowanie.
    • Reguły atrybutów Merchant Center: jeśli chcesz, aby Merchant Center nadal automatycznie zarządzało regułami przekształcania, odtwórz je dla nowego źródła danych interfejsu API w interfejsie Merchant Center.

4. Włączanie integracji z interfejsem API

Włącz integrację z produkcyjnym interfejsem API Products API, aby rozpocząć wstawianie, aktualizowanie i usuwanie produktów w nowym podstawowym źródle danych API:

  • Wstawianie i aktualizowanie produktów (przejęcie własności): wysyłaj żądania productInputs.insert i productInputs.patch z integracji. Gdy wstawisz produkt za pomocą interfejsu API z tym samym kluczem (offerId, contentLanguage, feedLabel) co istniejący produkt z pliku danych, źródło danych interfejsu API przejmie własność tego produktu i zachowa jego historię wyświetlania. Więcej informacji znajdziesz w artykułach Wstawianie produktu oraz Dodawanie produktów i zarządzanie nimi.

  • Usuwanie wycofanych produktów: skonfiguruj integrację tak, aby wywoływała metodę productInputs.delete za każdym razem, gdy produkt zostanie usunięty z katalogu.

  • Wdrażaj stopniowo: w przypadku dużych katalogów włączaj integrację po jednym subkoncie Merchant Center lub po jednym źródle danych naraz.

  • Skonfiguruj równoczesność: jeśli wysyłasz wiele żądań, skonfiguruj klienta tak, aby obsługiwał żądania równoczesne i zarządzał wieloma połączeniami. Zapoznaj się z przewodnikiem Refaktoryzacja kodu pod kątem żądań równoczesnych.

5. Wstrzymywanie aktualizacji źródła danych z pliku

Gdy integracja z interfejsem API będzie aktywna, zatrzymaj aktualizacje plików przed następnym zaplanowanym uruchomieniem pliku, aby źródło danych pliku nie zastąpiło aktualizacji interfejsu API:

  1. Przestań przesyłać nowe pliki do lokalizacji SFTP/FTP, Google Cloud Storage lub Arkuszy Google.
  2. W interfejsie Merchant Center otwórz źródło danych pliku i wstrzymaj zaplanowane pobieranie.
  3. Dotychczasowe produkty należące do źródła danych pliku pozostaną aktywne przez maksymalnie 30 dni, dopóki nie zostaną wstawione przez integrację z interfejsem API.

6. Poczekaj na zakończenie migracji i sprawdź jej wyniki

Poczekaj, aż wszystkie aktywne produkty zostaną przeniesione ze źródła danych pliku do źródła danych interfejsu API. Aktualizacje przyrostowe przenoszą produkty w miarę ich zmian, ale uruchomienie stopniowej pełnej synchronizacji katalogu za pomocą zwykłej integracji przyspiesza migrację całego katalogu (patrz Strategia synchronizacji i limity).

Na tym etapie:

  1. W interfejsie Merchant Center możesz sprawdzać liczbę produktów. Poczekaj, aż liczba źródeł danych z pliku zmniejszy się do 0, a liczba źródeł danych z interfejsu API będzie odpowiadać aktywnemu katalogowi.
  2. Użyj products.get, aby sprawdzić, czy atrybuty i reguły atrybutów niestandardowych są scalane zgodnie z oczekiwaniami.
  3. Monitoruj narzędzie Diagnostyka interfejsu API w interfejsie Merchant Center, aby śledzić odsetek błędów i wydajność interfejsu API.

7. Wycofanie źródła danych pliku

Po zakończeniu przenoszenia i gdy liczba elementów w pliku danych wynosi 0:

  1. Sprawdź, czy aktualizacje są odzwierciedlane w czasie rzeczywistym.
  2. Usuń starsze źródło danych pliku w interfejsie Merchant Center, aby zapobiec przypadkowemu zastąpieniu danych interfejsu API przez aktualizacje oparte na plikach.
Wstecz
Migrate Local Inventory Ads settings