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 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, sollten Sie wissen, wie das Google Ads-Zugriffsmodell funktioniert. Wir empfehlen Ihnen, den Leitfaden zum Google Ads-Zugriffsmodell zu lesen.

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 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. Die Python-Bibliothek ist so konfiguriert:

  • Wenn Sie eine google-ads.yaml-Datei oder einen YAML-String verwenden, fügen Sie Ihrer Konfiguration Folgendes hinzu, um den Pfad zur JSON-Datei mit dem privaten Schlüssel in Ihrer lokalen Umgebung festzulegen:

    json_key_file_path: JSON_KEY_FILE_PATH

    Rufen Sie dann die Methoden load_from_storage oder load_from_string auf:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • Wenn Sie eine dict zum Konfigurieren der Bibliothek verwenden, fügen Sie das folgende Schlüssel-Wert-Paar ein und rufen Sie die Methode load_from_dict auf, wobei Sie die Konfiguration dict übergeben:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • Wenn Sie Umgebungsvariablen verwenden, fügen Sie Ihrer bash-Konfiguration oder -Umgebung Folgendes hinzu:

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Rufen Sie dann die Methode load_from_env auf:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

Wenn die Konfigurationsoption json_key_file_path in einer dieser Konfigurationsmethoden vorhanden ist und die Option use_application_default_credentials auf False festgelegt oder nicht festgelegt ist, wird die Bibliothek automatisch mit dem Dienstkonto-Ablauf autorisiert.

Weitere Informationen finden Sie im Leitfaden für Dienstkonten.

Authentifizierungsvorgang für Einzelnutzer

Dieser Workflow kann verwendet werden, wenn Sie keine Dienstkonten nutzen 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 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 Tool wie die gcloud CLI oder das generate_user_credentials-Codebeispiel aus, um Ihre App zu autorisieren, alle seine Google Ads-Konten in seinem Namen zu verwalten.

Die Bibliothek kann mit den OAuth 2.0-Anmeldedaten des Nutzers initialisiert werden:

Bei Verwendung des gcloud CLI-Tools (empfohlen)

  1. Folgen Sie der Dokumentation unter Anmeldedaten generieren, um Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) in Ihrer lokalen Umgebung einzurichten.

  2. Fügen Sie Ihrer google-ads.yaml-Datei oder Ihrem YAML-String die folgende Konfiguration hinzu:

    use_application_default_credentials: true

    Rufen Sie dann die Methode load_from_storage oder load_from_string auf:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Wenn Sie eine dict zum Konfigurieren der Bibliothek verwenden, fügen Sie das folgende Schlüssel/Wert-Paar ein und rufen Sie die Methode load_from_dict auf:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Wenn Sie Umgebungsvariablen verwenden, fügen Sie Ihrer bash-Konfiguration oder -Umgebung Folgendes hinzu:

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    Rufen Sie dann die Methode load_from_env auf:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Wenn Sie OAuth-Tokens direkt verarbeiten

  1. Folgen Sie der Anleitung zum Einrichten eines Konsolenprojekts und laden Sie die JSON-Datei herunter, die die Client-ID und das Client-Secret Ihres Projekts enthält.

  2. Klonen Sie die Python-Clientbibliothek auf Ihren Computer und wechseln Sie in das entsprechende Verzeichnis:

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. Führen Sie das Beispiel aus und geben Sie einen absoluten Pfad zur JSON-Datei an, die Sie in Schritt 1 heruntergeladen haben:

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    Nach Abschluss wird ein Aktualisierungstoken in der Konsole ausgegeben. Kopieren Sie sie und speichern Sie sie für den nächsten Schritt.

  4. Konfigurieren Sie die Bibliothek, indem Sie die folgenden Einstellungen zu Ihrer Konfiguration hinzufügen:

    Fügen Sie Ihrer google-ads.yaml-Datei oder Ihrem YAML-String die folgende Konfiguration hinzu:

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Rufen Sie dann die Methode load_from_storage oder load_from_string auf:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Wenn Sie eine dict zum Konfigurieren der Bibliothek verwenden, fügen Sie die folgenden Schlüssel/Wert-Paare ein und rufen Sie die Methode load_from_dict auf:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Wenn Sie Umgebungsvariablen verwenden, fügen Sie Ihrer bash-Konfiguration oder -Umgebung Folgendes hinzu:

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    Rufen Sie dann die Methode load_from_env auf:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Weitere Informationen finden Sie im Leitfaden für den Authentifizierungsablauf für einzelne Nutzer.

Authentifizierungsablauf für mehrere Nutzer

Dieser Workflow wird empfohlen, 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. Die Bibliothek kann mit den Anmeldedaten des Nutzers initialisiert werden. Dabei wird davon ausgegangen, dass Ihre Anwendung Anmeldedaten zur Laufzeit abruft, entweder durch Ausführen eines Autorisierungsvorgangs oder durch Laden aus einem Datenspeicher:

Eine dict ist der einfachste Konfigurationsmechanismus, der beim Abrufen von Anmeldedaten zur Laufzeit verwendet werden kann:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

Weitere Informationen finden Sie im Leitfaden zum Workflow für die Multi-User-Authentifizierung.

Manuelle Authentifizierung

Sie können Anmeldedaten für die Authentifizierung mit einer beliebigen Methode generieren und sie der GoogleAdsClient manuell bereitstellen, indem Sie die Clientklasse direkt instanziieren. Angenommen, das von Ihnen erstellte Anmeldedatenobjekt ist eine Instanz von google.auth.credentials.Credentials. Dann können Sie es so übergeben:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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 Python-Clientbibliothek enthält die folgenden Codebeispiele, die veranschaulichen, wie solche Fälle behandelt werden.

  1. Im Codebeispiel get_account_hierarchy wird gezeigt, wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
  2. Das Codebeispiel für list_accessible_customers 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 login_customer_id verwendet werden.