Authentifizierung und Autorisierung

Wie andere Google APIs verwendet auch die Google Ads API das OAuth 2.0-Protokoll für die Authentifizierung und Autorisierung. Mit OAuth 2.0 kann Ihre Google Ads API-Client-App auf das Google Ads-Konto eines Nutzers zugreifen, ohne dass die Anmeldedaten des Nutzers verarbeitet oder gespeichert werden müssen.

Google Ads-Zugriffsmodell

Wenn Sie effektiv mit der Google Ads API arbeiten möchten, müssen Sie wissen, wie das Zugriffsmodell von Google Ads funktioniert. Weitere Informationen finden Sie im Leitfaden zum Google Ads-Zugriffsmodell.

OAuth-Workflows

Bei der Arbeit mit der Google Ads API gibt es drei gängige Workflows.

Dienstkonto-Ablauf

Dies ist der empfohlene Workflow, wenn Ihr Workflow keine menschliche Interaktion erfordert. Für diesen Workflow ist ein Konfigurationsschritt erforderlich, bei dem der Nutzer seinem Google Ads-Konto ein Dienstkonto hinzufügt. Die App kann dann die Anmeldedaten des Dienstkontos verwenden, um das Google Ads-Konto des Nutzers zu verwalten.

So richten Sie OAuth2 für den API-Zugriff mit Ihren eigenen Anmeldedaten und einem Dienstkonto in der Perl-Clientbibliothek ein:

  1. OAuth2-Anmeldedaten erstellen:

    Folgen Sie der Anleitung zum Generieren eines Dienstkontos und einer JSON-Schlüsseldatei.

  2. Clientbibliothek einrichten:

    Legen Sie in Ihrer Konfiguration den JSON-Pfad des privaten Schlüssels (und optional impersonatedEmail, wenn Sie die domainweite Delegation von Google Workspace verwenden) fest. Wenn Sie eine googleads.properties-Datei verwenden, fügen Sie Folgendes hinzu:

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
# Optional unless using Google Workspace domain-wide delegation:
impersonatedEmail=IMPERSONATED_EMAIL
loginCustomerId=LOGIN_CUSTOMER_ID

    Wenn Sie Umgebungsvariablen verwenden, fügen Sie Ihrer Bash-Konfiguration oder -Umgebung Folgendes hinzu:

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=\
IMPERSONATED_EMAIL
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

    Weitere Informationen finden Sie im Leitfaden zum Dienstkonto-Workflow.

Authentifizierungsablauf für einzelne Nutzer

Dieser Workflow kann verwendet werden, wenn Sie keine Dienstkonten verwenden können. Für diesen Workflow sind zwei Konfigurationsschritte erforderlich:

  1. Gewähren Sie einem einzelnen Nutzer Zugriff auf alle Konten, die über die Google Ads API verwaltet werden sollen. Ein gängiger Ansatz besteht darin, dem Nutzer Zugriff auf ein Google Ads API-Verwaltungskonto zu gewähren und alle Google Ads-Konten mit diesem Verwaltungskonto zu verknüpfen.
  2. Der Nutzer führt das Codebeispiel generate_user_credentials.pl aus, um Ihre App zu autorisieren, alle seine Google Ads-Konten in seinem Namen zu verwalten.

In den folgenden Schritten wird ein interaktives Codebeispiel ausgeführt, für das Sie dann Eingaben machen müssen.

  1. Führen Sie in einem Terminal das Beispiel generate_user_credentials.pl im Verzeichnis examples aus. Sie können entweder die INSERT_XXX_HERE-Werte im Beispiel vor der Ausführung ändern oder die Befehlszeilenargumente -client_id für die Client-ID und -client_secret für den Clientschlüssel verwenden.

    perl generate_user_credentials.pl \
  -client_id OAUTH_CLIENT_ID \
  -client_secret OAUTH_CLIENT_SECRET

  2. In diesem Codebeispiel werden Sie aufgefordert, eine URL aufzurufen, über die Sie die App autorisieren müssen, in Ihrem Namen auf Ihr Google Ads-Konto zuzugreifen.

    Paste this url in your browser:
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline...

    Rufen Sie die URL in einer privaten Browsersitzung oder einem Inkognitofenster auf. Melden Sie sich mit dem Google-Konto an, das Sie für den Zugriff auf Google Ads verwenden. In der Regel ist das ein E-Mail-Konto, das Zugriff auf ein Google Ads-Verwaltungskonto hat, das alle Konten enthält, die Sie in der Kontohierarchie verwalten müssen. Klicken Sie auf dem OAuth 2.0-Zustimmungsbildschirm auf Weiter.

    OAuth 2.0-Zustimmungsbildschirm

    Sie werden auf eine Seite mit einer Meldung weitergeleitet, die angibt, dass die Autorisierung erfolgreich war.

    Authorization code was successfully retrieved.

  3. Kehren Sie zur Konsole zurück, in der Sie das Codebeispiel ausführen. Das Codebeispiel ist abgeschlossen und zeigt Ihr Aktualisierungstoken und einige Anweisungen an, gefolgt von den Anweisungen, die Sie zum Konfigurieren der Clientbibliothek befolgen müssen:

    Replace the following keys and values in your googleads.properties
configuration file:

clientId=***********************apps.googleusercontent.com
clientSecret=****
refreshToken=****

  4. Drücken Sie Ctrl + C, um den Prozess zu beenden. Kopieren Sie dann das generierte Aktualisierungstoken zusammen mit der Client-ID und dem Clientschlüssel in Ihre googleads.properties-Datei oder speichern Sie es an einem anderen Ort, um es bei der Instanziierung der Bibliothek zur Laufzeit zu verwenden.

Die Bibliothek kann mit den OAuth 2.0-Anmeldedaten des Nutzers initialisiert werden, indem Sie in googleads.properties Folgendes festlegen:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Alternativ können Sie Umgebungsvariablen verwenden:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

Weitere Informationen finden Sie im Leitfaden zum Authentifizierungs-Workflow für einzelne Nutzer.

Authentifizierungsvorgang für mehrere Nutzer

Das ist der empfohlene Workflow, wenn Nutzer sich in Ihrer App anmelden und sie autorisieren können, ihre Google Ads-Konten in ihrem Namen zu verwalten. Ihre App erstellt und verwaltet die OAuth 2.0-Nutzeranmeldedaten.

Für Perl würden Sie in der Regel einen Webanwendungsablauf implementieren, bei dem Ihre Anwendung die OAuth 2.0-Weiterleitung und die Tokenverwaltung übernimmt. Der Nutzer authentifiziert sich über Ihre Anwendung. Diese speichert das Aktualisierungstoken des Nutzers und verwendet es, um in seinem Namen API-Aufrufe auszuführen.

Die Konfiguration für die Verwendung der erhaltenen Anmeldedaten ist dieselbe wie für den Authentifizierungsablauf für einzelne Nutzer:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Alternativ können Sie Umgebungsvariablen verwenden:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

Weitere Informationen finden Sie im Leitfaden zum Workflow für die Authentifizierung mehrerer Nutzer.

Was ist, wenn ein Nutzer mehrere Konten verwaltet?

Es ist üblich, dass ein Nutzer mehr als ein Google Ads-Konto verwaltet, entweder über den direkten Zugriff auf Konten oder über ein Google Ads-Verwaltungskonto. Die Perl-Clientbibliothek enthält Beispiele, die zeigen, wie solche Fälle behandelt werden:

  1. Im Beispiel get_account_hierarchy.pl wird gezeigt, wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
  2. Im Beispiel list_accessible_customers.pl wird gezeigt, wie Sie die Liste aller Konten abrufen, auf die ein Nutzer direkten Zugriff hat. Diese Konten können dann als gültige Werte für die Einstellung loginCustomerId in der Datei googleads.properties oder die Umgebungsvariable GOOGLE_ADS_LOGIN_CUSTOMER_ID verwendet werden.