Ä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 den 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-Oberfläche der Google Ads API, mit denen Sie vertraut sein 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. Innerhalb dieses Objekts geben Sie an, welche Art von Vorgang Sie ausführen – in diesem Fall eine 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 das Kampagnenbudget finden Sie eine Liste aller gültigen Felder. Sie können diese dann ausfüllen oder benutzerdefinierten JavaScript-Code in Ihr Script schreiben, um ein entsprechendes Objekt zu erstellen.

Alternativ können Sie versuchen, mithilfe der Funktion „Testen“ für das Kampagnenbudget einen Vorgang dynamisch zu erstellen. Dabei wird der Anfragetext dynamisch erstellt, indem Sie die Felder auswählen, die Sie hinzufügen möchten. 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 im Vorgang update 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. Nehmen Sie den Ressourcennamen nicht in die Aktualisierungsmaske auf.

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 Mutation 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 erstellen, z. B. eine vollständige Kampagnenhierarchie in einer einzelnen Anfrage. 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 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 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 akzeptiert das Array von Vorgängen als erstes Argument und ein optionales zweites Argument mit Optionen. Dazu gehören:

  • apiVersion: Sie können eine benutzerdefinierte API-Version wie V18 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 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, 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});