Der erste API-Aufruf

In diesem Leitfaden zeigen wir Ihnen alle Schritte bis zum ersten API-Aufruf. Anschließend können Sie vollständig von der AdWords API profitieren.

Im Video werden Java und Eclipse verwendet. Sie können jedoch die Programmiersprache und Clientbibliothek Ihrer Wahl verwenden. Die Konzepte sind ähnlich und Sie finden unten Anleitungen für alle unterstützten Sprachen.

Vorgehensweise – Übersicht

Der API-Zugriff wird eingerichtet, indem erforderliche Anmeldedaten zur Authentifizierung abgerufen, Testkonten erstellt und die Authentifizierungs- und Kontodetails einer Konfigurationsdatei für Ihre Clientbibliothek hinzugefügt werden.

Sobald die Konfigurationsdatei eingerichtet ist, sind AP-Aufrufe möglich.

Zu Beginn sind diese sechs Schritte erforderlich:

  1. Fordern Sie ein Entwickler-Token an.
  2. Erstellen Sie Testkonten.
  3. Rufen Sie eine Clientbibliothek ab.
  4. Richten Sie die Authentifizierung über OAuth2 ein.
  5. Rufen Sie ein OAuth2-Aktualisierungs-Token ab und konfigurieren Sie Ihren Client.
  6. Rufen Sie zum ersten Mal die API auf.

Jeder Schritt wird in den folgenden Abschnitten beschrieben.

Entwickler-Token anfordern

Mit einem Entwickler-Token von Google kann über Ihre Anwendung die Verbindung mit der AdWords API hergestellt werden. Führen Sie die Schritte im Registrierungsleitfaden aus, um ein Entwickler-Token anzufordern (falls noch nicht geschehen). Nach der Registrierung erhalten Sie ein Entwickler-Token, dessen Genehmigung aussteht.

Das ausstehende Entwickler-Token muss genehmigt werden, bevor Sie es für AdWords-Produktionskonten verwenden können.

Testkonten erstellen

Führen Sie folgende Schritte aus, um ein Testverwaltungskonto, ein Testkundenkonto und einige Kampagnen für das Testkundenkonto zu erstellen.

  1. Wechseln Sie zur AdWords-Seite mit Verwaltungskonten und erstellen Sie ein Testverwaltungskonto.
  2. Erstellen Sie über die AdWords-Weboberfläche unter diesem Testverwaltungskonto ein Testkundenkonto. Wenn Sie in AdWords mit dem Testverwaltungskonto angemeldet sind, sind von Ihnen erstellte Kundenkonten automatisch Testkonten.
  3. Erstellen Sie in der AdWords-Weboberfläche unter dem Testkundenkonto einige Testkampagnen.
  4. Merken Sie sich die Client-Kundennummer des neuen Testkundenkontos. Sie muss in einem weiteren Schritt zur Konfigurationsdatei hinzugefügt werden. Die Client-Kundennummer ist unten zu sehen.

Verwenden Sie für Anfragen beim Testverwaltungskonto das Entwickler-Token Ihres Verwaltungskontos. Auch wenn das Token noch nicht genehmigt ist, funktioniert es mit Testkonten einschließlich den soeben erstellten.

Clientbibliothek abrufen

Über die Clientbibliotheken werden alle Back-End-API-Aufrufe verarbeitet und Programmierern verständliche Objekte zur Verfügung gestellt, darunter auch Codebeispiele für praktisch jede gängige API-Aufgabe.

Wenn Sie ein erfahrener Entwickler sind, haben Sie wahrscheinlich Ihre Entwicklungsumgebung bereits wie gewünscht eingerichtet. Falls nicht, sehen Sie sich nachfolgend die empfohlenen Schritte zur Einrichtung der Clientbibliotheken an.

Klicken Sie unten auf den Tab der verwendeten Programmiersprache und folgen Sie der Anleitung.

Java

  1. Lesen Sie in der README-Datei der Java-Clientbibliothek den Abschnitt zum Einstieg in GitHub. Darin wird beschrieben, wie Sie die AdWords API-Clientbibliothek für Java herunterladen und installieren.
  2. Kehren Sie zu dieser Seite zurück, bevor Sie die OAuth2-Schritte durchführen: Im nächsten Schritt werden die OAuth2-Anmeldedaten eingerichtet.

.NET

  1. Lesen Sie in der README-Datei der .NET-Clientbibliothek den Abschnitt zum Einstieg. Darin wird beschrieben, wie Sie die AdWords API-Clientbibliothek für CSharp oder Visual Basic herunterladen und installieren.
  2. Kehren Sie zu dieser Seite zurück, bevor Sie die OAuth2-Schritte durchführen: Im nächsten Schritt werden die OAuth2-Anmeldedaten eingerichtet.

Python

  1. Lesen Sie in der README-Datei der Python-Clientbibliothek den Abschnitt zum Einstieg. Darin wird beschrieben, wie Sie die AdWords API-Clientbibliothek für Python herunterladen und installieren.
  2. Kehren Sie zu dieser Seite zurück, bevor Sie die OAuth2-Schritte durchführen: Im nächsten Schritt werden die OAuth2-Anmeldedaten eingerichtet.

PHP

  1. Lesen Sie in der README-Datei der PHP-Clientbibliothek den Abschnitt zum Einstieg. Darin wird beschrieben, wie Sie die AdWords API-Clientbibliothek für PHP herunterladen und installieren.
  2. Kehren Sie zu dieser Seite zurück, bevor Sie die OAuth2-Schritte durchführen: Im nächsten Schritt werden die OAuth2-Anmeldedaten eingerichtet.

Perl

  1. Lesen Sie in der README-Datei der Perl-Clientbibliothek den Abschnitt zum Einstieg. Darin wird beschrieben, wie Sie die AdWords API-Clientbibliothek für Perl herunterladen und installieren.
  2. Kehren Sie zu dieser Seite zurück, bevor Sie die OAuth2-Schritte durchführen: Im nächsten Schritt werden die OAuth2-Anmeldedaten eingerichtet.

Ruby

  1. Lesen Sie in der README-Datei der Ruby-Clientbibliothek den Abschnitt zum Einstieg. Darin wird beschrieben, wie Sie die AdWords API-Clientbibliothek für Ruby herunterladen und installieren.
  2. Kehren Sie zu dieser Seite zurück, bevor Sie die OAuth2-Schritte durchführen: Im nächsten Schritt werden die OAuth2-Anmeldedaten eingerichtet.

OAuth2-Authentifizierung einrichten

Sie müssen mit Ihrer Anwendung auf Nutzerdaten zugreifen und andere Google-Dienste in Ihrem Namen aufrufen können. Hierfür ist die Authentifizierung über OAuth2 erforderlich.

Damit Sie mit Ihrer Anwendung auf die API zugreifen können, benötigen Sie eine Client-ID und einen Clientschlüssel für OAuth2.

  1. Öffnen Sie die Google Developers Console, während Sie mit den Anmeldedaten Ihres Verwaltungskontos angemeldet sind.
  2. Wählen Sie aus der Drop-down-Liste Neues Projekt erstellen aus, geben Sie einen Namen für das Projekt ein und klicken Sie auf Erstellen.
  3. Wählen Sie Anmeldedaten erstellen und anschließend OAuth-Client-ID aus.
  4. Möglicherweise werden Sie nun aufgefordert, auf dem Bildschirm Zustimmung einen Produktnamen festzulegen. Klicken Sie in diesem Fall auf Zustimmungsbildschirm konfigurieren, geben Sie die benötigten Informationen ein und klicken Sie auf Speichern, um zum Bildschirm Anmeldedaten zurückzukehren.
  5. Wählen Sie in unserem Fall Andere unter Anwendungstyp aus. Geben Sie einen Namen in das Feld ein.
  6. Klicken Sie auf Erstellen. Die Client-ID und der Clientschlüssel für OAuth2 werden angezeigt. Kopieren und speichern Sie diese Werte. Im nächsten Schritt fügen Sie sie Ihrer Konfigurationsdatei hinzu.

OAuth2-Aktualisierungstoken abrufen und Client konfigurieren

Da der OAuth2-Zugriff nach einer bestimmten Zeit abläuft, wird ein Aktualisierungstoken verwendet, um den OAuth2-Zugriff automatisch neu zu generieren.

Klicken Sie unten auf den Tab der verwendeten Programmiersprache und folgen Sie der Anleitung, um ein OAuth2-Aktualisierungstoken zu generieren und die Konfigurationsdatei für den Client einzurichten.

Java

  1. Folgen Sie dieser Anleitung in GitHub, um ein OAuth2-Aktualisierungstoken abzurufen und die Clientbibliothek zu konfigurieren.
  2. Kehren Sie anschließend auf diese Seite zurück. Nach Abschluss aller Schritte sollte in der Datei ads.properties alles vorhanden sein, was zur Durchführung von API-Testaufrufen erforderlich ist. Die Datei sollte Werte ähnlich wie die folgenden enthalten:
[...]
api.adwords.developerToken=123axxxxxxxxxxxxxxxxxx
api.adwords.clientId=xxxxxxxxxx.apps.googleusercontent.com
api.adwords.clientSecret=zZxxxxxTxxxxxxxxxxx
api.adwords.clientCustomerId=123-456-7890
api.adwords.refreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
api.adwords.userAgent=Company_Name
[...]

.NET

  1. Folgen Sie dieser Anleitung in GitHub, um ein OAuth2-Aktualisierungstoken abzurufen und die Clientbibliothek zu konfigurieren.
  2. Kehren Sie anschließend auf diese Seite zurück. Nach Abschluss aller Schritte sollte in der Datei app.config alles vorhanden sein, was zur Durchführung von API-Testaufrufen erforderlich ist. Die Datei sollte Werte ähnlich wie die folgenden enthalten:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="AdWordsApi"
        type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <AdWordsApi>
    <!-- Settings specific to AdWords API.-->
    <add key="UserAgent" value="My AdWords API application"/>
    <add key="DeveloperToken" value="xxxxxxxxxxxxxxxxxxxxxx"/>
    <add key="ClientCustomerId" value="123-456-7890"/>

    <!-- OAuth2 configuration -->
    <add key="AuthorizationMethod" value="OAuth2" />
    <add key="OAuth2ClientId" value="xxxxxxxxxx.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="zZxxxxxTxxxxxxxxxxx" />
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2RefreshToken" value="1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxx" />
  </AdWordsApi>
</configuration>

Python

  1. Folgen Sie dieser Anleitung in GitHub, um ein OAuth2-Aktualisierungstoken abzurufen und die Clientbibliothek zu konfigurieren.
  2. Kehren Sie anschließend auf diese Seite zurück. Nach Abschluss aller Schritte sollte in der Datei googleads.yaml alles vorhanden sein, was zur Durchführung von API-Testaufrufen erforderlich ist. Die Datei sollte Werte ähnlich wie die folgenden enthalten:
adwords:
  developer_token: 123axxxxxxxxxxxxxxxxxx
  user_agent: Company_Name
  client_customer_id: 123-456-7890
  client_id: xxxxxxxxxx.apps.googleusercontent.com
  client_secret: zZxxxxxTxxxxxxxxxxx
  refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

PHP

  1. Folgen Sie dieser Anleitung in GitHub, um ein OAuth2-Aktualisierungstoken abzurufen und die Clientbibliothek zu konfigurieren.
  2. Kehren Sie anschließend auf diese Seite zurück. Nach Abschluss aller Schritte sollte in der Datei auth.ini alles vorhanden sein, was zur Durchführung von API-Testaufrufen erforderlich ist. Die Datei sollte Werte ähnlich wie die folgenden enthalten:
[...]
developerToken = 123axxxxxxxxxxxxxxxxxx
userAgent = Company_Name
clientCustomerId = 123-456-7890
client_id = xxxxxxxxxx.apps.googleusercontent.com
client_secret = zZxxxxxTxxxxxxxxxxx
refresh_token = 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Perl

  1. Folgen Sie dieser Anleitung in GitHub, um ein OAuth2-Aktualisierungstoken abzurufen und die Clientbibliothek zu konfigurieren.
  2. Kehren Sie anschließend auf diese Seite zurück. Nach Abschluss aller Schritte sollte in der Datei adwords.properties alles vorhanden sein, was zur Durchführung von API-Testaufrufen erforderlich ist. Die Datei sollte Werte ähnlich wie die folgenden enthalten:
[...]
userAgent = Company_Name
developerToken=123axxxxxxxxxxxxxxxxxx
clientId=123-456-7890
oAuth2ClientId=xxxxxxxxxx.apps.googleusercontent.com
oAuth2ClientSecret=zZxxxxxTxxxxxxxxxxx
oAuth2RefreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Ruby

  1. Folgen Sie dieser Anleitung in GitHub, um ein OAuth2-Aktualisierungstoken abzurufen und die Clientbibliothek zu konfigurieren.
  2. Kehren Sie anschließend auf diese Seite zurück. Nach Abschluss aller Schritte sollte in der Datei adwords_api.yml alles vorhanden sein, was zur Durchführung von API-Testaufrufen erforderlich ist. Die Datei sollte Werte ähnlich wie die folgenden enthalten:
[...]
:oauth2_client_id: xxxxxxxxxx.apps.googleusercontent.com
:oauth2_client_secret: zZxxxxxTxxxxxxxxxxx
:refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
:developer_token: 123axxxxxxxxxxxxxxxxxx
:client_customer_id: 123-456-7890
:user_agent: Company_Name
[...]

Der erste API-Aufruf

Nun sind Ihre Umgebung und die Konfigurationsdatei eingerichtet und Sie können den ersten API-Aufruf durchführen:

Java

  1. Öffnen Sie GetCampaigns.java in Ihrer IDE und führen Sie die Datei aus.
  2. Über die Konsole sollte eine Auflistung der Testkampagnen gedruckt werden, die Sie Ihrem Testkonto von oben hinzugefügt haben.

.NET

  1. Öffnen Sie GetCampaigns.cs oder GetCampaigns.vb in Ihrer IDE und führen Sie die Datei aus.
  2. Über die Konsole sollte eine Auflistung der Testkampagnen gedruckt werden, die Sie Ihrem Testkonto von oben hinzugefügt haben.

Python

  1. Öffnen Sie get_campaigns.py in Ihrer IDE und führen Sie die Datei aus.
  2. Über die Konsole sollte eine Auflistung der Testkampagnen gedruckt werden, die Sie Ihrem Testkonto von oben hinzugefügt haben.

PHP

  1. Öffnen Sie GetCampaigns.php in Ihrer IDE und führen Sie die Datei aus.
  2. Über die Konsole sollte eine Auflistung der Testkampagnen gedruckt werden, die Sie Ihrem Testkonto von oben hinzugefügt haben.

Perl

  1. Öffnen Sie get_campaigns.pl in Ihrer IDE und führen Sie die Datei aus.
  2. Über die Konsole sollte eine Auflistung der Testkampagnen gedruckt werden, die Sie Ihrem Testkonto von oben hinzugefügt haben.

Ruby

  1. Führen Sie an der Befehlszeile get_campaigns.rb aus, indem Sie Folgendes eingeben:
    ruby get_campaigns.rb
  2. Über die Konsole sollte eine Auflistung der Testkampagnen gedruckt werden, die Sie Ihrem Testkonto von oben hinzugefügt haben.

Damit haben Sie Ihren ersten AdWords API-Aufruf durchgeführt.

In diesem Abschnitt wurde viel Grundlegendes behandelt. Im nächsten Abschnitt gehen wir genauer auf einige Konfigurationselemente ein, mit denen wir in diesem Teil gearbeitet haben.

Konfigurationselemente genauer untersuchen

Im vorherigen Abschnitt haben Sie alles eingerichtet, um den ersten API-Aufruf durchzuführen.

In diesem Abschnitt rekapitulieren wir und sehen uns die Elemente der Anwendungskonfiguration genauer an, die wir für den Aufruf der AdWords API verwendet haben.

Testkonten im Vergleich zu Produktionskonten

Im vorherigen Abschnitt haben Sie ein Testverwaltungskonto und ein Testkundenkonto erstellt.

Testkonten sind sehr nützlich, um mit der API zu experimentieren, da sie sich nicht auf Ihre aktiven Anzeigen auswirken und Ihr Konto nicht belasten. Sie eignen sich auch bestens, um die AdWords-Weboberfläche zu erkunden.

Wenn Sie in AdWords angemeldet sind, erinnert Sie das hellrote Testkontolabel immer daran, dass Sie sich in einem Testkonto befinden:

Da über Testkonten keine Anzeigen ausgeliefert werden, sind Impressionen oder Kostendaten in Berichten oder API-Aufrufen häufig auf null gesetzt.

Weitere Informationen zu Testkonten, zu Produktionskonten und zur Einrichtung einer Kontohierarchie finden Sie unter Konten verwalten.

Konfigurationselemente

Da wir eine Clientbibliothek verwenden, müssen wir nicht die Back-End-Details behandeln, wie API-Aufrufe erfolgen. Wenn Sie jedoch mehr über SOAP, OAuth2 und die anderen Elemente wissen möchten, die diese Aufrufe ermöglichen, finden Sie hier entsprechende Informationen.

Auch bei Verwendung der Clientbibliotheken gibt es einige Elemente, die Sie immer benötigen: Wir haben diese oben bereits eingerichtet. Im Folgenden gehen wir darauf genauer ein.

Entwickler-Token

Mithilfe des Entwickler-Tokenswird Ihre Anwendung gegenüber der AdWords API identifiziert. Genehmigte Tokens können bei AdWords-Produktionskonten mit der API verbunden werden, noch nicht genehmigte Tokens hingegen nur mit Testkonten. Sobald Ihr Token genehmigt ist, können Sie es für Anfragen bei allen Ihren AdWords-Konten verwenden, auch wenn diese nicht mit dem Verwaltungskonto verknüpft sind, das zum Entwickler-Token gehört.

Weitere Informationen finden Sie unter Konten verwalten.

OAuth2-Client-ID und -Clientschlüssel

Über diese Elemente wird Ihre Clientanwendung einem Projekt in der Google Developers Console zugeordnet und sie werden zur OAuth2-Authentifizierung für Ihr Konto verwendet.

Weitere Informationen

OAuth2-Zugriffs- und -Aktualisierungstoken

Bevor über Ihre Anwendung mithilfe der API auf private Daten zugegriffen werden kann, muss ein OAuth2-Zugriffstoken abgerufen werden, um Zugriff auf die API zu erhalten.

Wenn Sie die Clientbibliotheken verwenden, wird das OAuth2-Zugriffstoken automatisch generiert. Sehen Sie sich ansonsten das Beispiel eines API-Aufrufs im Leitfaden zur API-Aufrufstruktur an. Darin wird beschrieben, wie Sie ein Zugriffstoken generieren.

OAuth2-Zugriffstokens verfallen nach einer bestimmten Zeit. Deshalb verwenden die Clientbibliotheken das OAuth2-Aktualisierungs-Token, um das OAuth2-Zugriffstoken automatisch neu zu generieren.

Sie haben in den Schritten oben das Aktualisierungstoken mithilfe eines Dienstprogramms in der Clientbibliothek erstellt.

Weitere Informationen zur Verwendung von OAuth2 mit Google APIs finden Sie unter OAuth2-Authentifizierung und in der Dokumentation zur OAuth2-Identitätsplattform.

Client-Kundennummer

Die Client-Kundennummer ist die Kontonummer des AdWords-Kundenkontos, das Sie über die API verwalten möchten. Sie hat normalerweise das Format 123-456-7890.

Optional kann die Client-Kundennummer in der Konfigurationsdatei weggelassen und programmatisch festgelegt werden. Sobald Ihr Entwickler-Token genehmigt ist, können Sie eine Client-Kundennummer aus einem Produktionskonto anstelle eines Testkontos verwenden.

Weitere Informationen

Weitere Informationen

Nun kennen Sie alle für Ihre erste API-Anwendung erforderlichen Elemente. Im nächsten Leitfaden, Codebeispiele und Anwendungsfälle, wird gezeigt, wie Sie mit den Clientbibliotheken und Codebeispielen in benutzerdefinierte Berichte und Automatisierung einsteigen.

Feedback geben zu...