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-Client-App auf das Google Ads-Konto eines Nutzers zugreifen, ohne dass die Anmeldedaten des Nutzers verarbeitet oder gespeichert werden 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 OAuth 2.0-Anmeldedaten und in einigen Fällen eine Anmelde-Kundennummer erforderlich.

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. Welche Anmeldedaten erforderlich sind, hängt vom verwendeten OAuth 2.0-Vorgang ab.

Die Bibliothek unterstützt drei Abläufe:

  • Ablauf für Dienstkonten
  • Ablauf für die Authentifizierung einzelner Nutzer
  • Ablauf für die Authentifizierung mehrerer 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 Anmelldaten zu erhalten.

Anmelde-Kundennummer

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

In der Clientbibliothek wird die Anmelde-Kundennummer durch den Schlüssel api.googleads.loginCustomerId in der Datei ads.properties angegeben.

Konfiguration

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

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

OAuth-Workflows

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

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 ein Dienstkonto zu seinem Google Ads-Konto 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
# 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 Workflow für Dienstkonten.

Ablauf für die Authentifizierung einzelner 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 ein Befehlszeilentool wie gcloud CLI 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

Weitere Informationen finden Sie in der Anleitung zum Workflow für die Authentifizierung einzelner Nutzer.

Ablauf für die Authentifizierung mehrerer 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. GenerateUserCredentials ist ein Befehlszeilen-Code beispiel, 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

Weitere Informationen finden Sie in der Anleitung zum Workflow für die Authentifizierung mehrerer 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 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 Clientgeheimnis und das Aktualisierungstoken nicht festgelegt werden.