Większość zasobów jest modyfikowana (utworzona, aktualizowana lub usuwana) za pomocą metody Mutate
. Metoda Mutate
jest wywoływana jako HTTP POST
na adres URL dla określonego zasobu, który pasuje do wzorca nazwy zasobu, bez końcowego identyfikatora zasobu.
Identyfikatory zasobów, których dotyczy mutacja, 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 do mutacji kampanii, pomiń końcowy identyfikator zasobu i dołącz :mutate
:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/campaigns:mutate
Wiadomość Mutate
zawiera obiekt JSON najwyższego poziomu z tablicą operations
, która może zawierać wiele obiektów operation
. Z kolei każda operacja może być jedną z tych operacji: create
, update
lub remove
. To jedyne możliwe operacje mutacji.
POST /v17/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. W przewodniku Limity systemu znajdują się informacje o ograniczeniach wielkości żądań.
Operacje w ramach pojedynczego żądania do interfejsu API są domyślnie wykonywane jako 1 zestaw działań, co oznacza, że albo wszystkie udają się razem, albo cały wsad kończy się niepowodzeniem w przypadku niepowodzenia jednej z operacji. Niektóre usługi obsługują atrybut partialFailure
, który zmienia to działanie. Bardziej szczegółowe informacje o semantyce operacji mutacji znajdziesz w artykule Mutowanie zasobów.
Utwórz
Operacje tworzenia tworzą nowe encje i muszą zawierać pełną reprezentację zasobu w formacie JSON, który chcesz utworzyć.
POST /v17/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": {} } } ] }
Zaktualizuj
Operacje aktualizacji wykonują rozproszone aktualizacje istniejącego zasobu. Wystarczy, że określisz pola, które chcesz zmodyfikować.
Aby określić pola, które chcesz zaktualizować, w atrybucie updateMask
ustaw listę nazw pól oddzielonych przecinkami. Jest to szczególnie przydatne, jeśli masz już w pełni uformowaną reprezentację obiektu JSON (na przykład zwrócona przez poprzednie wywołanie interfejsu API), ale chcesz zmienić tylko niektóre pola.
Zamiast przycinać obiekt JSON, możesz po prostu podać nazwy pól do modyfikacji w updateMask
i wysłać cały obiekt JSON.
W przykładzie poniżej zmieniamy wartości name
i status
istniejącej kampanii, która ma podaną wartość resourceName
.
POST /v17/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ń
Operacje usuwają skutecznie obiekt, zmieniając jego stan w Google Ads na REMOVED
. Wymagany jest tylko resourceName
do usunięcia.
POST /v17/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" } ] }