Änderung

Google Ads-Skripts unterstützen allgemeine Änderungen, die in der Google Ads API verfügbar sind. Die meisten Vorgänge, die über GoogleAdsService.mutate ausgeführt werden können, lassen sich auch in Google Ads-Skripts ausführen. Dazu gehört auch das Erstellen und Verwalten von Kampagnen.

Da diese Funktion den Zugriff auf einen so großen Teil der Google Ads API ermöglicht, ist es wichtig, dass Sie grundlegende Kenntnisse der Google Ads API-Konventionen kennen, um diese Funktion nutzen zu können. Viele Aspekte wie Entwicklertokens und Autorisierungen können übersprungen werden, da sie von Google Ads-Skripts automatisch übernommen werden. Sie müssen jedoch eine gültige Änderungsanfrage stellen.

Hier finden Sie einige grundlegende Ressourcen zur Google Ads API REST-Oberfläche, mit denen Sie vertraut sein sollten, bevor Sie mit diesem Leitfaden fortfahren:

Einfaches Beispiel

Die Funktionalität veranschaulicht dieses einfache Beispiel, bei dem ein Kampagnenbudget erstellt wird:

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

Ein Aufruf von AdsApp.mutate verwendet ein JSON-Objekt, das eine einzelne MutateOperation darstellt. Innerhalb dieses Objekts geben Sie an, welche Art von Vorgang ausgeführt werden soll – in diesem Fall campaignBudgetOperation. Anschließend geben Sie entweder create, remove oder sowohl update als auch updateMask an. Die spezifischen Felder in create und update hängen vom spezifischen Ressourcentyp ab, mit dem Sie arbeiten.

Vorgang erstellen

Es gibt verschiedene Strategien, mit denen Sie einen gültigen Vorgang erstellen können. Wenn Sie das Beispiel für das Kampagnenbudget beibehalten, können Sie in der REST-Referenzdokumentation für das Kampagnenbudget eine Liste aller gültigen Felder abrufen und dann die entsprechenden Felder ausfüllen oder benutzerdefinierten JavaScript-Code in Ihr Skript schreiben, um ein geeignetes Objekt zu erstellen.

Alternativ können Sie versuchen, mit der Funktion"Ausprobieren" für das Kampagnenbudget einen Vorgang dynamisch zu erstellen. Dabei können Sie einen Anfragetext dynamisch erstellen, indem Sie Felder auswählen, die Sie hinzufügen möchten. Anschließend können Sie 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 in Ihrem Vorgang create an und übergeben Sie die Objektdarstellung der Ressource, die Sie erstellen möchten.

Oben finden Sie ein Beispiel für den create-Vorgang.

Entfernen

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

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

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

Aktualisieren

Geben Sie in Ihrem Vorgang update an und übergeben Sie ein Objekt mit dem angegebenen Ressourcennamen, damit das System bestimmen kann, welches Objekt Sie aktualisieren möchten. Füllen Sie außerdem alle Felder aus, deren Werte Sie aktualisieren möchten, und geben Sie eine updateMask an, die genau angibt, welche Felder in dieser Anfrage geändert werden sollen. Geben Sie den Ressourcennamen nicht in die Aktualisierungsmaske an.

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.

Das folgende Beispiel zeigt einen grundlegenden Ablauf für die Überprüfung eines Ergebnisses und die Ausgabe einiger Informationen in den Logs:

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-Skripts unterstützen auch das Ändern mehrerer Vorgänge in einer einzelnen Anfrage mit der Methode AdsApp.mutateAll. Sie können voneinander unabhängige Entitäten erstellen, zum Beispiel eine vollständige Kampagnenhierarchie in einer einzelnen Anfrage. Sie können optional den gesamten Satz von Vorgängen atomar machen. Wenn also einer ausfällt, wird keiner ausgeführt.

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

Diese Funktion entspricht der Google Ads API-Funktion. In den Best Practices für die Google Ads API finden Sie eine ausführliche Erläuterung zu temporären IDs und weiteren Überlegungen. Im Leitfaden wird snake_case zur Darstellung von Feldnamen verwendet, in der Google Ads-Skriptdokumentation hingegen lowerCamelCase. Beide Fälle werden in Google Ads-Skripts akzeptiert, sodass Sie Code direkt aus dieser Anleitung kopieren können.

Wenn Sie mehrere Vorgänge in einer einzelnen Anfrage ausführen möchten, fassen Sie alle Vorgänge in einem Array zusammen und rufen Sie dann AdsApp.mutateAll auf. Beim mutateAll-Aufruf wird das Array der Vorgänge als erstes Argument und als optionales zweites Argument mit Optionen verwendet, einschließlich:

  • apiVersion: Wenn Sie eine andere Version als die Standardversion des Skripts verwenden möchten, können Sie eine benutzerdefinierte API-Version wie V16 angeben. Sie können jede öffentlich verfügbare Version zu diesem Zeitpunkt verwenden.
  • partialFailure: Der Standardwert in diesem Feld ist true. Wenn dieser Wert auf true gesetzt ist, werden gültige Vorgänge ausgeführt und fehlgeschlagene Vorgänge geben Fehler zurück. Wenn dieser Parameter auf false gesetzt ist, werden keine Vorgänge ausgeführt, wenn ein Vorgang fehlschlägt. Dadurch wird diese Gruppe von Vorgängen atomar.

Hier sehen Sie ein Beispiel mit mehreren Vorgängen, bei 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});