Authentifizierung und Autorisierung

Wie bei anderen Google APIs wird auch bei der Google Ads API das OAuth 2.0-Protokoll für die Authentifizierung und Autorisierung verwendet. Mit OAuth 2.0 kann Ihre Google Ads API-Clientanwendung 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 Google Ads-Zugriffsmodell funktioniert. Weitere Informationen finden Sie im Leitfaden zum Google Ads-Zugriffsmodell.

OAuth-Arbeitsabläufe

Es gibt drei gängige Workflows für die Arbeit mit der Google Ads API.

Ablauf für Dienstkonten

Dies ist der empfohlene Workflow, wenn für Ihren Workflow keine menschliche Interaktion erforderlich ist. 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 mit 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 für den privaten Schlüssel fest (und optional impersonatedEmail, wenn Sie die domainweite Delegierung für Google Workspace verwenden). 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 für den Dienstkontoworkflow.

Authentifizierungsvorgang 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. Einem einzelnen Nutzer Zugriff auf alle Konten gewähren, die mit der Google Ads API verwaltet werden sollen Eine gängige Vorgehensweise 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 generate_user_credentials.pl-Codebeispiel aus, um Ihre App zu autorisieren, alle seine Google Ads-Konten in seinem Namen zu verwalten.

Bei 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 ändern, bevor Sie es ausführen, 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 der App erlauben 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, mit dem Sie auf Google Ads zugreifen. In der Regel ist das ein E-Mail-Konto mit Zugriff auf ein Google Ads-Verwaltungskonto, das alle Konten enthält, die Sie in der zugehörigen 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 wurde ausgeführt und zeigt Ihr Aktualisierungstoken und einige Anleitungen an, gefolgt von der Anleitung, die Sie zum Konfigurieren der Clientbibliothek benötigen:

    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 Vorgang 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 beim Instanziieren der Bibliothek zur Laufzeit zu verwenden.

Die Bibliothek kann mit den OAuth 2.0-Anmeldedaten des Nutzers initialisiert werden, indem Sie Folgendes in googleads.properties 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 für den Authentifizierungs-Workflow für einzelne Nutzer.

Authentifizierungsvorgang für mehrere Nutzer

Dieser Workflow wird empfohlen, wenn sich Nutzer in Ihrer App anmelden und Ihre App 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 und Ihre Anwendung speichert und verwendet das Aktualisierungstoken des Nutzers, um API-Aufrufe in seinem Namen auszuführen.

Die Konfiguration für die Verwendung der abgerufenen Anmeldedaten ist dieselbe wie für den Authentifizierungsvorgang 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 für den Workflow zur Authentifizierung für mehrere Nutzer.

Was ist, wenn mein Nutzer mehrere Konten verwaltet?

Es ist üblich, dass ein Nutzer mehrere Google Ads-Konten verwaltet, entweder durch direkten Zugriff auf die Konten oder über ein Google Ads-Verwaltungskonto. Die Perl-Clientbibliothek enthält Beispiele, die veranschaulichen, 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 list_accessible_customers.pl-Beispiel 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 für die Umgebungsvariable GOOGLE_ADS_LOGIN_CUSTOMER_ID verwendet werden.