Zmiana obiektów

Jak opisano w przewodniku po strukturze interfejsu API, każdy zasób najwyższego poziomu w interfejsie Google Ads API ma odpowiadającą mu usługę, która obsługuje modyfikowanie instancji zasobu. Możesz też użyć metody GoogleAdsService.Mutate, aby w jednym żądaniu zmienić niepodzielnie wiele typów zasobów.

W tym przewodniku używamy CampaignService, aby zademonstrować modyfikowanie obiektów Campaign, ale te same koncepcje mają zastosowanie do wszystkich innych usług związanych z typami zasobów.

Żądania modyfikacji

Każda usługa powiązana z określonym typem zasobu ma metodę mutate, która akceptuje żądanie modyfikacji. To żądanie składa się z:

• customer_id (lub customerId w adresach URL REST)
• Kolekcja: operations
• Opcjonalne ustawienia wykonywania, takie jak partial_failure, validate_only i response_content_type (które określają, czy po mutacji zwracany jest zasób zmienny czy tylko nazwa zasobu).

Na przykład metoda MutateCampaigns obiektu CampaignService akceptuje obiekt MutateCampaignsRequest, który składa się z:

• customer_id
• Kolekcja obiektów: CampaignOperation (operations)
• Opcjonalne ustawienia wykonywania (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 pola operation. To pole jest polem oneof, które składa się z tych atrybutów:

create

Tworzy nową instancję zasobu.

update

Aktualizuje zasób, aby pasował do atrybutów zasobu update. Jeśli to pole jest ustawione, musisz też ustawić pole update_mask operacji, które informuje interfejs Google Ads API, które atrybuty mają zostać zmodyfikowane podczas operacji aktualizacji. Każda biblioteka klienta zawiera narzędzie maski pola lub metodę pomocniczą, która generuje obiekt update_mask.

remove

Usuwa zasób określony przez ciąg znaków nazwy zasobu (np. customers/1234567890/campaigns/987654321).

Pole operation jest polem typu oneof, więc nie możesz użyć pojedynczej operacji do zmodyfikowania wielu obiektów. Jeśli na przykład chcesz utworzyć jedną kampanię i usunąć inną, dodaj do żądania 2 wystąpienia CampaignOperation: jedno z ustawionym polem create, a drugie z ustawionym polem remove.

Operacje wsadowe

Chociaż pojedyncza operacja może tylko utworzyć, zaktualizować lub usunąć pojedynczy zasób, pojedyncze żą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 pojedyncze żądanie MutateCampaignsRequest zawierające 10 obiektów CampaignOperation. Aby pogrupować operacje na różnych typach zasobów w jedno żądanie, użyj GoogleAdsService.Mutate lub zasobów mutujących.

Odpowiedzi na mutacje

To, co zostanie zwrócone w odpowiedzi, zależy od tego, co zostało wysłane w polu response_content_type żądania modyfikacji. Jeśli na przykład podasz MUTABLE_RESOURCE, odpowiedź będzie zawierać zarówno resource_name zasobu, jak i zmienne pola kampanii w campaign. Domyślnie (RESOURCE_NAME_ONLY) w każdym obiekcie MutateCampaignResult wypełniane jest tylko pole resource_name.

Błędy mutacji

Domyślnie (partial_failure = false) operacje w żądaniu modyfikacji są stosowane na koncie 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 (tych z polem partial_failure w komunikacie żądania), ustawienie partial_failure = true powoduje zatwierdzenie prawidłowych operacji, a operacje zakończone niepowodzeniem zwracają błędy związane z operacją w polu partial_failure_error odpowiedzi. Szczegółowe informacje o obsłudze błędów znajdziesz w przewodniku po częściowych niepowodzeniach i przewodniku po typowych błędach.

Śledzenie zmian

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

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

Aby wysłać zapytanie do tych zasobów, użyj metody GoogleAdsService.SearchStream lub GoogleAdsService.Search. Dowiedz się więcej o strumieniowym przesyłaniu raportów za pomocą GoogleAdsService.