Änderung

Google Ads-Skripts unterstützen generische Mutationen, die in der Google Ads API verfügbar sind. Die meisten Vorgänge, die mit GoogleAdsService.mutate ausgeführt werden können, sind auch in Google Ads-Skripts möglich, einschließlich des Erstellens und Verwaltens von Kampagnen.

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

Hier sind 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
      }
    }
  });

Ein Aufruf von AdsApp.mutate verwendet ein JSON-Objekt, das eine einzelne MutateOperationdarstellt. In diesem Objekt geben Sie an, welche Art von Vorgang Sie ausführen – in diesem Fall eine 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 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 nach dem Kampagnenbudget suchen, um eine Liste aller gültigen Felder zu sehen. Füllen Sie dann die entsprechenden Felder aus oder schreiben Sie benutzerdefinierten JavaScript-Code in Ihrem Skript, um ein geeignetes Objekt zu erstellen.

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

Ein Beispiel für den Vorgang create finden Sie im zuvor bereitgestellten Snippet.

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 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 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 eine updateMask an, die 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"
    }
});

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 ist ein Beispiel für einen grundlegenden 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-Skripts unterstützen auch das Mutieren mehrerer Vorgänge in einer einzigen Anfrage mit der AdsApp.mutateAll Methode. Sie können Entitäten, die voneinander abhängig sind, z. B. eine vollständige Kampagnenhierarchie, in einer einzigen Anfrage erstellen. Optional können Sie den gesamten Satz von Vorgängen atomar machen. Wenn also ein Vorgang fehlschlägt, werden keine Vorgänge ausgeführt.

Der Rückgabewert ist ein Array von MutateResult Objekten, eines für jeden von Ihnen bereitgestellten 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 der temporären IDs und anderer Überlegungen finden Sie im Leitfaden zu Best Practices für die Google Ads API. Beachten Sie, dass im Leitfaden snake_case verwendet wird, um Feldnamen darzustellen, während in der Google Ads-Skriptdokumentation lowerCamelCase verwendet wird. Beide Schreibweisen werden in Google Ads-Skripts akzeptiert, sodass Sie Code direkt aus diesem Leitfaden kopieren können.

Wenn Sie mehrere Vorgänge in einer einzigen Anfrage ausführen möchten, erfassen Sie alle Vorgänge in einem Array und rufen Sie dann AdsApp.mutateAll auf. Der Aufruf mutateAll 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 V24 angeben, wenn Sie eine andere Version als die Standardskriptversion verwenden möchten. Sie können jede öffentlich verfügbare Version verwenden.
  • partialFailure: Dieses Feld ist standardmäßig auf true gesetzt. Wenn es auf true gesetzt ist, werden gültige Vorgänge ausgeführt und bei fehlgeschlagenen Vorgängen werden Fehler zurückgegeben. Wenn es auf false gesetzt ist, werden bei einem Fehler keine Vorgänge ausgeführt. Dadurch wird dieser Satz von Vorgängen effektiv 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});