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.

In diesem Leitfaden wird beschrieben, wie Sie die Java-Clientbibliothek für die Google Ads API-Authentifizierung mit den drei gängigsten OAuth 2.0-Vorgängen konfigurieren. Außerdem werden die erforderlichen Anmeldedaten erläutert.

Weitere Informationen zum Zugriffsmodell der Google Ads API finden Sie im Leitfaden zum Zugriffsmodell für Google Ads.

Anmeldedaten

Für den Zugriff auf die Google Ads API sind OAuth 2.0-Anmeldedaten und in einigen Fällen eine Kundennummer für die Anmeldung erforderlich.

OAuth 2.0-Anmeldedaten

Wenn Sie sich als Google-Kontonutzer mit Zugriff auf Google Ads-Konten autorisieren möchten, müssen Sie OAuth 2.0-Anmeldedaten angeben. Die Art der erforderlichen Anmeldedaten hängt vom verwendeten OAuth 2.0-Vorgang ab.

Die Bibliothek unterstützt drei Abläufe:

  • Dienstkonto-Ablauf
  • Authentifizierungsablauf für einzelne Nutzer
  • Authentifizierungsvorgang für mehrere Nutzer

Weitere Informationen zu OAuth-Abläufen in der 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.

Kundennummer 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. Sie müssen nicht alle Verwaltungskonten auf dem Pfad zur Kundennummer angeben, 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 Kundennummer des Logins 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 diesem Leitfaden wird die Verwendung einer ads.properties-Datei beschrieben. Weitere Informationen zu allen Optionen finden Sie im Konfigurationsleitfaden.

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

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.

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

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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-Zielkonten mit diesem Verwaltungskonto zu verknüpfen.
  2. Der Nutzer führt ein Befehlszeilentool wie die gcloud-Befehlszeile oder das GenerateUserCredentials-Codebeispiel aus, um Ihre Anwendung zu autorisieren, alle seine Google Ads-Konten in seinem Namen zu verwalten.

Fügen Sie der Datei ads.properties Folgendes hinzu, sobald Sie diese Anmeldedaten haben:

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 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. Das Codebeispiel GenerateUserCredentials ist ein Befehlszeilentool, mit dem Sie die Nutzerauthentifizierung zur Laufzeit abrufen können, um die Google Ads-Konten der Nutzer in deren Namen zu verwalten. Sie können dieses Codebeispiel als Referenz für die Erstellung von Desktop- oder Webanwendungen verwenden, die eine Nutzerauthentifizierung erfordern.

Speichern Sie bei Anwendungen für mehrere Nutzer die OAuth 2.0-Client-ID und den Clientschlüssel Ihrer Anwendung in ads.properties (oder einem anderen Konfigurationsspeicher). Speichern Sie das Aktualisierungstoken jedes Endnutzers sicher in Ihrer Anwendungsdatenbank und übergeben Sie es beim Erstellen von UserCredentials und GoogleAdsClient programmatisch zur Laufzeit:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

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

Mehrere Konten verwalten

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 Java-Clientbibliothek bietet 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. Im Codebeispiel ListAccessibleCustomers 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 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 erforderlichen OAuth 2.0-Bereiche zugreifen können.

Achten Sie bei der Google Ads API darauf, dass 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 oder rufen Sie .enableApplicationDefaultCredentials() für GoogleAdsClient.newBuilder() auf. Wenn Sie Standardanmeldedaten für Anwendungen verwenden, sollten die Client-ID, der Clientschlüssel und das Aktualisierungstoken nicht festgelegt werden.