Leitfaden für die Einrichtung der Google Ads API

In dieser Anleitung wird der gesamte Prozess für das Onboarding, die Authentifizierung und den ersten Aufruf der Google Ads API beschrieben.

1. Voraussetzungen und Kontohierarchie

Bevor Sie mit der Google Ads API interagieren, müssen Sie die Kontohierarchie verstehen und die richtige Kontostruktur auf oberster Ebene eingerichtet haben.

  • Verwaltungskonto (MCC): Ein Google Ads-Verwaltungskonto (ehemals „Kundencenter“) ist ein primäres Konto, mit dem Sie mehrere Kundenkonten aufrufen und verwalten können. Sie benötigen ein Verwaltungskonto, um ein Entwicklertoken für die Google Ads API zu beantragen.
  • Kundenkonto: Das Standardkonto, in dem Kampagnen, Anzeigengruppen und Anzeigen erstellt und die Abrechnung konfiguriert werden.

Aufgabe: Wenn Sie kein Verwaltungskonto haben, erstellen Sie eines unter Google Ads-Verwaltungskonten.

2. Entwicklertoken abrufen

Das Entwicklertoken identifiziert Ihre Anwendung eindeutig für die Google Ads API und steuert die Zugriffsebene für das Anrufvolumen.

Schritte zur Anmeldung

  1. Melden Sie sich in Ihrem Google Ads-Verwaltungskonto an.
  2. Rufen Sie Tools und Einstellungen > Einrichtung > API-Center (oder Verwaltung > API-Center) auf.
  3. Füllen Sie das Formular mit den Entwicklerdetails aus und stimmen Sie den Nutzungsbedingungen für die API zu.
  4. Reichen Sie Ihr Antragsformular ein.

Zugriffsebenen

  • Ausstehende Genehmigung: Neu erstellte Tokens haben sofort den Status „Ausstehend“. Sie können ein ausstehendes Token verwenden, um sofort eine Verbindung zu Testkonten herzustellen. Für Produktionskonten funktioniert es jedoch nicht.
  • Grundlegender Zugriff: Nach der Genehmigung sind bis zu 15.000 API-Vorgänge pro Tag möglich.
  • Standardzugriff: Unbegrenzte Anzahl von API-Vorgängen pro Tag für Anwendungen, die die erforderlichen Mindestfunktionen erfüllen.

3. Testkonten einrichten

Wenn Sie mit Produktionskonten entwickeln und testen, riskieren Sie unerwünschte Werbeausgaben und Kampagnenänderungen. Es wird dringend empfohlen, die gesamte aktive Entwicklung mit Testkonten durchzuführen.

Testverwaltungskonto erstellen

  1. Rufen Sie die Seite zum Erstellen eines Google Ads-Testverwaltungskontos auf.
  2. Melden Sie sich mit einem Google-Konto an, das nicht bereits mit Ihrem Google Ads-Produktionsverwaltungskonto verknüpft ist.
  3. Geben Sie einen beschreibenden Kontonamen ein, z.B. MyCompany Test MCC.
  4. Wählen Sie als primäre Verwendung Konten von anderen Nutzern verwalten aus.
  5. Wählen Sie das Land der Rechnungsadresse, die Zeitzone und die Währung aus. Klicken Sie auf Speichern und fortfahren.

Testkundenkonto erstellen

Nachdem Sie Ihr Testverwaltungskonto erstellt haben, müssen Sie mindestens ein untergeordnetes Kundenkonto erstellen, um Testkampagnen auszuführen.

  1. Melden Sie sich in Ihrem neu erstellten Testverwaltungskonto an.
  2. Klicken Sie im Navigationsmenü links auf Konten und wählen Sie dann Einstellungen für Unterkonten (oder Leistung) aus.
  3. Klicken Sie auf das blaue + (Pluszeichen) und wählen Sie Neues Konto erstellen aus.
  4. Wählen Sie Google Ads-Konto aus.
  5. Geben Sie einen Kontonamen ein, z.B. Test Client Account A.
  6. Wählen Sie eine Zeitzone und eine Währung aus und klicken Sie dann auf Speichern und fortfahren.
  7. Notieren Sie sich die 10-stellige Kundennummer (z.B. 1234567890 ohne Bindestriche) dieses neuen Kundenkontos.

Wichtige Regeln für Testkonten

  • Verwendung des Entwicklertokens: Beantragen Sie kein Entwicklertoken über Ihr Testverwaltungskonto. Verwenden Sie immer das ausstehende oder genehmigte Entwicklertoken aus Ihrem Produktionsverwaltungskonto.
  • Abrechnung: In Testkonten werden keine tatsächlichen Anzeigen ausgeliefert. Sie müssen daher keine echten Abrechnungsinformationen eingeben.

4. Google Cloud-Projekt einrichten

Alle API-Anfragen müssen mit einem Google Cloud-Projekt authentifiziert werden, in dem die Google Ads API aktiviert ist.

Anleitung zum Aktivieren der API

  1. Gehen Sie zur Google Cloud Console.
  2. Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes Projekt aus.
  3. Rufen Sie APIs und Dienste > Bibliothek auf.
  4. Suchen Sie nach Google Ads API und klicken Sie auf Aktivieren.

Preise und Abrechnung

  • Keine API-Gebühren: Das Erstellen eines Google Cloud-Projekts, das Aktivieren der Google Ads API und das Generieren von OAuth 2.0-Anmeldedaten sind völlig kostenlos. Google erhebt keine Gebühren für den Aufruf oder die Verwendung der Google Ads API.
  • Andere Cloud-Ressourcen: Google Cloud-Gebühren fallen nur an, wenn Sie andere kostenpflichtige Google Cloud-Dienste (z. B. Compute Engine, Cloud Run oder BigQuery) über die Limits der kostenlosen Stufe hinaus verwenden, um Ihre Anwendung zu hosten oder Ihre Anzeigendaten zu speichern.

5. Authentifizierung mit OAuth 2.0 konfigurieren

Die Google Ads API verwendet OAuth 2.0 zur Authentifizierung und Autorisierung von Anfragen.

Schritte für den Desktopanwendungsablauf

  1. Rufen Sie in Ihrem Google Cloud-Projekt APIs und Dienste > OAuth-Zustimmungsbildschirm auf und konfigurieren Sie den Zustimmungsbildschirm. Fügen Sie Ihre E-Mail-Adresse dem Bereich Testnutzer hinzu, während sich die App im Status „Testen“ befindet, um Zugriffsfehler während der Autorisierung zu vermeiden.
  2. Rufen Sie APIs und Dienste > Anmeldedaten auf.
  3. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
  4. Wählen Sie als Anwendungstyp Desktop-App aus.
  5. Klicken Sie auf Erstellen und laden Sie dann die OAuth-Anmeldedatendatei als client_secret.json herunter (oder kopieren Sie Ihre Client ID und Client Secret).

Aktualisierungstoken generieren

Sobald Sie Ihre Client-ID und Ihren Clientschlüssel haben, müssen Sie ein Aktualisierungstoken generieren. Sie können dies entweder mit dem Google OAuth 2.0 Playground oder einem Clientbibliothekskript tun.

Methode A: Google OAuth 2.0 Playground verwenden

  1. Rufen Sie den Google OAuth 2.0 Playground auf.
  2. Klicken Sie oben rechts auf das Zahnradsymbol (OAuth 2.0-Konfiguration).
  3. Klicken Sie das Kästchen Eigene OAuth-Anmeldedaten verwenden an.
  4. Geben Sie Ihre OAuth 2.0-Client ID und Client Secret ein und klicken Sie dann auf Schließen.
  5. Geben Sie links unter Schritt 1: APIs auswählen und autorisieren den Google Ads API-Bereich in das Feld „Eigene Bereiche eingeben“ ein: https://www.googleapis.com/auth/adwords
  6. Klicken Sie auf APIs autorisieren. Melden Sie sich mit dem Google-Konto an, das Zugriff auf Ihr Google Ads-Verwaltungskonto (oder Testkonto) hat, wenn Sie dazu aufgefordert werden.
  7. Klicken Sie auf dem Zustimmungsbildschirm auf Weiter.
  8. Klicken Sie unter Schritt 2: Autorisierungscode gegen Tokens austauschen auf die blaue Schaltfläche Autorisierungscode gegen Tokens austauschen.
  9. Ihr Refresh token und Access token werden im Antwort bereich angezeigt. Kopieren und speichern Sie das Refresh token.

Methode B: Clientbibliothekskript verwenden (Python-Beispiel)

Die offizielle Python-Clientbibliothek bietet ein integriertes Hilfsskript zum Generieren von Anmeldedaten. Alternativ können Sie client_secret.json über die Google Cloud Console herunterladen und das folgende eigenständige Python-Skript ausführen:

  1. Installieren Sie die erforderliche OAuth-Bibliothek:
pip install google-auth-oauthlib
  1. Erstellen Sie im selben Verzeichnis wie client_secret.json ein Skript mit dem Namen generate_refresh_token.py und führen Sie es aus:
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Clientbibliothek und Anmeldedaten einrichten

Google bietet offiziell unterstützte Clientbibliotheken, die die Authentifizierung, Serialisierung und Kommunikation mit den gRPC-Endpunkten übernehmen.

Unterstützte Sprachen

  • Python: pip install google-ads
  • Java: Über Maven oder Gradle verfügbar
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads
  • Perl: cpanm Google::Ads::GoogleAds::Client

Konfigurationsdatei (google-ads.yaml)

Erstellen Sie eine Konfigurationsdatei mit Ihren Anmeldedaten. Standardmäßig sucht die Initialisierungsmethode der Clientbibliothek (z.B. GoogleAdsClient.load_from_storage()) automatisch an zwei Orten nach google-ads.yaml:

  1. Das aktuelle Arbeitsverzeichnis , aus dem Ihr Skript ausgeführt wird.
  2. Ihr Home-Verzeichnis (~ unter Linux/macOS oder %HOMEPATH% unter Windows).

Wenn Sie die Datei an einem benutzerdefinierten Speicherort speichern, können Sie den Pfad explizit an die Initialisierungsmethode übergeben (z.B., load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Der erste API-Aufruf

Führen Sie ein Schnellstartskript aus, um vorhandene Kampagnen aus Ihrem Testkonto abzurufen und so Ihre Onboarding-Einrichtung zu überprüfen.

Beispielskript für Python (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Best Practices und Ressourcen

  • Protokollierung: Aktivieren Sie die detaillierte Protokollierung in Ihrer Clientbibliothek, um Anfragen- und Antwort-IDs (request-id) zu erfassen. Diese sind wichtig, wenn Sie Support von Google anfordern.
  • Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung für GoogleAdsException und verwalten Sie insbesondere Ratenlimits (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Offizielle Dokumentation: Google Ads API-Entwicklerdokumentation
  • Clientbibliotheken und Codebeispiele: GitHub-Repositories für Google Ads
Zurück
Einführung
Weiter
Schnelleinstieg