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 odpowiednią usługę specyficzną dla typu zasobu, która obsługuje modyfikowanie instancji zasobu. Możesz też użyć GoogleAdsService.Mutate, aby w ramach jednego żądania atomowo zmieniać wiele typów zasobów.

W tym przewodniku do demonstrowania modyfikowania obiektów Campaign używamy CampaignService, ale te same koncepcje mają zastosowanie do wszystkich innych usług specyficznych dla typu zasobu.

Żądania modyfikacji

Każda usługa dotycząca określonego typu zasobu ma metodę mutate, która akceptuje żądanie mutate. Żądanie składa się z tych elementów:

• znak 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 zwracany jest zmienny zasób, czy tylko jego nazwa).

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

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

Operacje

Obiekt operacji, np. CampaignOperation, umożliwia określenie działania, które chcesz wykonać na pojedynczym zasobie, przez ustawienie jego pola operation. To pole jest oneofpolem, które zawiera te atrybuty:

create

Tworzy nową instancję zasobu.

update

Aktualizuje zasób, aby był zgodny z atrybutami zasobu update. Gdy to pole jest ustawione, musisz też ustawić update_mask operacji, które informuje interfejs Google Ads API, które atrybuty należy zmodyfikować podczas operacji aktualizacji. Każda biblioteka klienta zawiera narzędzie do maskowania pól lub metodę pomocniczą, która generuje update_maskza 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 ustawioną wartością create i drugą z ustawioną wartością remove.

Operacje wsadowe

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

Jeśli na przykład chcesz utworzyć 10 kampanii, wyślij jeden MutateCampaignsRequest z 10 obiektami CampaignOperation. Aby zgrupować operacje na różnych typach zasobów w jednym żądaniu, użyj GoogleAdsService.Mutate lub zasobów zmieniających.

Odpowiedzi dotyczące zmiany

To, co jest zwracane w odpowiedzi, zależy od tego, co zostało wysłane w polu response_content_type żądania modyfikacji. Jeśli np. podano MUTABLE_RESOURCE, odpowiedź zawiera zarówno resource_name zasobu, jak i pola kampanii, które można zmieniać, w campaign. Domyślnie (RESOURCE_NAME_ONLY) w każdym elemencie MutateCampaignResult wypełniany jest tylko atrybut 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ń mutate, które obsługują częściowe niepowodzenie (czyli tych, które w wiadomości żądania mają pole partial_failure), ustawienie wartości partial_failure = true powoduje zatwierdzenie prawidłowych operacji, a operacje, które się nie powiodły, zwracają w polu partial_failure_error odpowiedzi błędy specyficzne dla operacji. Szczegółowe informacje o obsłudze błędów znajdziesz w przewodniku dotyczącym częściowych błędów i przewodniku dotyczącym typowych błędów.

Śledzenie zmian

Aby śledzić zmiany wprowadzane w obiektach na koncie Google Ads lub pobierać ich bieżący stan, możesz używać 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 strumieniowaniu raportów za pomocą GoogleAdsService.