Änderung

Google Ads-Skripts 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, lassen sich auch in Google Ads-Scripts ausführen, einschließlich des Erstellens und Verwaltens von Kampagnen.

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

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

Einfaches Beispiel

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

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

Bei einem Aufruf von AdsApp.mutate wird ein JSON-Objekt verwendet, das ein einzelnes MutateOperation darstellt. In diesem Objekt geben Sie an, welche Art von Vorgang Sie ausführen – in diesem Fall ein campaignBudgetOperation. Anschließend geben Sie entweder create, remove oder beides an: update und updateMask. Die genauen Felder in create und update hängen vom jeweiligen Ressourcentyp ab, mit dem Sie arbeiten.

Vorgang erstellen

Es gibt verschiedene Strategien, mit denen Sie einen gültigen Vorgang erstellen können. Wenn Sie beim Beispiel für das Kampagnenbudget bleiben, können Sie in der REST-Referenzdokumentation für das Kampagnenbudget eine Liste aller gültigen Felder aufrufen 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 einen Vorgang dynamisch erstellen, indem Sie die Funktion „Try this“ für das Kampagnenbudget verwenden. Damit lässt sich ein Anfragetext dynamisch erstellen, indem Sie die gewünschten Felder auswählen. Anschließend können Sie den Inhalt des Vorgangs aus dem generierten Ergebnis extrahieren und ihn 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 Vorgang 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, deren Werte Sie aktualisieren möchten, und geben Sie einen updateMask an, der genau angibt, welche Felder Sie in dieser Anfrage ändern möchten. Der Ressourcenname darf nicht in der Aktualisierungsmaske enthalten sein.

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"
    }
});

Ergebnisse verarbeiten

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 welche Fehler aufgetreten sind.

Hier ist ein Beispiel für einen einfachen Ablauf zum Prüfen eines Ergebnisses und zum Ausgeben 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-Scripts unterstützen auch das Ausführen mehrerer Vorgänge in einer einzelnen Anfrage mit der Methode AdsApp.mutateAll. Sie können voneinander abhängige Einheiten wie eine vollständige Kampagnenhierarchie in einer einzigen Anfrage erstellen. Optional können Sie den gesamten Satz von Vorgängen atomar machen. Wenn ein Vorgang fehlschlägt, 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 ursprünglichen Vorgänge.

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

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. Der mutateAll-Aufruf verwendet das Array von Vorgängen als erstes Argument und ein optionales zweites Argument mit Optionen, darunter:

  • apiVersion: Sie können eine benutzerdefinierte API-Version wie V20 angeben, wenn Sie eine andere Version als die Standardskriptversion verwenden möchten. Sie können jederzeit eine öffentlich verfügbare Version verwenden.
  • partialFailure: Der Standardwert für dieses Feld ist true. Wenn der Wert auf true gesetzt ist, werden gültige Vorgänge ausgeführt und bei fehlgeschlagenen Vorgängen werden Fehler zurückgegeben. Wenn der Wert auf false gesetzt ist und ein Vorgang fehlschlägt, werden keine Vorgänge ausgeführt. Diese Gruppe von Vorgängen ist dann atomar.

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