Codestruktur

Sie haben bereits alles für Ihren ersten API-Aufruf eingerichtet und die Konfigurationselemente kennengelernt, die für Aufrufe an die API erforderlich sind.

In diesem Leitfaden beschäftigen wir uns mit der Struktur eines typischen Codebeispiels für die AdWords API.

Dann zeigen wir anhand einiger häufiger Anwendungsfälle, wie Sie mithilfe der Codebeispiele praktisch jede API-Funktion in Ihre Anwendung integrieren können.

Aufbau eines API-Codebeispiels

Die mit den Clientbibliotheken bereitgestellten Codebeispiele decken die gebräuchlichsten API-Funktionen ab. Die meisten Back-End-Aufgaben werden damit automatisch erledigt und die Entwicklung von AdWords API-Anwendungen wird erheblich erleichtert.

Sehen wir uns die typische Struktur eines Codebeispiels für die AdWords API einmal an. Klicken Sie dazu unten auf den Tab für die von Ihnen verwendete Programmiersprache.

Java

Öffnen Sie in Ihrer IDE die im vorherigen Leitfaden verwendete Beispieldatei: GetCampaigns.java.

Dort sehen Sie in main Boilerplate-Code, der folgende Aufgaben erfüllt:

  • Anmeldedaten generieren
  • AdWords-Sitzung erstellen
  • AdWords-Dienste instanziieren

Sinn und Zweck werden deutlich, wenn Sie sich die Codebeispiele in der Clientbibliothek ansehen.

Im GetCampaigns-Beispiel gibt es eine weitere Zeile, die Sie möglicherweise benötigen: Im vorherigen Leitfaden haben wir die Client-Kundennummer in der Datei "ads.properties" festgelegt.

Was tun Sie aber, wenn es in Ihrem Verwaltungskonto viele Client-Kundenkonten gibt? In diesem Fall können Sie die Client-Kundennummer aus der Datei "ads.properties" entfernen und sie programmatisch über das AdWords-Sitzungsobjekt festlegen. Nach dem Erstellen des Objekts rufen Sie setClientCustomerID auf, um sie dynamisch festzulegen.

// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(oAuth2Credential)
    .build();

session.setClientCustomerID("123-456-7890");

AdWordsServices adWordsServices = new AdWordsServices();

runExample(adWordsServices, session);

C#

Öffnen Sie in Ihrer IDE die im vorherigen Leitfaden verwendete Beispieldatei: GetCampaigns.cs.

In main sehen Sie Boilerplate-Code, der auf AdWordsUser verweist:
public static void Main(string[] args) {
    GetCampaigns codeExample = new GetCampaigns();
    Console.WriteLine(codeExample.Description);
    try {
      codeExample.Run(new AdWordsUser());
    }
}

Die wichtigsten Klassen in der C#-Bibliothek sind die AdsUser-Klassen. Diese kapseln typischerweise ein einzelnes Anzeigenkonto, in diesem Fall ein AdWords-Konto.

Mit der AdWordsUser-Klasse lässt sich eine vorkonfigurierte Dienstklasse erstellen, die zur Ausführung von API-Aufrufen verwendet werden kann. Dabei wird auf die in der Datei app.config Ihrer Anwendung angegebenen Einstellungen zurückgegriffen.

// Create a new AdWordsUser with the App.config settings.
AdWordsUser user = new AdWordsUser();

Was tun Sie aber, wenn es in Ihrem Verwaltungskonto viele Client-Kundenkonten gibt? In diesem Fall ist die programmatische Festlegung über die Config-Property des AdsUser-Objekts möglich, um den Nutzer zur Laufzeit zu konfigurieren:

// Create a default AdWordsUser instance. If any configuration
// is available in App.config, those will be used.
AdWordsUser user = new AdWordsUser();

// Override a specific setting at runtime.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

Eine weitere Möglichkeit besteht darin, den Konstruktor zu verwenden, der eine AdWordsAppConfig-Instanz akzeptiert. Beispiel:

// Create a config object with the values in App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Override any specific setting you wish to change.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Python

Öffnen Sie in Ihrer IDE die im vorherigen Leitfaden verwendete Beispieldatei: get_campaigns.py.

In dem Beispiel geht aus den Kommentaren hervor, dass bei der Methode LoadFromStorage Anmeldedaten und Properties aus der Datei googleads.yaml entnommen werden. Im vorherigen Leitfaden haben wir die Client-Kundennummer in googleads.yaml festgelegt. Bei der Methode LoadFromStorage wird standardmäßig im Stammverzeichnis nach einer Datei mit diesem Namen gesucht. Sie können allerdings auch den Pfad zu einer beliebigen Datei mit dem korrekten yaml-Inhalt übergeben:

Standardspeicherort verwenden – Ihr Stammverzeichnis:

adwords_client = adwords.AdWordsClient.LoadFromStorage()

Speicherort der Datei übergeben:

adwords_client = adwords.AdWordsClient.LoadFromStorage('C:\My\Directory\googleads.yaml')

Was tun Sie aber, wenn es in Ihrem Verwaltungskonto viele Client-Kundenkonten gibt? In diesem Fall können Sie mit dem folgenden Code programmatisch die Client-Kundennummer zur Laufzeit festlegen:

adwords_client = AdWordsClient.LoadFromStorage()
adwords_client.SetClientCustomerId('123-456-7890')

PHP

Öffnen Sie in Ihrer IDE die Beispieldatei GetCampaigns.php.

Zuerst wird damit ein OAuth-Token generiert:

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

Dann wird mit dem Token eine API-Sitzung erstellt, in der die runExample()-Funktion ausgeführt wird:

// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdWordsSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();
self::runExample(new AdWordsServices(), $session);

runExample() ist in diesem Beispiel die primäre Funktion. Damit werden mithilfe eines Selektors die Kampagnen-IDs und -namen aus CampaignService abgerufen.

Perl

Öffnen Sie in Ihrer IDE die im vorherigen Leitfaden verwendete Beispieldatei: get_campaigns.pl.

In dem Beispiel gibt es Code, durch den Anmeldedaten aus der Konfigurationsdatei adwords.properties abgerufen werden:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});

Im vorherigen Leitfaden haben wir die Client-Kundennummer in der Datei "adwords.properties" festgelegt.

Was tun Sie aber, wenn es in Ihrem Verwaltungskonto viele Client-Kundenkonten gibt? In diesem Fall können Sie die Client-Kundennummer aus adwords.properties entfernen und sie durch Aufrufen von set_client_id programmatisch festlegen:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});
$client->set_client_id("123-456-7890");

Ruby

Öffnen Sie in Ihrer IDE die im vorherigen Leitfaden verwendete Beispieldatei: get_campaigns.rb.

Dort sehen Sie in main Boilerplate-Code, durch den Anmeldedaten aus der Konfigurationsdatei adwords_api.yml abgerufen werden.

  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

Im Beispiel gibt es eine weitere Zeile, die Sie möglicherweise benötigen: Im vorherigen Leitfaden haben wir die Client-Kundennummer in der Konfigurationsdatei "adwords_api.yml" festgelegt.

Was tun Sie aber, wenn es in Ihrem Verwaltungskonto viele Client-Kundenkonten gibt? In diesem Fall können Sie die Client-Kundennummer aus der Datei "adwords_api.yml" entfernen und sie programmatisch über das AdWords-Sitzungsobjekt festlegen. Nach dem Erstellen des Objekts rufen Sie zur programmatischen Festlegung adwords.config.set auf.

# Set a new CID value
adwords.config.set("authentication.client_customer_id", "123-456-7890")

Auf Codebeispiele zugreifen

Sie finden alle Codebeispiele für die AdWords API auf der Seite Clientbibliotheken und Codebeispiele. Durch die Beispiele sind die wichtigsten Einsatzbereiche der API-Funktionen abgedeckt:

  • Kontoverwaltung
  • Kampagnenverwaltung
  • Fehlerbehandlung
  • Optimierung
  • Berichte
  • Ausrichtung

Sie kennen jetzt die Struktur eines typischen Codebeispiels für die AdWords API. Nun wenden wir uns einigen Anwendungsfällen zu, die veranschaulichen, wie sich die Codebeispiele für nahezu alle API-Funktionen nutzen lassen.

Die beiden wichtigsten Anwendungsbereiche der API-Funktionen sind Berichte und Automatisierung. Beginnen wir mit Berichten.

Codebeispiele für Berichte verwenden

Wir beginnen mit einem Codebeispiel, das einen Kriterien-Leistungsbericht herunterlädt:

Java

Öffnen Sie DownloadCriteriaReport.java in Ihrer IDE.

In main sehen Sie den Boilerplate-Code, den Sie bereits kennen:

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

Allerdings enthält die RunExample-Methode den interessanten Code in dieser Klasse. Hier erstellen wir eine Objekthierarchie, die den gewünschten Bericht definiert:

// Create report definition.
    ReportDefinition reportDefinition = new ReportDefinition();
    reportDefinition.setReportName("Criteria performance report #" + System.currentTimeMillis());
    reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.YESTERDAY);
    reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);
    reportDefinition.setDownloadFormat(DownloadFormat.CSV);

Die Definition wird dann an eine Instanz von ReportDownloader übergeben:

 ReportDownloadResponse response =
          new ReportDownloader(session).downloadReport(reportDefinition);
      response.saveToFile(reportFile);

Führen Sie nun DownloadCriteriaReport.java aus.

In der IDE-Konsole wird der Speicherort der heruntergeladenen Datei ausgegeben.

Im Beispielcode ist ein Berichtstyp angegeben, in diesem Fall ein Kriterien-Leistungsbericht.

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

Außerdem sind Felder angegeben, die für den Bericht abgerufen werden sollen:

Selector selector = new Selector();
    selector.getFields().addAll(Lists.newArrayList("CampaignId",
        "AdGroupId",
        "Id",
        "CriteriaType",
        "Criteria",
        "FinalUrls",
        "Impressions",
        "Clicks",
        "Cost"));

C#

Öffnen Sie DownloadCriteriaReport.cs in Ihrer IDE.

Hier wird der gleiche Boilerplate-Code wie im vorherigen Beispiel verwendet. Er übernimmt die Authentifizierung, indem er Werte aus der Datei app.config abruft:

public static void Main(string[] args) {
  GetCampaigns codeExample = new GetCampaigns();
  Console.WriteLine(codeExample.Description);
  try {
    codeExample.Run(new AdWordsUser());
  }
}

In diesem Beispiel ist jedoch insbesondere der Code interessant, mit dem eine Objekthierarchie erstellt wird, die den gewünschten Bericht definiert:

public void Run(AdWordsUser user, string fileName) {
  ReportDefinition definition = new ReportDefinition() {
    reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT",
        reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,
        downloadFormat = DownloadFormat.GZIPPED_CSV,
        dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS,
  }
}

Führen Sie nun DownloadCriteriaReport.cs aus.

In der Konsole wird der Speicherort der heruntergeladenen Datei ausgegeben.

Im Beispielcode ist ein Berichtstyp angegeben, in diesem Fall ein Kriterien-Leistungsbericht.

reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,

Außerdem sind Felder angegeben, die für den Bericht abgerufen werden sollen:

selector = new Selector() {
  fields = new string[] {"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria",
      "FinalUrls", "Clicks", "Impressions", "Cost"},
      predicates = new Predicate[] {
        Predicate.In("Status", new string[] {"ENABLED", "PAUSED"})
      }
}

Python

Öffnen Sie download_criteria_report_with_selector.py in Ihrer IDE.

Hier wird der gleiche Boilerplate-Code wie im vorherigen Beispiel verwendet. Er übernimmt die Authentifizierung, indem er Werte aus der Konfigurationsdatei googleads.yaml abruft:

adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

In diesem Beispiel ist jedoch insbesondere der Code interessant, mit dem eine Objekthierarchie erstellt wird, die den gewünschten Bericht definiert:

# Create report definition.
report = {
    'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
    'dateRangeType': 'LAST_7_DAYS',
    'reportType': 'CRITERIA_PERFORMANCE_REPORT',
    'downloadFormat': 'CSV',
    'selector': {
        'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                   'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']
    }
}

Die Definition wird dann an eine Instanz von ReportDownloader übergeben:

report_downloader.DownloadReport(
    report, sys.stdout, skip_report_header=False, skip_column_header=False,
    skip_report_summary=False)

Führen Sie nun download_criteria_report_with_selector.py aus.

In der Konsole wird der Speicherort der heruntergeladenen Datei ausgegeben.

Im Beispielcode ist ein Berichtstyp angegeben, in diesem Fall ein Kriterien-Leistungsbericht.

Außerdem sind im Abschnitt "selector" auch einige Felder angegeben, die für den Bericht abgerufen werden sollen, z. B. "CampaignId" oder "AdGroupId".

PHP

Öffnen Sie DownloadCriteriaReportWithSelector.php in Ihrer IDE.

Das Beispiel enthält den Standardcode für die Authentifizierung und Erstellung einer AdWords-Sitzung. In der primären Funktion runExample() wird ein Selektor erstellt und der Bericht definiert:

// Create selector.
$selector = new Selector();
$selector->setFields(['CampaignId', 'AdGroupId', 'Id', 'Criteria',
    'CriteriaType', 'Impressions', 'Clicks', 'Cost']);

// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName(
    'Criteria performance report #' . uniqid());
$reportDefinition->setDateRangeType(
    ReportDefinitionDateRangeType::LAST_7_DAYS);
$reportDefinition->setReportType(
    ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);

Im Beispiel ist als Berichtstyp ein KRITERIEN-LEISTUNGSBERICHT angegeben. Außerdem sind die Felder aufgeführt, die für den Bericht abgerufen werden sollen.

Die Berichtsdefinition wird dann an einen Downloader für Berichte übergeben:

// Download report.
$reportDownloader = new ReportDownloader($session);
$reportDownloadResult =
    $reportDownloader->downloadReport($reportDefinition);
$reportDownloadResult->saveToFile($filePath);
printf("Report with name '%s' was downloaded to '%s'.\n",
    $reportDefinition->getReportName(), $filePath);

Führen Sie DownloadCriteriaReportWithSelector.php aus. Daraufhin wird in der Konsole der Speicherort der heruntergeladenen Datei ausgegeben.

Perl

Öffnen Sie download_criteria_report_with_selector.pl in Ihrer IDE.

Hier wird der gleiche Boilerplate-Code wie im vorherigen Beispiel verwendet. Er übernimmt die Authentifizierung, indem er Werte aus der Konfigurationsdatei adwords.properties abruft:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});

In diesem Beispiel ist jedoch insbesondere der Code interessant, mit dem ein Selektor erstellt wird, der den gewünschten Bericht definiert:

my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
      reportName     => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today,
      dateRangeType  => "LAST_7_DAYS",
      reportType     => "CRITERIA_PERFORMANCE_REPORT",
      downloadFormat => "CSV",
      selector       => $selector
});

Die Definition wird dann an eine Instanz von ReportDownloader übergeben:

# Download the report using the appropriate method on ReportDownloadHandler.
my $result;
if ($output_file) {
  $result = $report_handler->save($output_file);
} else {
  $result = $report_handler->get_as_string();
}

Führen Sie download_criteria_report_with_selector.pl aus.

In der Konsole wird der Speicherort der heruntergeladenen Datei ausgegeben.

Im Beispielcode ist ein Berichtstyp angegeben, in diesem Fall ein Kriterien-Leistungsbericht.

reportType => "CRITERIA_PERFORMANCE_REPORT",

Außerdem sind Felder angegeben, die für den Bericht abgerufen werden sollen:

# Create selector.
my $selector = Google::Ads::AdWords::Reports::Selector->new({
    fields => [
      "CampaignId", "AdGroupId", "Id",          "CriteriaType",
      "Criteria",   "FinalUrls", "Impressions", "Clicks",
      "Cost"
    ]
});

Ruby

Öffnen Sie download_criteria_report_with_selector.rb.

Hier wird der gleiche Boilerplate-Code wie im vorherigen Beispiel verwendet. Er übernimmt die Authentifizierung, indem er Werte aus der Konfigurationsdatei adwords_api.yml abruft:

def download_criteria_report_with_selector(file_name)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

In diesem Beispiel ist jedoch insbesondere der Code interessant, mit dem eine Objekthierarchie erstellt wird, die den gewünschten Bericht definiert:

# Define report definition. You can also pass your own XML text as a string.
report_definition = {
  :selector => {
    :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
        'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
  },
...

  :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
  :report_type => 'CRITERIA_PERFORMANCE_REPORT',
  :download_format => 'CSV',
  :date_range_type => 'LAST_7_DAYS',
}

Die Definition wird dann an die Methode report_utils.download_report_as_file übergeben:

# Download report, using "download_report_as_file" utility method.
# To retrieve the report as return value, use "download_report" method.
report_utils.download_report_as_file(report_definition, file_name)
puts "Report was downloaded to '%s'." % file_name
end

Führen Sie nun download_criteria_report_with_selector.rb aus. In der Konsole wird der Speicherort der heruntergeladenen Datei ausgegeben.

Im Beispielcode ist ein Berichtstyp angegeben, in diesem Fall ein Kriterien-Leistungsbericht.

:report_type => 'CRITERIA_PERFORMANCE_REPORT',

Außerdem sind Felder angegeben, die für den Bericht abgerufen werden sollen:

:fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],

Eine vollständige Liste der Berichtstypen und der darin enthaltenen Felder finden Sie auf der Seite mit Berichtstypen.

Sie können dieses Codebeispiel in Verbindung mit den Informationen auf der Seite mit Berichtstypen verwenden, um alle Arten von Berichten zu definieren, zu erstellen und herunterzuladen, die Sie benötigen.

AdWords Query Language (AWQL)

Sie können Berichte nicht nur über eine Objekthierarchie, sondern auch mit der AdWords Query Language (AWQL) definieren. Dies ist eine SQL-ähnliche Sprache, mit der sich Berichte einfacher erstellen lassen als über Objekte.

Java

Vergleichen Sie den zuvor ausgeführten Beispielcode mit DownloadCriteriaReportWithAWQL.java: Von beiden wird derselbe Bericht abgerufen, aber die AWQL ist kompakter. Die Berichtstypen und -felder sind in beiden Fällen gleich.

String query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, "
    + "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT "
    + "WHERE Status IN [ENABLED, PAUSED] "
    + "DURING YESTERDAY";

C#

Vergleichen Sie den zuvor ausgeführten Beispielcode mit DownloadCriteriaReportWithAWQL.cs: Von beiden wird derselbe Bericht abgerufen, aber die AWQL ist kompakter. Die Berichtstypen und -felder sind in beiden Fällen gleich.

string query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, Impressions, " +
    "Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] " +
    "DURING LAST_7_DAYS";

Python

Vergleichen Sie den zuvor ausgeführten Beispielcode mit download_criteria_report_with_awql.py: Von beiden wird derselbe Bericht abgerufen, aber die AWQL ist kompakter. Die Berichtstypen und -felder sind in beiden Fällen gleich.

report_query = ('SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
                'FinalUrls, Impressions, Clicks, Cost '
                'FROM CRITERIA_PERFORMANCE_REPORT '
                'WHERE Status IN [ENABLED, PAUSED] '
                'DURING LAST_7_DAYS')

PHP

Vergleichen Sie das Beispiel für den Download von Berichten mithilfe eines Selektors mit DownloadCriteriaReportWithAwql.php: Von beiden werden die gleichen Berichtstypen und Felder definiert und es wird derselbe Bericht abgerufen, aber die AWQL ist kompakter.

// Create report query to get the data for last 7 days.
$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
    . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
    . 'WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS';

Perl

Vergleichen Sie den zuvor ausgeführten Beispielcode mit download_criteria_report_with_awql.pl: Von beiden wird derselbe Bericht abgerufen, aber die AWQL ist kompakter. Die Berichtstypen und -felder sind in beiden Fällen gleich.

my $report_query =
  "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " .
  "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " .
  "WHERE Status IN [ENABLED, PAUSED] " . "DURING $last_4_days, $yesterday";

Hier wird der Zeitraum für den Bericht im Code unmittelbar vor der AWQL-Abfrage definiert:

# Create report query.
my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24);
my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
(undef, undef, undef, $mday, $mon, $year) =
  localtime(time - 60 * 60 * 24 * 4);
my $last_4_days = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);

Ruby

Vergleichen Sie den zuvor ausgeführten Beispielcode mit download_criteria_report_with_awql.rb: Von beiden wird derselbe Bericht abgerufen, aber die AWQL ist kompakter. Die Berichtstypen und -felder sind in beiden Fällen gleich.

report_query = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' +
    'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' +
    'WHERE Status IN [ENABLED, PAUSED] ' +
    'DURING %s' % date_range

Hier wird der Zeitraum im Code unmittelbar vor der AWQL-Abfrage definiert:

# Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
date_range = '%s,%s' % [
    DateTime.parse((Date.today - 7).to_s).strftime('%Y%m%d'),
    DateTime.parse((Date.today - 1).to_s).strftime('%Y%m%d')
]

Sie kennen jetzt die Grundlagen der Berichterstellung und verfügen über die Tools zum Erstellen einer eigenen, benutzerdefinierten Berichtsplattform.

Codebeispiele zur Automatisierung verwenden

In diesem Abschnitt erfahren Sie, wie Sie die Codebeispiele zur Aktualisierung von AdWords-Konten und für einige andere gebräuchliche Anwendungsfälle verwenden können. Außerdem sehen Sie, wie diese Beispiele als Grundlage für nahezu alle Arten von Automatisierungen dienen.

Anzeigengruppen pausieren und fortsetzen

Einer der häufigsten Anwendungsfälle für die API ist das Pausieren und Fortsetzen von Anzeigengruppen. So können Sie beispielsweise eine Anzeige pausieren, wenn der Bestand eines Artikels erschöpft ist, und damit Ihr Werbebudget optimal nutzen.

Bei diesem Anwendungsfall werden die Vorteile deutlich, die die Verknüpfung eigener Systeme (z. B. Bestandsverfolgung) mit der AdWords API bietet.

Wir verwenden die Codebeispiele zum Pausieren und Fortsetzen einer Anzeigengruppe:

Java

Öffnen Sie das Beispiel UpdateAdGroup.java in Ihrer IDE.

In main sehen wir wieder den typischen Boilerplate-Code, den wir bereits kennen. Dieses Mal enthält main ziemlich am Ende einen Platzhalterstring für die ID der Anzeigengruppe.

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    Long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");
}

Wie kommen Sie zu dieser ID? Sie können sie programmatisch über die Methode get() der AdGroupService-Oberfläche erhalten. Schneller geht es aber, wenn Sie sie der URL der AdWords-Weboberfläche entnehmen, während diese Anzeigengruppe zu sehen ist.

Auch hier enthält die Methode runExample den interessanten Code. Betrachten wir Schritt für Schritt, was passiert:

Erst einmal wird ein Verweis auf die AdGroupService-Oberfläche abgerufen, weil eine Anzeigengruppe aktualisiert wird. Zum Aktualisieren anderer Entitäten verwenden Sie den entsprechenden Dienst. Eine vollständige Liste der Dienste finden Sie im Leitfaden Objekte, Methoden und Dienste.

// Get the AdGroupService.
AdGroupServiceInterface adGroupService =
    adWordsServices.get(session, AdGroupServiceInterface.class);

Nun wird ein neues Anzeigengruppenobjekt erstellt und die ID des neuen Objekts auf die ID der Anzeigengruppe gesetzt, die aktualisiert werden soll.

// Create ad group with updated status.
AdGroup adGroup = new AdGroup();
adGroup.setId(adGroupId);

Dann wird der Status auf PAUSED gesetzt.

adGroup.setStatus(AdGroupStatus.PAUSED);

Anschließend wird eine AdGroupOperation erstellt, die das neu erstellte adGroup-Objekt als Operanden und SET als Operator verwendet.

// Create operations.
AdGroupOperation operation = new AdGroupOperation();
operation.setOperand(adGroup);
operation.setOperator(Operator.SET);

Schließlich wird die Methode mutate() der AdGroupService-Oberfläche aufgerufen und das AdGroupOperation-Objekt übergeben.

// Update ad group.
AdGroupReturnValue result = adGroupService.mutate(operations);

Ersetzen Sie nun den Platzhalter durch eine Anzeigengruppen-ID aus Ihrem Testkundenkonto und führen Sie den Code aus. Melden Sie sich nach der Ausführung in der AdWords-Weboberfläche im Testkonto an und prüfen Sie, ob sich der Status geändert hat.

C#

Öffnen Sie das Beispiel UpdateAdGroup.cs in Ihrer IDE.

In main sehen wir wieder den typischen Boilerplate-Code wie in den vorherigen Abschnitten. Dieses Mal enthält main ziemlich am Ende einen Platzhalterstring für die ID der Anzeigengruppe.

public static void Main(string[] args) {
    UpdateAdGroup codeExample = new UpdateAdGroup();
    Console.WriteLine(codeExample.Description);
    try {
      long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE");
      codeExample.Run(new AdWordsUser(), adGroupId);
    }
}

Wie kommen Sie zu dieser ID? Sie können sie programmatisch über die Methode get() der AdGroupService-Oberfläche erhalten. Schneller geht es aber, wenn Sie sie der URL der AdWords-Weboberfläche entnehmen, während diese Anzeigengruppe zu sehen ist.

Auch hier enthält die Methode runExample den interessanten Code. Betrachten wir Schritt für Schritt, was passiert:

Erst einmal wird ein Verweis auf die AdGroupService-Oberfläche abgerufen, weil eine Anzeigengruppe aktualisiert wird. Zum Aktualisieren anderer Entitäten verwenden Sie den entsprechenden Dienst. Eine vollständige Liste der Dienste finden Sie im Leitfaden Objekte, Methoden und Dienste.

public void Run(AdWordsUser user, long adGroupId) {
    // Get the AdGroupService.
    AdGroupService adGroupService =
        (AdGroupService) user.GetService(AdWordsService.v201710.AdGroupService);
}

Nun wird ein neues AdGroup-Objekt erstellt und die ID des neuen Objekts auf die ID der Anzeigengruppe gesetzt, die aktualisiert werden soll.

// Create the ad group.
AdGroup adGroup = new AdGroup();
adGroup.status = AdGroupStatus.PAUSED;
adGroup.id = adGroupId;

Der Status wird auf PAUSED gesetzt.

adGroup.status = AdGroupStatus.PAUSED;

Anschließend wird eine AdGroupOperation erstellt, die das neu erstellte adGroup-Objekt als Operanden und SET als Operator verwendet.

// Create the operation.
AdGroupOperation operation = new AdGroupOperation();
operation.@operator = Operator.SET;
operation.operand = adGroup;

Schließlich wird die Methode mutate() der AdGroupService-Oberfläche aufgerufen und das AdGroupOperation-Objekt übergeben.

// Update the ad group.
AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});

Ersetzen Sie nun den Platzhalter durch eine Anzeigengruppen-ID aus Ihrem Testkundenkonto und führen Sie den Code aus. Melden Sie sich nach der Ausführung in der AdWords-Weboberfläche im Testkonto an und prüfen Sie, ob sich der Status geändert hat.

Python

Öffnen Sie das Beispiel update_ad_group.py in Ihrer IDE.

Auch hier sehen wir den typischen Boilerplate-Code, mit dem durch die Methode LoadFromStorage Anmeldedaten und Properties aus der Konfigurationsdatei googleads.yaml entnommen werden. Dieses Mal wird für die ID der Anzeigengruppe ein Platzhalterstring hinzugefügt.

AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'

Wie kommen Sie zu dieser ID? Sie können sie programmatisch über die Methode get() der AdGroupService-Oberfläche erhalten. Schneller geht es aber, wenn Sie sie der URL der AdWords-Weboberfläche entnehmen, während diese Anzeigengruppe zu sehen ist.

Der interessante Code kommt danach. Betrachten wir Schritt für Schritt, was passiert:

Erst einmal wird ein Verweis auf die AdGroupService-Oberfläche abgerufen, weil eine Anzeigengruppe aktualisiert wird. Zum Aktualisieren anderer Entitäten verwenden Sie den entsprechenden Dienst. Eine vollständige Liste der Dienste finden Sie im Leitfaden Objekte, Methoden und Dienste.

def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_service = client.GetService('AdGroupService', version='v201710')

Nun wird die ID auf die ID der zu aktualisierenden Anzeigengruppe und der Status auf PAUSED gesetzt.

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

Anschließend wird eine AdGroupOperation erstellt, die das neu erstellte Anzeigengruppenobjekt als Operanden und SET als Operator verwendet. Der Status wird auf PAUSED gesetzt.

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

Schließlich wird die Methode mutate() der AdGroupService-Oberfläche aufgerufen und das AdGroupOperation-Objekt übergeben.

ad_groups = ad_group_service.mutate(operations)

Ersetzen Sie nun den Platzhalter durch eine Anzeigengruppen-ID aus Ihrem Testkundenkonto und führen Sie den Code aus. Melden Sie sich nach der Ausführung in der AdWords-Weboberfläche im Testkonto an und prüfen Sie, ob sich der Status geändert hat.

PHP

Öffnen Sie PauseAd.php in Ihrer IDE.

Die jeweilige Anzeige wird anhand der Anzeigengruppen- und Anzeigen-ID identifiziert:

const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const AD_ID = 'INSERT_AD_ID_HERE';

Die Anzeigengruppen-ID kann über die Methode get() aus AdGroupService oder aus der URL der AdWords-Weboberfläche abgerufen werden, während die Anzeigengruppe zu sehen ist.

Im Folgenden gehen wir runExample() Schritt für Schritt durch:

  1. Verweis auf AdGroupService abrufen, weil eine Anzeigengruppe aktualisiert wird:
    $adGroupAdService =
        $adWordsServices->get($session, AdGroupAdService::class);
    
  2. Ad-Objekt erstellen:
    $ad = new Ad();
    $ad->setId($adId);
    
  3. AdGroupAd-Objekt erstellen und dessen Anzeigengruppen-ID und Anzeige festlegen:
    $adGroupAd = new AdGroupAd();
    $adGroupAd->setAdGroupId($adGroupId);
    $adGroupAd->setAd($ad);
    
  4. Status von AdGroupAd auf PAUSED setzen:
    $adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
    
  5. Operation einrichten und mit der Methode mutate() an AdGroupAdService senden:
    // Create ad group ad operation and add it to the list.
    $operation = new AdGroupAdOperation();
    $operation->setOperand($adGroupAd);
    $operation->setOperator(Operator::SET);
    $operations[] = $operation;
    
    // Pause the ad on the server.
    $result = $adGroupAdService->mutate($operations);
    

Ersetzen Sie die Platzhalter durch entsprechende IDs aus Ihrem Testkundenkonto und führen Sie den Code aus. Melden Sie sich nach der Ausführung in der AdWords-Weboberfläche im Testkonto an und prüfen Sie, ob sich der Status geändert hat.

Perl

Öffnen Sie das Beispiel update_ad_group.pl in Ihrer IDE.

Wieder sehen wir am Ende den uns bereits bekannten, typischen Boilerplate-Code, mit dem aus der Konfigurationsdatei adwords.properties Anmeldedaten entnommen werden.

In diesem Beispiel wird ein Platzhalterstring für die ID der Anzeigengruppe und der Anzeige hinzugefügt, die pausiert werden soll.

# Replace with valid values of your account.
my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";

Wie kommen Sie zu dieser ID? Sie können sie programmatisch über die Methode get() der AdGroupService-Oberfläche erhalten. Schneller geht es aber, wenn Sie sie der URL der AdWords-Weboberfläche entnehmen, während diese Anzeigengruppe zu sehen ist.

Der interessante Code ist allerdings erst zu sehen, wenn das Beispiel ausgeführt wird. Betrachten wir Schritt für Schritt, was passiert:

Erst einmal wird eine Anzeigengruppe mit aktualisiertem Status und der angegebenen adGroupID erstellt. Zum Aktualisieren anderer Entitäten verwenden Sie den entsprechenden Dienst. Eine vollständige Liste der Dienste finden Sie im Leitfaden Objekte, Methoden und Dienste. Dann wird der Status auf PAUSED gesetzt.

# Create ad group with updated status.
my $ad_group = Google::Ads::AdWords::v201710::AdGroup->new({
    id     => $ad_group_id,
    status => "PAUSED"
});

Anschließend wird eine AdGroupOperation erstellt, die das neu erstellte Anzeigengruppenobjekt als Operanden und SET als Operator verwendet.

# Create operation.
my $operation = Google::Ads::AdWords::v201710::AdGroupOperation->new({
    operand  => $ad_group,
    operator => "SET"
});

Schließlich wird die Methode mutate() der AdGroupService-Oberfläche aufgerufen und das AdGroupOperation-Objekt übergeben.

# Update ad group.
my $result = $client->AdGroupService()->mutate({operations => [$operation]});

Ersetzen Sie nun den Platzhalter durch eine Anzeigengruppen-ID aus Ihrem Testkundenkonto und führen Sie den Code aus. Melden Sie sich nach der Ausführung in der AdWords-Weboberfläche im Testkonto an und prüfen Sie, ob sich der Status geändert hat.

Ruby

Öffnen Sie das Beispiel update_ad_group.rb.

Wir sehen wieder den uns bereits bekannten, typischen Boilerplate-Code, mit dem aus der Konfigurationsdatei adwords_api.yml Anmeldedaten entnommen werden. Etwas weiter unten befindet sich ein Platzhalterstring für die ID der Anzeigengruppe.

# ID of an ad group to update.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

Wie kommen Sie zu dieser ID? Sie können sie programmatisch über die Methode get() der AdGroupService-Oberfläche erhalten. Schneller geht es aber, wenn Sie sie der URL der AdWords-Weboberfläche entnehmen, während diese Anzeigengruppe zu sehen ist.

Auch hier ist der interessante Code erst zu sehen, wenn das Beispiel ausgeführt wird. Betrachten wir Schritt für Schritt, was passiert:

Erst einmal wird ein Verweis auf die AdGroupService-Oberfläche abgerufen, weil eine Anzeigengruppe aktualisiert wird. Zum Aktualisieren anderer Entitäten verwenden Sie den entsprechenden Dienst. Eine vollständige Liste der Dienste finden Sie im Leitfaden Objekte, Methoden und Dienste.

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

Nun wird ein neues AdGroup-Objekt erstellt und die ID des neuen Objekts auf die ID der Anzeigengruppe gesetzt, die aktualisiert werden soll. Außerdem wird der Status auf PAUSED gesetzt und SET als Operator verwendet.

# Prepare for updating ad group.
operation = {
  :operator => 'SET',
  :operand => {
    :status => 'PAUSED',
    :id => ad_group_id
  }
}

Schließlich wird die Methode mutate() der AdGroupService-Oberfläche aufgerufen und das AdGroupOperation-Objekt übergeben.

# Update ad group.
response = ad_group_srv.mutate([operation])

Ersetzen Sie nun den Platzhalter durch eine Anzeigengruppen-ID aus Ihrem Testkundenkonto und führen Sie den Code aus. Melden Sie sich nach der Ausführung in der AdWords-Weboberfläche im Testkonto an und prüfen Sie, ob sich der Status geändert hat.

Nähere Betrachtung des Musters

Der oben erläuterte Ablauf zum Pausieren und Fortsetzen der Anzeigengruppe wird bei den meisten Aktualisierungen über die API verwendet. Daher lohnt es sich, die Schritte etwas genauer zu betrachten:

  1. Neues Objekt erstellen
  2. Dessen ID auf die ID der Entität festlegen, die geändert werden soll
  3. Den neuen Wert der Property in diesem neuen Objekt festlegen
  4. Operation-Objekt mit SET als Operator und diesem neuen Entitätsobjekt als Operand erstellen
  5. Operation-Objekt an die Methode mutate() des entsprechenden Dienstes übergeben

Da dies eine Aktualisierung war, haben wir den Operator SET verwendet. Das Hinzufügen oder Entfernen würde mit dem Operator ADD bzw. REMOVE erfolgen.

Wenn Ihnen in diesem Zusammenhang etwas unklar ist, sollten Sie einen Blick auf die anderen Codebeispiele werfen. Dann werden Sie schnell das Muster erkennen.

Jetzt kennen Sie das Muster und können leicht viele andere Aktualisierungen vornehmen, z. B. das Gebot für eine Anzeigengruppe ändern.

Gebote für Anzeigengruppen ändern

Ein weiterer gebräuchlicher Anwendungsfall ist das programmatische Ändern von Geboten. Klassisches Beispiel: Wenn es regnet, soll bei einer Anzeige für Regenschirme das Gebot angehoben werden. Sie könnten Ihre Anwendung mit einem Wetterdienst im Web verknüpfen, um dann mithilfe der AdWords API das Gebot für die entsprechende Anzeigengruppe zu erhöhen.

Hierfür ließe sich das oben behandelte Beispiel "UpdateAdGroup" etwas abändern: Anstelle von AdGroupStatus würden Sie die Gebotsstrategie festlegen. Weitere Informationen finden Sie im Leitfaden zur Gebotseinstellung.

Kampagnen erstellen

Ein weiterer Anwendungsfall:

Java

Öffnen Sie AddCampaigns.java in Ihrer IDE.

Das Beispiel enthält sehr viel Code, entspricht jedoch dem gleichen Muster wie oben. Sobald die Objekthierarchie erstellt ist, wird der ADD-Operator verwendet, um mit BudgetService ein neues Budget und mit CampaignService neue Kampagnen hinzuzufügen.

IDs müssen hier nicht festgelegt werden, weil dies neue Entitäten sind, die noch keine IDs haben.

C#

Öffnen Sie AddCampaigns.cs in Ihrer IDE.

Das Beispiel enthält sehr viel Code, entspricht jedoch dem gleichen Muster wie oben. Sobald die Objekthierarchie erstellt ist, wird der ADD-Operator verwendet, um mit BudgetService ein neues Budget und mit CampaignService neue Kampagnen hinzuzufügen.

IDs müssen hier nicht festgelegt werden, weil dies neue Entitäten sind, die noch keine IDs haben.

Python

Öffnen Sie add_campaigns.py in Ihrer IDE.

Das Beispiel enthält sehr viel Code, entspricht jedoch dem gleichen Muster wie oben. Sobald die Objekthierarchie erstellt ist, wird der ADD-Operator verwendet, um mit BudgetService ein neues Budget und mit CampaignService neue Kampagnen hinzuzufügen.

IDs müssen hier nicht festgelegt werden, weil dies neue Entitäten sind, die noch keine IDs haben.

PHP

Öffnen Sie AddCampaigns.php in Ihrer IDE.

Wie üblich befindet sich der Großteil der Logik in runExample(). Wir richten ein Budget, eine Kampagne, eine Gebotsstrategie sowie optionale Einstellungen wie Ausrichtung auf Werbenetzwerke und Frequency Capping ein. Nun schließen wir die Kampagne mit einem ADD-Operator ein und senden die Operation über mutate() an CampaignService.

Perl

Öffnen Sie add_campaigns.pl in Ihrer IDE.

Das Beispiel enthält sehr viel Code, entspricht jedoch dem gleichen Muster wie oben. Sobald die Objekthierarchie erstellt ist, wird der ADD-Operator verwendet, um mit BudgetService ein neues Budget und mit CampaignService neue Kampagnen hinzuzufügen.

IDs müssen hier nicht festgelegt werden, weil dies neue Entitäten sind, die noch keine IDs haben.

Ruby

Öffnen Sie add_campaigns.rb.

Das Beispiel enthält sehr viel Code, entspricht jedoch dem gleichen Muster wie oben. Sobald die Objekthierarchie erstellt ist, wird der ADD-Operator verwendet, um mit BudgetService ein neues Budget und mit CampaignService neue Kampagnen hinzuzufügen.

IDs müssen hier nicht festgelegt werden, weil dies neue Entitäten sind, die noch keine IDs haben.

Weitere Informationen

Jetzt sind Sie mit den Grundlagen vertraut. In Objekte, Methoden und Dienste und zugehörigen Leitfäden erfahren Sie mehr über die Architektur sowie die Dienste und Funktionen der API.

Dann können Sie eine eigene Anwendung erstellen und von den Vorteilen profitieren, die sich Ihnen durch die AdWords API eröffnen: höhere Effizienz durch Automatisierung und bessere Auswertungsmöglichkeiten durch benutzerdefinierte Berichte.

Feedback geben zu...