Änderung

Google Ads-Scripts unterstützen generische Mutationen, die in der Google Ads API verfügbar sind. Die meisten Vorgänge, die über GoogleAdsService.mutate ausgeführt werden können, können auch in Google Ads-Scripts ausgeführt werden, z. B. das Erstellen und Verwalten von Kampagnen.

Da diese Funktion Zugriff auf einen so großen Teil der Google Ads API ermöglicht, ist es wichtig, die Google Ads API-Konventionen zu kennen, um sie verwenden zu können. Viele Aspekte können übersprungen werden, z. B. Entwicklertokens und Autorisierung, da diese von Google Ads-Scripts für Sie verarbeitet werden. Sie müssen jedoch eine gültige Änderungsanfrage stellen.

Hier finden Sie einige grundlegende Ressourcen zur REST-Schnittstelle der Google Ads API, mit denen Sie sich vertraut machen sollten, bevor Sie mit diesem Leitfaden fortfahren:

Einfaches Beispiel

Zur Veranschaulichung der Funktionsweise sehen Sie sich dieses einfache Beispiel an, in dem ein Kampagnenbudget erstellt wird:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

Ein Aufruf von AdsApp.mutate erfordert ein JSON-Objekt, das ein einzelnes MutateOperation darstellt. In diesem Objekt geben Sie an, welche Art von Vorgang Sie ausführen, in diesem Fall einen campaignBudgetOperation. Geben Sie dann entweder create, remove oder sowohl update als auch updateMask an. Die spezifischen Felder in create und update hängen von der Art der Ressource ab, mit der Sie arbeiten.

Vorgang erstellen

Es gibt verschiedene Strategien, mit denen Sie einen gültigen Vorgang erstellen können. Angenommen, Sie möchten ein Kampagnenbudget erstellen. In der REST-Referenzdokumentation für Kampagnenbudgets finden Sie eine Liste aller gültigen Felder. Sie können diese Felder dann ausfüllen oder benutzerdefinierten JavaScript-Code in Ihr Script schreiben, um ein entsprechendes Objekt zu erstellen.

Alternativ können Sie mit der Funktion „Probieren Sie das aus“ für das Kampagnenbudget einen Vorgang dynamisch erstellen. Dabei können Sie den Anfragetext dynamisch erstellen, indem Sie auswählen, welche Felder hinzugefügt werden sollen. Sie können dann den Inhalt des Vorgangs aus dem generierten Ergebnis extrahieren und Ihrem mutate-Aufruf hinzufügen, nachdem Sie den Vorgangstyp angegeben haben.

Vorgangsarten

Erstellen

Geben Sie create in Ihrem Vorgang an und übergeben Sie eine Objektdarstellung der Ressource, die Sie erstellen möchten.

Ein Beispiel für den Befehl create finden Sie oben.

Entfernen

Geben Sie remove in Ihrem Vorgang an und übergeben Sie den Ressourcennamen der Ressource, die Sie entfernen möchten, z. B.:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Wenn Sie den Ressourcennamen für eine Entität nicht kennen, können Sie ihn mit einer Adsapp.search-Anfrage abrufen.

Aktualisieren

Geben Sie update in Ihrem Vorgang an und übergeben Sie ein Objekt mit dem angegebenen Ressourcennamen, damit das System ermitteln kann, welches Objekt Sie aktualisieren möchten. Füllen Sie außerdem alle Felder aus, für die Sie die Werte aktualisieren möchten, und geben Sie einen updateMask an, der genau angibt, welche Felder Sie in dieser Anfrage ändern möchten. Fügen Sie den Ressourcennamen nicht in die Aktualisierungsmaske ein.

Beispiel für einen update-Vorgang:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Umgang mit Ergebnissen

Unabhängig vom Vorgangstyp ist der Rückgabewert ein MutateResult. Mit dem zurückgegebenen Ressourcennamen können Sie den aktuellen Status der Ressource nach der Änderung abfragen und prüfen, ob der Vorgang erfolgreich war oder ob Fehler aufgetreten sind.

Hier ein Beispiel für einen einfachen Ablauf zum Prüfen eines Ergebnisses und zum Drucken einiger Informationen in die Protokolle:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Mehrere Vorgänge

Google Ads-Scripts unterstützen auch die Änderung mehrerer Vorgänge in einer einzelnen Anfrage mit der Methode AdsApp.mutateAll. Sie können voneinander abhängige Entitäten in einer einzigen Anfrage erstellen, z. B. eine vollständige Kampagnenhierarchie. Optional können Sie den gesamten Satz von Vorgängen atomar machen, sodass bei einem Fehler keiner ausgeführt wird.

Der Rückgabewert ist ein Array von MutateResult-Objekten, eines für jeden angegebenen Vorgang und in derselben Reihenfolge wie die ursprünglichen Vorgänge.

Diese Funktion funktioniert genauso wie die Funktion in der Google Ads API. Eine vollständige Erklärung zu temporären IDs und anderen Aspekten finden Sie im Leitfaden zu Best Practices für die Google Ads API. Beachten Sie, dass in diesem Leitfaden snake_case für Feldnamen verwendet wird, während in der Dokumentation zu Google Ads-Scripts lowerCamelCase verwendet wird. Beide Varianten sind in Google Ads-Scripts zulässig. Sie können den Code also direkt aus diesem Leitfaden kopieren.

Wenn Sie mehrere Vorgänge in einer einzigen Anfrage ausführen möchten, legen Sie alle Vorgänge in einem Array ab und rufen Sie dann AdsApp.mutateAll auf. Der mutateAll-Aufruf nimmt das Array mit den Vorgängen als erstes Argument und ein optionales zweites Argument mit Optionen an, darunter:

  • apiVersion: Sie können eine benutzerdefinierte API-Version wie V19 angeben, wenn Sie eine andere Version als die Standardversion der Scripts verwenden möchten. Sie können jede öffentlich verfügbare Version verwenden.
  • partialFailure: Der Standardwert für dieses Feld ist true. Wenn der Wert auf true festgelegt ist, werden gültige Vorgänge ausgeführt und fehlgeschlagene Vorgänge geben Fehler zurück. Wenn der Wert auf false festgelegt ist und ein Vorgang fehlschlägt, werden keine Vorgänge ausgeführt. Dieser Vorgangssatz ist dann atomar.

Hier ein Beispiel mit mehreren Vorgängen, mit denen in einer atomaren Anfrage ein Kampagnenbudget, eine Kampagne und eine Anzeigengruppe erstellt werden:

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});