Authentifizierung und Autorisierung

Wie bei anderen Google APIs wird auch bei der Google Ads API zur Authentifizierung und Autorisierung das OAuth 2.0-Protokoll 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.

Informationen zum Google Ads-Zugriffsmodell

Wenn Sie effektiv mit der Google Ads API arbeiten möchten, sollten Sie wissen, wie das Google Ads-Zugriffsmodell funktioniert. Wir empfehlen Ihnen, die Anleitung zum Google Ads-Zugriffsmodell zu lesen.

OAuth-Workflows

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

Workflow für Dienstkonten

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. Konfigurieren Sie dazu die JSON-Schlüsseldatei in der Google Cloud Console und laden Sie sie herunter. Kopieren Sie dann google_ads_config.rb in Ihr Home-Verzeichnis und ändern Sie die Datei, um den Speicherort der Schlüsseldatei Ihres Dienstkontos und die E-Mail Adresse des Nutzers anzugeben, dessen Identität angenommen werden soll:

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Wenn Sie diese Informationen nicht in einer Datei speichern möchten, sondern lieber Umgebungsvariablen verwenden, können Sie GOOGLE_ADS_JSON_KEY_FILE_PATH und GOOGLE_ADS_IMPERSONATED_EMAIL festlegen.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Sie können die Informationen auch programmatisch zur Laufzeit übergeben, indem Sie mit dem googleauth-Gem Anmeldedaten aus einer JSON-Datei für Dienstkonten erstellen:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  # Inject the service account credentials
  config.oauth2_client = credentials
end

Weitere Informationen finden Sie in der Anleitung zum Workflow für Dienstkonten.

Workflow für die Authentifizierung eines einzelnen Nutzers

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 die gcloud CLI oder das GenerateUserCredentials Codebeispiel aus, um Ihrer App die Berechtigung zu erteilen, alle seine Google Ads-Konten in seinem Namen zu verwalten.

Die OAuth 2.0-Anmeldedaten können für Ruby konfiguriert werden, indem Sie die google_ads_config.rb-Datei in Ihr Home-Verzeichnis kopieren und sie so ändern, dass sie Ihre Client-ID, Ihren Clientschlüssel und Ihr Aktualisierungstoken enthält:

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Der Client liest die Konfigurationsdatei automatisch aus dem Home-Verzeichnis, wenn er ohne Argumente instanziiert wird:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Wenn Sie die Datei an einem anderen Ort speichern möchten, können Sie den Client auch instanziieren, indem Sie den Pfad zu dieser Datei übergeben:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Wenn Sie diese Informationen nicht in einer Datei speichern möchten, sondern lieber Umgebungsvariablen verwenden, können Sie jede davon festlegen:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Sie können die Informationen auch programmatisch zur Laufzeit übergeben:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

Weitere Informationen finden Sie in der Anleitung zum Workflow für die Authentifizierung eines einzelnen Nutzers.

Workflow für die Authentifizierung mehrerer Nutzer

Dies ist der empfohlene Workflow, wenn sich Nutzer in Ihrer App anmelden und Ihrer App die Berechtigung erteilen können, ihre Google Ads-Konten in ihrem Namen zu verwalten. Ihre App erstellt und verwaltet die OAuth 2.0-Nutzeranmeldedaten. Dieser Workflow kann ähnlich wie der Workflow für einen einzelnen Nutzer konfiguriert werden, aber mit der zusätzlichen Angabe von login_customer_id.

Wir empfehlen die Verwendung einer Konfigurationsdatei. Kopieren Sie die google_ads_config.rb in Ihr Home-Verzeichnis und ändern Sie sie so, dass sie Ihre Client-ID, Ihren Clientschlüssel, Ihr Aktualisierungstoken und Ihre Kundennummer enthält:

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

  # Required for manager accounts only: Specify the login customer ID used to
  # authenticate API calls. This will be the customer ID of the authenticated
  # manager account. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Der Client liest die Konfigurationsdatei automatisch aus dem Home-Verzeichnis, wenn er ohne Argumente instanziiert wird:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Wenn Sie die Datei an einem anderen Ort speichern möchten, können Sie den Client auch instanziieren, indem Sie den Pfad zu dieser Datei übergeben:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Wenn Sie diese Informationen nicht in einer Datei speichern möchten, sondern lieber Umgebungsvariablen verwenden, können Sie jede davon festlegen:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Sie können die Informationen auch programmatisch zur Laufzeit übergeben:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Weitere Informationen finden Sie in der Anleitung zum Workflow für die Authentifizierung mehrerer Nutzer. Die Ruby-Clientbibliothek enthält ein Codebeispiel als Referenz. `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.

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 Ruby-Clientbibliothek enthält die folgenden Codebeispiele, die zeigen, wie Sie solche Fälle behandeln.

  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 Ruby-Clientbibliothek unterstützt auch die Authentifizierung mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). So können Sie die Standardanmeldedaten für Ihre Anwendung festlegen, ohne die OAuth 2.0-Informationen in der Konfiguration Ihrer Anwendung konfigurieren zu müssen.

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.

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, empfehlen wir, das Google Cloud Befehlszeilentool zu verwenden und sich für ADC zu authentifizieren:

gcloud auth application-default login

Mit diesem Befehl wird ein Webbrowser geöffnet, um den Authentifizierungsvorgang für Ihr Google-Konto abzuschließen. Nach der Autorisierung werden die Anmeldedaten an einem Standardspeicherort gespeichert. Anschließend müssen Sie Ihre Anwendung aktualisieren, um ADC zu verwenden.

Wir empfehlen die Verwendung einer Konfigurationsdatei. Kopieren Sie die Datei google_ads_config.rb in Ihr Home-Verzeichnis, und legen Sie use_application_default_credentials auf true fest:

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

Wenn Sie diese Informationen nicht in einer Datei speichern möchten, sondern lieber Umgebungsvariablen verwenden, können Sie GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS festlegen:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Sie können die Informationen auch programmatisch zur Laufzeit übergeben. Wenn Sie den Client in Ihrem Ruby-Code initialisieren, geben Sie keine expliziten OAuth 2.0-Anmeldedaten an. Die Bibliothek erkennt und verwendet automatisch die Anmeldedaten, die mit dem Google Cloud-Befehlszeilentool eingerichtet wurden.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

Weitere Informationen zu den verfügbaren Optionen zum Konfigurieren der Ruby-Clientbibliothek finden Sie auf der KonfigurationSeite.