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. 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 (sowie optional impersonated_email, wenn Sie die domänenweite Delegation 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 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. Ü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-Nutzeranmeldedaten-Schlüssel (client_id, client_secret und refresh_token) nicht festgelegt oder auskommentiert sind, wird die Bibliothek automatisch über den Dienstkonto-Vorgang autorisiert.

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:

  1. 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.

  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:

Wenn Sie die gcloud CLI verwenden (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- oder YAML-Konfiguration Folgendes 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 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_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 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

    Anschließend 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 Ihrer Konfiguration die folgenden Einstellungen hinzufügen:

    Fügen Sie Ihrer google-ads.yaml- oder YAML-Konfiguration Folgendes 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 eine dict zum Konfigurieren der Bibliothek verwenden, fügen Sie die folgenden Schlüssel/Wert-Paare ein und rufen Sie die load_from_dict-Methode 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 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. 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:

Ein 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 für den Workflow zur Authentifizierung für mehrere Nutzer.

Manuelle Authentifizierung

Sie können Autorisierungsanmeldedaten mit einer beliebigen Methode generieren und sie der GoogleAdsClient manuell zur Verfügung stellen, 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 mehrere Google Ads-Konten verwaltet, entweder durch direkten Zugriff auf die 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 get_account_hierarchy-Codebeispiel wird gezeigt, wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
  2. Im list_accessible_customers-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.