Die meisten Ressourcen werden mit der Methode Mutate
geändert (erstellt, aktualisiert oder entfernt). Die Methode Mutate
wird als HTTP-POST
zu einer ressourcenspezifischen URL aufgerufen, die dem Muster für den Ressourcennamen entspricht, ohne die nachgestellte Ressourcen-ID.
Die IDs der zu ändernden Ressourcen werden stattdessen im JSON-Anfragetext gesendet. So können Sie einen einzelnen API-Aufruf senden, der mehrere Vorgänge für verschiedene Ressourcen enthält.
Der Ressourcenname einer Kampagne hat beispielsweise das folgende Format:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Um die URL zum Ändern von Kampagnen abzuleiten, lassen Sie die nachgestellte Ressourcen-ID weg und hängen Sie :mutate
an:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/campaigns:mutate
Eine Mutate
-Nachricht enthält ein JSON-Objekt der obersten Ebene mit einem operations
-Array, das viele operation
-Objekte enthalten kann. Jeder Vorgang kann wiederum create
, update
oder remove
sein. Dies sind die einzig möglichen mutate-Vorgänge.
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": [ ... ] }
Die meisten Dienste unterstützen Tausende von Vorgängen in einem einzigen API-Aufruf. Im Leitfaden zu Systemlimits sind die Beschränkungen für Anfragegrößen dokumentiert.
Vorgänge innerhalb einer einzelnen API-Anfrage werden standardmäßig als eine Gruppe von Aktionen ausgeführt. Das bedeutet, dass sie entweder alle gemeinsam erfolgreich sind oder der gesamte Batch fehlschlägt, wenn ein einzelner Vorgang fehlschlägt. Einige Dienste unterstützen ein partialFailure
-Attribut, um dieses Verhalten zu ändern. Ausführlichere Informationen zur Semantik von mutate-Vorgängen finden Sie unter Ressourcen zusammenführen.
Erstellen
Bei Erstellungsvorgängen werden neue Entitäten erzeugt und müssen eine vollständige JSON-Darstellung der Ressource enthalten, die Sie erstellen möchten.
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": {} } } ] }
Aktualisieren
Aktualisierungsvorgänge führen dünnbesetzte Aktualisierungen einer vorhandenen Ressource aus. Sie müssen nur die Felder angeben, die Sie ändern möchten.
Legen Sie für das Attribut updateMask
eine durch Kommas getrennte Liste von Feldnamen fest, um die Felder anzugeben, die Sie aktualisieren möchten. Dies ist besonders nützlich, wenn Sie bereits eine vollständige JSON-Darstellung eines Objekts haben (z. B. wie von einem vorherigen API-Aufruf zurückgegeben), aber nur bestimmte Felder ändern möchten.
Anstatt das JSON-Objekt zu bereinigen, können Sie einfach die zu ändernden Feldnamen in der updateMask
auflisten und das gesamte JSON-Objekt senden.
Im folgenden Beispiel werden name
und status
einer vorhandenen Kampagne mit der angegebenen resourceName
geändert.
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", } } ] }
Entfernen
Beim Entfernen wird ein Objekt effektiv gelöscht. Daher wird sein Google Ads-Status auf REMOVED
gesetzt. Nur das zu entfernende resourceName
ist erforderlich.
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" } ] }