Zmiana obiektów

Jak wspomnieliśmy w przewodniku po strukturze interfejsu API, każdy zasób najwyższego poziomu w interfejsie Google Ads API ma odpowiadającą mu usługę specyficzną dla typu zasobu, która umożliwia modyfikowanie instancji zasobu. Możesz też użyć GoogleAdsService.Mutate, aby modyfikować wiele typów zasobów w sposób niepodzielny w jednym żądaniu.

W tym przewodniku używamy CampaignService aby pokazać, jak modyfikować obiekty Campaign, ale te same zasady obowiązują w przypadku wszystkich innych usług specyficznych dla typu zasobu.

Żądania modyfikacji

Każda usługa specyficzna dla typu zasobu ma metodę mutate, która akceptuje żądanie modyfikacji. To żądanie składa się z tych elementów:

  • customer_id (lub customerId w adresach URL REST),
  • kolekcja operations,
  • opcjonalne ustawienia wykonania, takie jak partial_failure, validate_only i response_content_type (które określają, czy po modyfikacji ma zostać zwrócony modyfikowalny zasób, czy tylko jego nazwa).

Na przykład metoda MutateCampaigns usługi CampaignService akceptuje MutateCampaignsRequest, który składa się z tych elementów:

  • customer_id,
  • kolekcja obiektów CampaignOperation (operations),
  • opcjonalne ustawienia wykonania (partial_failure, validate_only i response_content_type wskazujące preferowany typ odpowiedzi).

Operacje

Obiekt operacji, taki jak CampaignOperation, umożliwia określenie działania, które chcesz wykonać na pojedynczym zasobie, przez ustawienie jego pola operation. To pole jest oneof polem składającym się z tych atrybutów:

create
Tworzy nową instancję zasobu.
update
Aktualizuje zasób, aby pasował do atrybutów zasobu update. Gdy to pole jest ustawione, musisz też ustawić update_mask operacji, która informuje interfejs Google Ads API, które atrybuty mają zostać zmodyfikowane podczas operacji aktualizacji. Każda biblioteka klienta zawiera narzędzie do maskowania pól lub metodę pomocniczą , która generuje update_mask za Ciebie.
remove
Usuwa zasób określony przez ciąg nazwy zasobu (np. customers/1234567890/campaigns/987654321).

Ponieważ pole operation jest polem oneof, nie możesz użyć jednej operacji do zmodyfikowania wielu obiektów. Jeśli na przykład chcesz utworzyć jedną kampanię i usunąć inną, dodaj do żądania 2 instancje CampaignOperation: jedną z ustawionym polem create i drugą z ustawionym polem remove.

Operacje wsadowe

Chociaż pojedyncza operacja może tylko utworzyć, zaktualizować lub usunąć pojedynczy zasób, jedno żądanie modyfikacji może zawierać wiele operacji. Zamiast wysyłać wiele żądań modyfikacji, z których każde zawiera pojedynczą operację, połącz operacje w jedno żądanie modyfikacji.

Jeśli na przykład chcesz utworzyć 10 kampanii, wyślij jedno żądanie MutateCampaignsRequest, które zawiera 10 obiektów CampaignOperation. Aby pogrupować operacje dotyczące różnych typów zasobów w jednym żądaniu, użyj GoogleAdsService.Mutate lub modyfikowania zasobów.

Odpowiedzi na żądania modyfikacji

To, co jest zwracane w odpowiedzi, zależy od tego, co zostało wysłane w polu response_content_type żądania modyfikacji. Jeśli na przykład określono MUTABLE_RESOURCE, to odpowiedź zawiera zarówno resource_name zasobu, jak i modyfikowalne pola kampanii w campaign. Domyślnie (RESOURCE_NAME_ONLY) w każdym MutateCampaignResult wypełniana jest tylko resource_name.

Błędy modyfikacji

Domyślnie (partial_failure = false) operacje w żądaniu modyfikacji są stosowane do Twojego konta Google Ads tylko wtedy, gdy każda operacja w żądaniu zakończy się powodzeniem. Jeśli jakakolwiek operacja się nie powiedzie, całe żądanie zostanie wycofane. W przypadku żądań modyfikacji, które obsługują częściowe niepowodzenie (czyli tych, które mają pole partial_failure w wiadomości żądania), ustawienie partial_failure = true powoduje zatwierdzenie prawidłowych operacji, a nieudane operacje zwracają błędy specyficzne dla operacji w polu partial_failure_error odpowiedzi. Więcej informacji o obsłudze błędów znajdziesz w przewodniku dotyczącym częściowego niepowodzenia i przewodniku dotyczącym typowych błędów.

Śledzenie zmian

Aby śledzić zmiany wprowadzane w obiektach na koncie Google Ads lub pobierać bieżący stan obiektów, możesz użyć zasobów change_status i change_event.

  • change_status zawiera podsumowanie, które zasoby uległy zmianie w danym okresie.
  • change_event zawiera szczegółową historię zmian, w tym stare i nowe wartości zmienionych pól.

Aby wysyłać zapytania do tych zasobów, użyj metody GoogleAdsService.SearchStream lub GoogleAdsService.Search. Więcej informacji o strumieniowaniu raportów za pomocą GoogleAdsService.

Wstecz
Obsługa wersji
Dalej
Pobieram obiekty