Authentifizierung und Autorisierung

Wie andere Google APIs verwendet auch die Google Ads API das OAuth 2.0-Protokoll zur 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.

In dieser Anleitung wird beschrieben, wie Sie die Java-Clientbibliothek für die Google Ads API-Authentifizierung mit den drei häufigsten OAuth 2.0-Abläufen konfigurieren. Außerdem werden die erforderlichen Anmeldedaten erläutert.

Weitere Informationen zum Zugriffsmodell der Google Ads API finden Sie in der Anleitung zum Zugriffsmodell der Google Ads API.

Anmeldedaten

Für den Zugriff auf die Google Ads API sind ein Entwickler-Token, OAuth 2.0-Anmeldedaten und in einigen Fällen eine Kunden-ID für die Anmeldung erforderlich.

Entwickler-Token

Das Entwickler-Token ist mit einem Verwaltungskonto verknüpft und kann in der Google Ads-Weboberfläche gefunden werden.

Obwohl das Entwickler-Token mit einem Verwaltungskonto verknüpft ist, gewährt es keinen Zugriff auf dieses Konto. Stattdessen gewährt das Entwickler-Token Zugriff auf die API im Allgemeinen. Der Zugriff auf Kontoebene wird über OAuth 2.0 konfiguriert.

In der Clientbibliothek wird das Entwickler-Token durch den Schlüssel api.googleads.developerToken in der Datei ads.properties angegeben.

OAuth 2.0-Anmeldedaten

Wenn Sie sich als Google-Kontonutzer mit Zugriff auf Google Ads-Konten autorisieren möchten, müssen Sie eine Reihe von OAuth 2.0-Anmeldedaten angeben. Die Art der erforderlichen Anmeldedaten variiert je nach verwendetem OAuth 2.0-Ablauf.

Die Bibliothek unterstützt drei Abläufe:

  • Dienstkontoablauf
  • Authentifizierungsablauf für einzelne Nutzer
  • Authentifizierungsablauf für mehrere Nutzer

Weitere Informationen zu OAuth-Abläufen für die Google Ads API finden Sie in der OAuth-Übersicht. Folgen Sie der Anleitung für den Ablauf, der Ihren Anforderungen am besten entspricht, um die erforderlichen Anmeldedaten zu erhalten.

Kunden-ID für die Anmeldung

Optional können Sie die Kundennummer eines Verwaltungskontos angeben, das Zugriff auf das Konto zur Anzeigenauslieferung bietet. Dies muss angegeben werden, wenn Sie über ein Verwaltungskonto auf das Kundenkonto zugreifen. Es ist nicht erforderlich, alle Verwaltungskonten auf dem Pfad zur Kunden-ID anzugeben, sondern nur die oberste Verwaltungs-ID, die Sie für Zugriffsberechtigungen verwenden. Weitere Informationen finden Sie in der zugehörigen Dokumentation.

In der Clientbibliothek wird die Kunden-ID für die Anmeldung durch den Schlüssel api.googleads.loginCustomerId in der Datei ads.properties angegeben.

Konfiguration

Sie können die Clientbibliothek mit einer ads.properties-Datei, Umgebungsvariablen oder programmatisch konfigurieren. In dieser Anleitung wird die Verwendung einer ads.properties-Datei beschrieben. Weitere Informationen zu allen Optionen finden Sie in der Konfigurations anleitung.

Wenn Sie eine ads.properties-Datei verwenden, platzieren Sie sie in Ihrem Basisverzeichnis: ~/ads.properties.

OAuth-Abläufe

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

Dienstkontoablauf

Dies ist der empfohlene Ablauf, wenn für Ihren Workflow keine menschliche Interaktion erforderlich ist. Für diesen Ablauf 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.

Sobald Sie die JSON-Datei mit dem privaten Schlüssel haben, fügen Sie der Datei ads.properties Folgendes hinzu:

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Weitere Informationen finden Sie in der Anleitung zum Dienstkontoablauf, um mehr zu erfahren.

Authentifizierungsablauf für einzelne Nutzer

Dieser Ablauf kann verwendet werden, wenn Sie keine Dienstkonten verwenden können. Für diesen Ablauf 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 ein Befehlszeilentool wie gcloud oder das GenerateUserCredentials Codebeispiel aus, um Ihre App zu autorisieren, alle seine Google Ads-Konten in seinem Namen zu verwalten.

Sobald Sie diese Anmeldedaten haben, fügen Sie der Datei ads.properties Folgendes hinzu:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Weitere Informationen finden Sie in der Anleitung zum Authentifizierungsablauf für einzelne Nutzer.

Authentifizierungsablauf für mehrere Nutzer

Dies ist der empfohlene Ablauf, wenn sich Nutzer in Ihrer App anmelden und Ihre App autorisieren können, ihre Google Ads-Konten in ihrem Namen zu verwalten. Das GenerateUserCredentials ist ein Befehlszeilen Codebeispiel, das zeigt, wie Sie zur Laufzeit die Nutzerauthentifizierung erhalten, um die Google Ads-Konten der Nutzer in ihrem Namen zu verwalten. Sie können dieses Codebeispiel als Referenz verwenden, um Desktop-Apps zu erstellen, für die eine Nutzerauthentifizierung erforderlich ist.

Fügen Sie der Datei ads.properties Folgendes hinzu:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Weitere Informationen finden Sie in der Anleitung zum Authentifizierungsablauf für mehrere Nutzer.

Was ist, wenn mein Nutzer mehrere Konten verwaltet?

Häufig verwaltet ein Nutzer mehrere Google Ads-Konten, entweder durch direkten Zugriff auf Konten oder über ein Google Ads-Verwaltungskonto. Die Java-Clientbibliothek enthält die folgenden Codebeispiele, die zeigen, wie solche Fälle behandelt werden.

  1. Das Codebeispiel GetAccountHierarchy zeigt, wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
  2. Das Codebeispiel ListAccessibleCustomers 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 verwendet werden.

Standardanmeldedaten für Anwendungen

Die Java-Clientbibliothek unterstützt auch die Authentifizierung mit Standardanmeldedaten für Anwendungen.

Dies ist besonders nützlich für die lokale Entwicklung oder für die Entwicklung mit verschiedenen Google APIs, da Sie dieselben Anmeldedaten wiederverwenden können, sofern sie auf die richtigen OAuth 2.0-Bereiche zugreifen können.

Für die Google Ads API müssen Ihre Standardanmeldedaten für Anwendungen auf den OAuth 2.0-Bereich https://www.googleapis.com/auth/adwords zugreifen können.

Wenn Sie Standardanmeldedaten für Anwendungen verwenden möchten, setzen Sie die Option api.googleads.useApplicationDefaultCredentials in der Datei ads.properties auf true. Bei Verwendung von Standardanmeldedaten für Anwendungen dürfen die Client-ID, das Clientschlüssel und das Aktualisierungstoken nicht festgelegt werden.