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-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 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. 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 des privaten Schlüssels in Ihrer lokalen Umgebung festzulegen (zusammen mit optionalem impersonated_email, wenn Sie die domainweite Delegierung verwenden):

    json_key_file_path: JSON_KEY_FILE_PATH
# Optional: only set if using Google Workspace domain-wide delegation:
# impersonated_email: IMPERSONATED_EMAIL

    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 die Bibliothek mit einer dict konfigurieren, fügen Sie das folgende Schlüssel/Wert-Paar ein und rufen Sie die Methode load_from_dict auf. Übergeben Sie dabei die Konfiguration dict:

    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, die Option use_application_default_credentials auf False gesetzt oder nicht festgelegt ist und die OAuth-Nutzeranmeldeschlüssel (client_id, client_secret und refresh_token) nicht festgelegt oder auskommentiert sind, autorisiert die Bibliothek automatisch über den Dienstkontofluss.

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 Tool wie die gcloud CLI oder das generate_user_credentials-Codebeispiel aus, um Ihre Anwendung zu autorisieren, alle seine Google Ads-Konten in seinem Namen zu verwalten.

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

Bei Verwendung der gcloud CLI (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 entweder die Methode load_from_storage oder load_from_string auf:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    Wenn Sie die Bibliothek mit einer dict konfigurieren, fügen Sie das folgende Schlüssel/Wert-Paar hinzu und rufen Sie die Methode load_from_dict auf:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "use_application_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_APPLICATION_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 Console-Projekts und laden Sie die JSON-Datei mit der Client-ID und dem Clientschlüssel Ihres Projekts herunter.

  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

    Anschließend wird ein Aktualisierungstoken in der Konsole ausgegeben. Kopieren Sie ihn und speichern Sie ihn für den nächsten Schritt.

  4. Konfigurieren Sie die Bibliothek, indem Sie der gewünschten Konfiguration die folgenden Einstellungen hinzufügen:

    Fügen Sie Ihrer google-ads.yaml- oder YAML-Datei 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 entweder die Methode load_from_storage oder load_from_string auf:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    Wenn Sie die Bibliothek mit einer dict-Datei konfigurieren, 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 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. Die Bibliothek kann mit den Anmeldedaten des Nutzers wie folgt initialisiert werden. Dabei wird davon ausgegangen, dass Ihre Anwendung die Anmeldedaten zur Laufzeit abruft, entweder durch Ausführen eines Autorisierungsablaufs oder durch Laden aus einem Datenspeicher:

Eine dict ist der einfachste Konfigurationsmechanismus, um Anmeldedaten zur Laufzeit abzurufen:

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 Authentifizierung mehrerer Nutzer.

Manuelle Authentifizierung

Sie können Authentifizierungsdaten mit einem beliebigen Ansatz generieren und sie dem 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,
    use_proto_plus=True,
)

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 Python-Clientbibliothek bietet die folgenden Codebeispiele, die zeigen, 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. Im Codebeispiel list_accessible_customers 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.