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.

Google Ads-Zugriffsmodell

Wenn Sie effektiv mit der Google Ads API arbeiten möchten, müssen Sie wissen, wie das Zugriffsmodell von Google Ads funktioniert. Weitere Informationen finden Sie im Leitfaden zum Google Ads-Zugriffsmodell.

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. Erstellen 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 Basisverzeichnis und ändern Sie die Datei, um den Speicherort der Schlüsseldatei Ihres Dienstkontos anzugeben (und optional die E-Mail-Adresse des Nutzers, dessen Identität bei der Verwendung der domainweiten Delegation von Google Workspace 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'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Wenn Sie diese Informationen nicht in einer Datei speichern, sondern Umgebungsvariablen verwenden möchten, können Sie GOOGLE_ADS_JSON_KEY_FILE_PATH (und optional GOOGLE_ADS_IMPERSONATED_EMAIL) festlegen:

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Sie können den Pfad zur Dienstkontoschlüsseldatei (und optional die E-Mail-Adresse des imitierten Dienstkontos) auch programmatisch zur Laufzeit übergeben:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Alternativ können Sie das Gem googleauth verwenden, um Dienstkonto-Anmeldedaten zu erstellen und credentials.updater_proc an config.authentication zu übergeben:

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 = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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

Die OAuth 2.0-Anmeldedaten können für Ruby konfiguriert werden. Kopieren Sie dazu die Datei google_ads_config.rb in Ihr Basisverzeichnis und ändern Sie sie so, 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 Basisverzeichnis, wenn er ohne Argumente instanziiert wird:

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

Wenn Sie die Datei lieber an einem anderen Ort speichern möchten, können Sie den Client 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, sondern Umgebungsvariablen verwenden möchten, 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 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. Ihre App erstellt und verwaltet die OAuth 2.0-Nutzeranmeldedaten. Dieser Workflow kann ähnlich wie der Single-User-Flow konfiguriert werden, wobei auch die login_customer_id angegeben wird.

Es wird empfohlen, eine Konfigurationsdatei zu verwenden. Kopieren Sie die Datei google_ads_config.rb in Ihr Basisverzeichnis 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 to 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 Basisverzeichnis, wenn er ohne Argumente instanziiert wird:

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

Wenn Sie die Datei lieber an einem anderen Ort speichern möchten, können Sie den Client 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, sondern Umgebungsvariablen verwenden möchten, 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 im Leitfaden zum Workflow für die Authentifizierung mehrerer Nutzer. Die Ruby-Clientbibliothek enthält ein Codebeispiel als Referenz. Das Befehlszeilen-Codebeispiel GenerateUserCredentials zeigt, wie Sie zur Laufzeit die Nutzerauthentifizierung erhalten, um die Google Ads-Konten der Nutzer in deren Namen zu verwalten. Sie können dieses Codebeispiel als Referenz für die Entwicklung von Desktop-Anwendungen verwenden, die eine Nutzerauthentifizierung erfordern.

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 Ruby-Clientbibliothek bietet die folgenden Codebeispiele, die zeigen, 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 login_customer_id verwendet werden.

Standardanmeldedaten für Anwendungen

Die Ruby-Clientbibliothek (v36.1.0 und höher) unterstützt auch die Authentifizierung mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). Damit können Sie die Standardanmeldedaten für Ihre Anwendung festlegen, ohne die OAuth 2.0-Informationen in der Anwendungskonfiguration 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 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, verwenden Sie das Google Cloud-Befehlszeilentool und authentifizieren Sie sich für ADC:

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 so aktualisieren, dass sie ADC verwendet.

Kopieren Sie die Datei google_ads_config.rb in Ihr Basisverzeichnis und legen Sie für use_application_default_credentials den Wert 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, sondern Umgebungsvariablen verwenden möchten, 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, legen Sie config.use_application_default_credentials = true fest und geben Sie keine expliziten OAuth 2.0-Anmeldedaten an. Die Bibliothek erkennt und verwendet automatisch die vom Google Cloud-Befehlszeilentool eingerichteten Anmeldedaten:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # 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 client_id, client_secret, or refresh_token here.
end

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