Authentifizierung und Autorisierung

Wie andere Google APIs verwendet 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 die Anmeldedaten des Nutzers verarbeiten oder speichern zu 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-Workflows

Bei der Arbeit mit der Google Ads API werden drei gängige Workflows verwendet.

Dienstkonto-Workflow

Dies ist der empfohlene Workflow, wenn für Ihren Workflow keine Interaktion mit einem Nutzer 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 OAuth 2.0 für den API-Zugriff mit Ihren eigenen Anmeldedaten und einem Dienstkonto in der Perl-Clientbibliothek ein:

1. OAuth 2.0-Anmeldedaten erstellen :

   Folgen Sie der Anleitung, um ein Dienstkonto und eine JSON-Schlüssel datei zu generieren.

2. Clientbibliothek einrichten :

   Legen Sie in der Konfiguration den JSON-Pfad des privaten Schlüssels und optional impersonatedEmail fest, wenn Sie die domainweite Google Workspace-Delegierung 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
   

   Wichtiger Hinweis: Beim Laden von Konfigurationen sucht die Bibliothek zuerst nach Anmeldedaten aus den OAuth 2.0-Desktop- oder Web-App-Abläufen und verwendet sie dann, falls sie gefunden werden. Wenn Sie ein Dienstkonto für die Authentifizierung verwenden möchten, dürfen in Ihrer Konfiguration keine Anmeldedaten für die anderen Abläufe vorhanden sein.

   Weitere Informationen finden Sie im Leitfaden zum Dienstkonto-Workflow.

Authentifizierungs-Workflow 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 mit der 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 unter 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 Eingaben machen müssen.

1. Führen Sie in einem Terminal das generate_user_credentials.pl Beispiel im examples Verzeichnis aus. Sie können entweder die Werte INSERT_XXX_HERE 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 dies ein E-Mail-Konto mit Zugriff auf ein Google Ads-Verwaltungskonto, das alle Konten enthält, die Sie in der Kontohierarchie verwalten müssen. Klicken Sie auf dem OAuth 2.0-Zustimmungsbildschirm auf Weiter.

   

   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, auf der Sie das Codebeispiel ausführen. Sie sehen, dass das Codebeispiel abgeschlossen ist und Ihr Aktualisierungstoken und einige Anweisungen angezeigt werden. Danach folgen die Anweisungen, 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 zu verwenden, wenn Sie die Bibliothek zur Laufzeit instanziieren.

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.

Authentifizierungs-Workflow für mehrere Nutzer

Dies ist der empfohlene Workflow, 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 Webanwendungs-Workflow 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 Authentifizierungs-Workflow 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 Authentifizierungs-Workflow für mehrere Nutzer.

Was ist, wenn mein Nutzer mehrere Konten verwaltet?

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

1. Das get_account_hierarchy.pl Beispiel zeigt wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
2. Das list_accessible_customers.pl Beispiel zeigt, 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.