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 die Anmeldedaten des Nutzers verarbeiten oder speichern zu 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-Workflows

Bei der Arbeit mit der Google Ads API werden drei gängige Workflows verwendet.

Dienstkonto-Workflow

Dies ist der empfohlene Workflow, wenn für Ihren Workflow keine Interaktion mit einem Nutzer 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 wird 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 (zusammen mit der optionalen impersonated_email, wenn Sie die domainweite Übertragung 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 die Bibliothek mit einem dict konfigurieren, fügen Sie das folgende Schlüssel-Wert-Paar hinzu und rufen Sie die Methode load_from_dict auf. Übergeben Sie dabei das Konfigurations-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-Nutzeranmeldedatenschlüssel (client_id, client_secret und refresh_token) nicht festgelegt oder auskommentiert sind, autorisiert die Bibliothek automatisch mit dem Dienstkonto-Workflow.

Weitere Informationen finden Sie im Leitfaden zum Dienstkonto-Workflow.

Authentifizierungsvorgang für einen einzelnen 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 mit der 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 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 so initialisiert werden:

Wenn Sie das gcloud CLI-Tool verwenden (empfohlen)

  1. Folgen Sie der Dokumentation zum Generieren von Anmeldedaten, 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 einem dict konfigurieren, fügen Sie das folgende Schlüssel-Wert-Paar hinzu und rufen Sie die load_from_dict Methode 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, um ein Konsolenprojekt einzurichten und die JSON-Datei mit der Client-ID und dem Clientschlüssel Ihres Projekts herunterzuladen.

  2. Klonen Sie die Python-Clientbibliothek auf Ihren Computer und wechseln Sie in das zugehörige 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 es und speichern Sie es 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-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 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 einem dict konfigurieren, fügen Sie die folgenden Schlüssel-Wert-Paare hinzu 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 zum Authentifizierungsvorgang für einen einzelnen Nutzer.

Authentifizierungsvorgang für mehrere Nutzer

Dies ist der empfohlene Workflow, 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 so 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 verwendet werden kann, wenn Anmeldedaten zur Laufzeit abgerufen werden:

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 Authentifizierungsvorgang für mehrere Nutzer.

Manuelle Authentifizierung

Sie können Anmeldedaten mit einer beliebigen Methode generieren und sie dem GoogleAdsClient manuell zur Verfügung stellen, indem Sie die Clientklasse direkt instanziieren. Wenn das von Ihnen erstellte Anmeldedatenobjekt eine Instanz von google.auth.credentials.Credentials ist, 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

In der Regel verwaltet ein Nutzer mehrere Google Ads-Konten, entweder durch direkten Zugriff auf Konten oder über ein Google Ads-Verwaltungskonto. Die Python-Clientbibliothek enthält die folgenden Codebeispiele, die veranschaulichen, wie Sie solche Fälle behandeln:

  1. Das get_account_hierarchy Codebeispiel zeigt, wie Sie die Liste aller Konten unter einem Google Ads-Verwaltungskonto abrufen.
  2. Das list_accessible_customers Code beispiel 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.