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"
}
]
}