Die meisten Ressourcen werden mit einer Mutate-Methode geändert (erstellt, aktualisiert oder entfernt). Die Methode Mutate wird als HTTP-POST zu einer ressourcenspezifischen URL aufgerufen, die mit dem Muster des Ressourcennamens übereinstimmt, ohne nachgestellte Ressourcen-ID.
Die IDs der zu ändernden Ressourcen werden stattdessen im JSON-Anfragetext gesendet. Auf diese Weise können Sie einen einzelnen API-Aufruf senden, der mehrere Vorgänge für verschiedene Ressourcen enthält.
Der Ressourcenname einer Kampagne hat beispielsweise folgendes Format:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Um die URL für mutierende Kampagnen abzuleiten, lassen Sie die nachgestellte Ressourcen-ID weg und fügen Sie :mutate an:
https://googleads.googleapis.com/v17/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 einen der folgenden Werte haben: create, update oder remove. Dies sind die einzig möglichen mutate-Vorgänge.
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": [
...
]
}
Die meisten Dienste unterstützen Tausende von Vorgängen in einem einzigen API-Aufruf. Im Leitfaden zu Systemlimits werden 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 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ührliche Informationen zur Semantik von mutate-Vorgängen finden Sie unter Ressourcen stummschalten.
Erstellen
Mit Erstellungsvorgängen werden neue Entitäten erzeugt. Sie müssen eine vollständige JSON-Darstellung der Ressource enthalten, die Sie erstellen möchten.
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": {}
}
}
]
}
Aktualisieren
Aktualisierungsvorgänge führen dünnbesetzte Aktualisierungen für eine vorhandene Ressource aus. Sie müssen nur die Felder angeben, die Sie ändern möchten.
Wenn Sie die Felder angeben möchten, die Sie aktualisieren möchten, legen Sie für das Attribut updateMask eine durch Kommas getrennte Liste von Feldnamen fest. Dies ist besonders nützlich, wenn Sie bereits eine vollständige JSON-Darstellung eines Objekts haben (wie bei 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 dem angegebenen resourceName geändert.
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",
}
}
]
}
Entfernen
Mit Entfernungsvorgängen wird ein Objekt effektiv gelöscht und sein Google Ads-Status auf REMOVED gesetzt. Nur das zu entfernende resourceName ist erforderlich.
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"
}
]
}