Authentifizierung und Autorisierung

Wie bei anderen Google-APIs wird bei der Google Ads API zur Authentifizierung und Autorisierung das OAuth 2.0-Protokoll verwendet. Mit OAuth 2.0 kann Ihre Google Ads API-Clientanwendung 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 gängigsten OAuth 2.0-Abläufen konfigurieren und welche Anmeldedaten dafür erforderlich sind.

Weitere Informationen zum Google Ads API-Zugriffsmodell finden Sie im Leitfaden zum Google Ads-Zugriffsmodell.

Anmeldedaten

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

Entwickler-Token

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

Das Entwickler-Token ist zwar mit einem Verwaltungskonto verknüpft, bietet aber keinen Zugriff auf dieses Konto. Stattdessen gewährt das Entwicklertoken allgemeinen Zugriff auf die API. Der Zugriff auf Kontoebene wird über OAuth 2.0 konfiguriert.

In der Clientbibliothek wird das Entwicklertoken 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 OAuth 2.0-Anmeldedaten angeben. Welche Art von Anmeldedaten erforderlich ist, hängt vom verwendeten OAuth 2.0-Ablauf ab.

Die Bibliothek unterstützt drei Abläufe:

  • Ablauf für Dienstkonten
  • Authentifizierungsvorgang für Einzelnutzer
  • Authentifizierungsablauf für mehrere Nutzer

Weitere Informationen zu den Google Ads API-OAuth-Abläufen 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

Geben Sie optional die Kundennummer eines Verwaltungskontos an, über das auf das Konto für die Anzeigenbereitstellung zugegriffen werden kann. Dies muss angegeben werden, wenn Sie über ein Verwaltungskonto auf das Kundenkonto zugreifen. Sie müssen nicht alle Verwaltungskonten im Pfad zur Kunden-ID angeben, sondern nur die oberste Manager-ID, die Sie für Zugriffsrechte 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 ads.properties-Datei, Umgebungsvariablen oder programmatisch konfigurieren. In diesem Leitfaden geht es um die Verwendung einer ads.properties-Datei. Weitere Informationen zu allen Optionen finden Sie im Konfigurationsleitfaden.

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

OAuth-Ablä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 Interaktion mit Menschen 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.

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

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 im Leitfaden für Dienstkonten.

Authentifizierungsvorgang für Einzelnutzer

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. Eine gängige Vorgehensweise ist, 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 im Leitfaden für den Authentifizierungs-Workflow für einzelne Nutzer.

Authentifizierungsablauf 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. GenerateUserCredentials ist ein Befehlszeilenbeispiel, das zeigt, wie Sie zur Laufzeit die Nutzerauthentifizierung abrufen, um ihre Google Ads-Konten in ihrem Namen zu verwalten. Sie können dieses Codebeispiel als Referenz für die Entwicklung von Desktop-Apps verwenden, 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 im Leitfaden zum Workflow für die Multi-User-Authentifizierung.

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 veranschaulichen, wie solche Fälle behandelt werden.

  1. Im Codebeispiel GetAccountHierarchy wird gezeigt, 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.

Das 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.

Achten Sie bei der Google Ads API darauf, dass Ihre Standardanmeldedaten für die Anwendung auf den OAuth 2.0-Bereich https://www.googleapis.com/auth/adwords zugreifen können.

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