Workflow für die Einzelnutzerauthentifizierung

Hinweis :In dieser Anleitung wird davon ausgegangen, dass Sie mit dem Google Ads-Zugriffsmodell vertraut sind. Falls nicht, empfehlen wir Ihnen, sich mit den Konzepten vertraut zu machen, indem Sie den Leitfaden zum Google Ads-Zugriffsmodell lesen.

Achtung :Google empfiehlt, den Dienstkonto-Workflow anstelle des Authentifizierungs-Workflows für einzelne Nutzer zu verwenden. Der Workflow zur Einzelnutzerauthentifizierung sollte nur verwendet werden, wenn Dienstkonten nicht verwendet werden können.

Ähnlich wie beim Dienstkonto-Workflow werden beim Authentifizierungsablauf für einzelne Nutzer die Autorisierungs- und Nutzerverwaltungsfunktionen der Google Ads-Benutzeroberfläche verwendet, um der App Zugriff auf alle erforderlichen Konten zu gewähren. Dieser Authentifizierungsablauf besteht aus zwei Schritten:

• Sie gewähren einem einzelnen Nutzer Zugriff auf alle Google Ads-Konten, die von der App verwaltet werden sollen.
• Der Nutzer autorisiert Ihre App, seine Google Ads-Konten in seinem Namen zu verwalten, und gewährt der App damit Zugriff auf alle Google Ads-Konten.

Da nur ein Nutzer beteiligt ist, können Sie Tools wie die gcloud CLI oder das Codebeispiel für GenerateUserCredential verwenden, anstatt einen eigenen OAuth 2.0-Nutzerauthentifizierungsvorgang zu erstellen.

Ein ähnlicher Anwendungsfall für diesen Workflow ist, wenn auf Ihre Konten über eine Handvoll Nutzeranmeldungen (z. B. 3–4 Nutzer) zugegriffen werden kann. In diesem Fall ist der Entwicklungsaufwand für die Erstellung eines umfassenden OAuth-Nutzerauthentifizierungs-Workflows im Vergleich zum Aufwand für die Autorisierung von 3–4 Nutzern mit einem Befehlszeilentool wie der gcloud-Befehlszeile nicht gerechtfertigt.

Nachteile

Dieser Ablauf hat im Vergleich zum Dienstkonto-Workflow einige Nachteile:

1. Für den Nutzerauthentifizierungs-Workflow müssen Sie eine OAuth 2.0-Client-ID und einen Clientschlüssel in der Google Cloud Console erstellen. Dies erfordert mehr Konfigurationsschritte als das Erstellen eines Dienstkontos und eines Schlüssels.
2. Ihre App muss möglicherweise einen zusätzlichen Google Cloud-App-Prüfungsprozess durchlaufen.
3. Wenn der autorisierte Nutzer das Team oder Unternehmen verlässt, funktioniert Ihre App möglicherweise nicht mehr, wenn Sie den Nutzer aus Ihren Konten entfernen oder das Nutzerkonto deaktivieren. Dienstkonten sind nicht an einzelne Nutzer gebunden, sodass dieses Risiko vermieden wird.
4. Der Nutzer, der das Google Ads-Konto autorisiert, sollte zusätzliche Vorsichtsmaßnahmen treffen, z. B. die 2-Faktor-Authentifizierung aktivieren, um zu verhindern, dass sein Google-Konto aufgrund von mangelnder Sicherheit, Malware oder Phishing kompromittiert wird. Dienstkonten sind weniger anfällig für dieses Problem, da einige dieser Angriffsmethoden nicht direkt auf sie angewendet werden können.

Anmeldedaten generieren

Hinweis: In dieser Anleitung wird beim Erstellen der OAuth-Anmeldedaten der OAuth-App-Typ Desktop-App verwendet, da dieser am besten mit der gcloud CLI funktioniert. Bei Verwendung des Authentifizierungsablaufs für einzelne Nutzer kann dieser OAuth-App-Typ unabhängig von der Art der Anwendung verwendet werden, die Sie entwickeln. Wenn Sie stattdessen Web-App auswählen, müssen Sie das OAuth-Playground verwenden, um ein Aktualisierungstoken zu generieren. Video mit einer Anleitung

1. Folgen Sie der Anleitung, um einen OAuth-Zustimmungsbildschirm für Ihre Anwendung zu konfigurieren und https://www.googleapis.com/auth/adwords als OAuth 2.0-Bereich hinzuzufügen.

2. Folgen Sie der Anleitung, um eine Client-ID und einen Clientschlüssel zu erstellen. Nachdem Sie den OAuth 2.0-Client erstellt haben, laden Sie die JSON-Datei des Clients herunter. Klicken Sie dazu zuerst auf das Symbol „OAuth-Client herunterladen“ und dann auf dem folgenden Bildschirm auf die Schaltfläche „JSON HERUNTERLADEN“. Speichern Sie die Datei als credentials.json.

3. Suchen Sie ein Nutzerkonto, das Zugriff auf alle Google Ads-Konten hat, die Sie mit Ihrer App verwalten möchten. Wenn es Konten mit fehlendem Zugriff gibt, folgen Sie der Anleitung, um den erforderlichen Zugriff zu gewähren.

4. Laden Sie die gcloud CLI herunter und installieren Sie sie. Prüfen Sie nach der Installation, ob das Tool richtig funktioniert, indem Sie den Befehl gcloud version über die Befehlszeile ausführen. Die Ausgabe könnte so aussehen:

   :~$ gcloud version
   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   gsutil 5.30

5. Generieren Sie ein OAuth 2.0-Aktualisierungstoken, indem Sie das gcloud-CLI-Tool ausführen:

   gcloud auth application-default 
   
     login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform 
   
     --client-id-file=<path_to_credentials.json>

   Die Datei credentials.json stammt aus dem vorherigen Schritt.

6. Mit dem Befehl gcloud wird in einem neuen Browserfenster ein Google-Konto-Anmeldefenster geöffnet, in dem Sie die OAuth 2.0-Authentifizierungsschritte durchlaufen. Melden Sie sich mit dem Nutzer an, den Sie in den vorherigen Schritten ausgewählt haben. Wenn Ihre App nicht verifiziert ist, wird möglicherweise ein Warnbildschirm angezeigt. In solchen Fällen können Sie bedenkenlos auf den Link Erweitert und dann auf die Option Zu PROJECT_NAME (nicht überprüft) klicken.

   

7. Nachdem Sie die Bereiche bestätigt haben, klicken Sie auf die Schaltfläche Weiter, um die Berechtigung zu erteilen. Der Browser ruft https://cloud.google.com/sdk/auth_success auf. Das bedeutet, dass die Authentifizierung erfolgreich war. Auf der Seite wird die folgende Meldung angezeigt:

   Authorization code granted. Close this tab.

   Der Befehl gcloud gibt die folgende Meldung aus:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]

   Öffnen Sie nun die Datei application_default_credentials.json. Der Inhalt sollte in etwa so aussehen:

   {
   "account": "",
   "client_id": "******.apps.googleusercontent.com",
   "client_secret": "******",
   "refresh_token": "******",
   "type": "authorized_user",
   "universe_domain": "googleapis.com"
   }
   

Clientbibliothek konfigurieren

Wählen Sie den Tab für Ihre Programmiersprache aus, um eine Anleitung zum Konfigurieren der Clientbibliothek zu erhalten.

Java

Konfigurieren Sie die folgenden Schlüssel in der Datei ads.properties.

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Weitere Optionen finden Sie im Konfigurationsleitfaden.

.NET

Sie können Ihre GoogleAdsClient-Instanz zur Laufzeit initialisieren. Verwenden Sie dazu die Anmeldedaten, die Sie vom Nutzer erhalten haben, dessen Konten Sie API-Aufrufe senden.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN",
    ...
};
GoogleAdsClient client = new GoogleAdsClient(config);

Weitere Optionen finden Sie im Konfigurationsleitfaden.

Python

Konfigurieren Sie die folgenden Schlüssel in der Datei google-ads.yaml.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Weitere Optionen finden Sie im Konfigurationsleitfaden.

PHP

Konfigurieren Sie die folgenden Schlüssel in Ihrer google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Weitere Optionen finden Sie im Konfigurationsleitfaden.

Ruby

Konfigurieren Sie die folgenden Schlüssel in der Datei google_ads_config.rb.

  Google::Ads::GoogleAds::Config.new do |c|
     c.client_id = 'INSERT_CLIENT_ID_HERE'
     c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
     c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
     c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
     c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  end

Weitere Optionen finden Sie im Konfigurationsleitfaden.

Perl

Konfigurieren Sie die folgenden Schlüssel in der Datei googleads.properties.

 clientId=INSERT_OAUTH2_CLIENT_ID_HERE
 clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
 refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
 loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
 

Weitere Optionen finden Sie im Konfigurationsleitfaden.

curl

Rufen Sie zuerst mit einem HTTP-Client ein OAuth 2.0-Zugriffstoken ab. In dieser Anleitung wird der Befehl curl verwendet.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Sie können das Zugriffstoken jetzt in Ihren API-Aufrufen verwenden. Im folgenden Beispiel wird gezeigt, wie Sie einen Kampagnenbericht mit der Methode GoogleAdsService.SearchStream ausführen, um die Kampagnen in Ihrem Konto abzurufen. Details zum Erstellen von Berichten werden in diesem Leitfaden nicht behandelt.

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

Der Inhalt von query.json sieht so aus:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}