Większość zasobów jest modyfikowana (tworzona, aktualizowana lub usuwana) za pomocą metody Mutate
. Metoda Mutate
jest wywoływana jako POST
HTTP do adresu URL określonego zasobu, który pasuje do wzorca nazwy zasobu bez identyfikatora zasobu na końcu.
Identyfikatory zasobów, które mają być objęte mutacją, są wysyłane w treści żądania JSON. Dzięki temu możesz wysłać jedno wywołanie interfejsu API, które zawiera wiele operacji na różnych zasobach.
Na przykład nazwa zasobu kampanii ma taki format:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Aby uzyskać adres URL używany na potrzeby mutacji kampanii, pomiń końcowy identyfikator zasobu i dołącz :mutate
:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/campaigns:mutate
Komunikat Mutate
zawiera obiekt JSON najwyższego poziomu z tablicą operations
, który może zawierać wiele obiektów operation
. Każda operacja może mieć jedną z tych wartości: create
, update
lub remove
. To jedyne możliwe
operacje mutacji.
POST /v16/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ ... ] }
Większość usług obsługuje tysiące operacji w jednym wywołaniu interfejsu API. Ograniczenia dotyczące rozmiarów żądań opisaliśmy w sekcji Ograniczenia systemu.
Operacje w ramach pojedynczego żądania do interfejsu API są domyślnie wykonywane jako jeden zestaw działań, co oznacza, że wszystkie kończą się sukcesem razem lub cały wsad kończy się niepowodzeniem, jeśli któraś operacja się nie powiedzie. Niektóre usługi obsługują atrybut partialFailure
, który pozwala zmienić to działanie. Więcej informacji o semantyce operacji zmiany znajdziesz w artykule o zmienianiu zasobów.
Utwórz
Operacje tworzenia generują nowe encje i muszą zawierać pełną reprezentację JSON zasobu, który chcesz utworzyć.
POST /v16/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "create": { "name": "An example campaign", "status": "PAUSED", "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID", "advertisingChannelType": "SEARCH", "networkSettings": { "targetGoogleSearch": true, "targetSearchNetwork": true, "targetContentNetwork": true, "targetPartnerSearchNetwork": false }, "target_spend": {} } } ] }
Aktualizuj
Operacje aktualizacji przeprowadzają rzadkie aktualizacje istniejących zasobów. Musisz tylko określić pola, które chcesz zmodyfikować.
Aby określić pola, które chcesz zaktualizować, ustaw atrybut updateMask
jako listę nazw pól oddzielonych przecinkami. Jest to szczególnie przydatne, gdy masz już pełną reprezentację obiektu w formacie JSON (np. zwrot z poprzedniego wywołania interfejsu API), ale chcesz zmienić tylko niektóre pola.
Zamiast przycinać obiekt JSON, możesz po prostu podać nazwy pól do zmodyfikowania w updateMask
i wysłać cały obiekt JSON.
W poniższym przykładzie zmienia się name
i status
w istniejącej kampanii, która ma podany parametr resourceName
.
POST /v16/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Usuń
Usuwanie operacji powoduje efektywne usunięcie obiektu i ustawienie jego stanu w Google Ads na REMOVED
. Wymagany jest tylko identyfikator resourceName
do usunięcia.
POST /v16/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }