Ändern

Google Ads-Skripts unterstützen allgemeine Mutate-Anfragen, die in der Google Ads API verfügbar sind. Die meisten Vorgänge, die über GoogleAdsService.mutate ausgeführt werden können, sind auch in Google Ads-Scripts 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 diese Funktion verwenden 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 Mutationsanfrage erstellen.

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 Funktionalität sehen Sie hier ein einfaches Beispiel, 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 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 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 für das Kampagnenbudget eine Liste aller gültigen Felder aufrufen und dann die entsprechenden Felder ausfüllen oder benutzerdefinierten JavaScript-Code in Ihr Script schreiben, um ein entsprechendes Objekt zu erstellen.

Alternativ können Sie einen Vorgang dynamisch mit der Funktion „Ausprobieren“ für das Kampagnenbudget erstellen. Damit können Sie einen 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 nach Angabe des Vorgangstyps Ihrem mutate-Aufruf hinzufügen.

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 im Snippet oben.

Entfernen

Geben Sie in Ihrem Vorgang remove 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 eine updateMask an, die genau angibt, welche Felder Sie in dieser Anfrage ändern möchten. Geben Sie den Ressourcennamen nicht in der 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"
    }
});

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 ein Beispiel für einen einfachen Ablauf, bei dem ein Ergebnis geprüft und einige Informationen in die Logs geschrieben werden:

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 Ändern mehrerer Vorgänge in einer einzigen Anfrage mit der Methode AdsApp.mutateAll. Sie können voneinander abhängige Entitäten, z. B. eine vollständige Kampagnenhierarchie, in einer einzigen Anfrage erstellen. Optional können Sie die gesamte Gruppe von Vorgängen atomar machen, sodass bei einem Fehler keiner der Vorgänge ausgeführt wird.

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 ausführliche Erläuterung zu temporären IDs und anderen Überlegungen finden Sie im Leitfaden zu den Best Practices für die Google Ads API. Beachten Sie, dass im 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-Scripts akzeptiert, sodass Sie Code direkt aus diesem Leitfaden kopieren können.

Wenn Sie mehrere Vorgänge in einer einzigen Anfrage ausführen möchten, fassen Sie alle Vorgänge in einem Array zusammen und rufen Sie dann AdsApp.mutateAll auf. Der Aufruf von 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 V26 angeben, wenn Sie eine andere Version als die Standardversion des Scripts verwenden möchten. Sie können jede zu diesem Zeitpunkt ö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 fehlgeschlagene Vorgänge geben Fehler zurück. Wenn der Wert auf false gesetzt ist und ein Vorgang fehlschlägt, werden keine Vorgänge ausgeführt. Dadurch wird diese Gruppe von Vorgängen atomar.

Hier ist ein Beispiel mit mehreren Vorgängen, bei dem ein Kampagnenbudget, eine Kampagne und eine Anzeigengruppe in einer atomaren Anfrage 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});