Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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-Clientanwendung 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 Google Ads-Zugriffsmodell funktioniert. Weitere Informationen finden Sie im Leitfaden zum Google Ads-Zugriffsmodell.

OAuth-Arbeitsablä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 menschliche Interaktion 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. Erstellen und laden Sie die JSON-Schlüsseldatei in der Google Cloud Console herunter, um dies zu konfigurieren. Kopieren Sie dann google_ads_config.rb in Ihr Basisverzeichnis und ändern Sie die Datei, um den Speicherort der Dienstkontoschlüsseldatei anzugeben (und optional die E-Mail-Adresse des Nutzers, der bei der Verwendung der domainweiten Delegierung von Google Workspace imitiert 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 lieber 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 Nutzers) 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 googleauth-Gem verwenden, um Anmeldedaten für Dienstkonten 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 für Dienstkonto-Workflows.

Authentifizierungsvorgang für einzelne Nutzer

Dieser Workflow kann verwendet werden, wenn Sie keine Dienstkonten verwenden können. Für diesen Workflow sind zwei Konfigurationsschritte erforderlich:

Einem einzelnen Nutzer Zugriff auf alle Konten gewähren, die mit der Google Ads API verwaltet werden sollen Eine gängige Vorgehensweise 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.
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, indem Sie die Datei google_ads_config.rb 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 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 lieber Umgebungsvariablen verwenden möchten, können Sie jede Variable einzeln 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 für den Authentifizierungs-Workflow für einzelne Nutzer.

Authentifizierungsvorgang 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. Ihre App erstellt und verwaltet die OAuth 2.0-Nutzeranmeldedaten. Dieser Workflow kann ähnlich wie der Einzelnutzer-Ablauf konfiguriert werden. Dabei wird auch login_customer_id angegeben.

Es wird empfohlen, eine Konfigurationsdatei zu verwenden. Kopieren Sie die Datei 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 Kunden-ID 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 Home-Verzeichnis, 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 lieber Umgebungsvariablen verwenden möchten, können Sie jede Variable einzeln 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 für den Workflow zur Authentifizierung für mehrere Nutzer. Die Ruby-Clientbibliothek enthält ein Codebeispiel als Referenz. Das GenerateUserCredentials-Befehlszeilenbeispiel veranschaulicht, wie Sie die Nutzerauthentifizierung zur Laufzeit abrufen, um ihre Google Ads-Konten 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.

Mehrere Konten verwalten

Es ist üblich, dass ein Nutzer mehrere Google Ads-Konten verwaltet, entweder durch direkten Zugriff auf die Konten oder über ein Google Ads-Verwaltungskonto. Die Ruby-Clientbibliothek enthält die folgenden Codebeispiele, die zeigen, wie solche Fälle behandelt werden:

Im GetAccountHierarchy-Codebeispiel wird gezeigt, wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
Im ListAccessibleCustomers-Codebeispiel 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 (Version 36.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 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, 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, in dem Sie den Authentifizierungsvorgang für Ihr Google-Konto abschließen können. Nach der Autorisierung werden die Anmeldedaten an einem Standardspeicherort gespeichert. Anschließend müssen Sie Ihre Anwendung aktualisieren, damit sie ADC verwendet.

Kopieren Sie die Datei google_ads_config.rb in Ihr Home-Verzeichnis 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 lieber 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 Anmeldedaten, die vom Google Cloud-Befehlszeilentool eingerichtet wurden:

# 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 Seite Konfiguration.