Die meisten Ressourcen werden mit einer Mutate-Methode geändert (erstellt, aktualisiert oder entfernt). Die Mutate-Methode wird als HTTP-POST auf eine ressourcenspezifische URL aufgerufen, die dem Muster für den Ressourcennamen entspricht, ohne die abschließende Ressourcen-ID.
Die IDs der zu mutierenden Ressourcen werden stattdessen im JSON-Anfragetext gesendet. So können Sie einen einzelnen API-Aufruf senden, der mehrere Vorgänge auf verschiedenen Ressourcen enthält.
Der Ressourcenname einer Kampagne hat beispielsweise folgendes Format:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Um die URL abzuleiten, die zum Ändern von Kampagnen verwendet wird, lassen Sie die abschließende Ressourcen-ID weg und fügen Sie :mutate an:
https://googleads.googleapis.com/v19/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 einer der folgenden Werte sein: create, update oder remove. Das sind die einzigen möglichen Mutaionsvorgänge.
POST /v19/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. In der Anleitung zu Systemlimits werden die Einschränkungen für die Anfragegröße beschrieben.
Vorgänge innerhalb einer einzelnen API-Anfrage werden standardmäßig als eine Reihe von Aktionen ausgeführt. Das bedeutet, dass sie entweder alle erfolgreich sind oder der gesamte Batch fehlschlägt, wenn ein einzelner Vorgang fehlschlägt. Einige Dienste unterstützen das Attribut partialFailure, um dieses Verhalten zu ändern. Weitere Informationen zur Semantik von Mutate-Vorgängen finden Sie unter Ressourcen mutieren.
Erstellen
Erstellevorgänge erzeugen neue Entitäten und müssen eine vollständige JSON-Darstellung der zu erstellenden Ressource enthalten.
POST /v19/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
Bei Aktualisierungsvorgängen werden nur einzelne Elemente einer vorhandenen Ressource aktualisiert. Sie müssen nur die Felder angeben, die Sie ändern möchten.
Um die Felder anzugeben, die Sie aktualisieren möchten, legen Sie für das Attribut updateMask eine durch Kommas getrennte Liste von Feldnamen fest. Das ist besonders nützlich, wenn Sie bereits eine vollständige JSON-Darstellung eines Objekts haben (z. B. von einem vorherigen API-Aufruf zurückgegeben), aber nur bestimmte Felder ändern möchten.
Anstatt das JSON-Objekt zu kürzen, können Sie einfach die zu ändernden Feldnamen in updateMask auflisten und das gesamte JSON-Objekt senden.
Im folgenden Beispiel werden die name und status einer bestehenden Kampagne mit der angegebenen resourceName geändert.
POST /v19/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
Durch das Entfernen wird ein Objekt effektiv gelöscht und sein Google Ads-Status auf REMOVED gesetzt. Es ist nur die zu entfernende resourceName erforderlich.
POST /v19/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" } ] }