Für Produktion bereitstellen

In diesem Leitfaden erfahren Sie, wie Sie den geeigneten Authentifizierungsansatz für Ihre Data Manager API-Produktionsbereitstellung auswählen und konfigurieren.

Bereitstellungsszenario auswählen

Wählen Sie den Authentifizierungsansatz aus, der zu Ihrer Anwendungsarchitektur und Bereitstellungsumgebung passt:

• Arbeitslasten in Google Cloud: Für automatisierte Arbeitslasten (z. B. ETL-Pipelines, Batchjobs oder Backend-Dienste), die in Compute Engine, Cloud Run, Cloud Functions oder GKE ausgeführt werden, verwenden Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) mit einem angehängten Dienstkonto oder Workload Identity Federation for GKE.
• Arbeitslasten außerhalb von Google Cloud: Für automatisierte Arbeitslasten, die lokal oder bei anderen Cloud-Anbietern ausgeführt werden, verwenden Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) mit Workload Identity Federation oder einem Dienstkontoschlüssel.
• Im Namen von Nutzern handeln: Für Drittanbieterplattformen und mehrmandantenfähige Anwendungen, die Konten für externe Nutzer verwalten (z. B. Werbetreibende, die sich auf Ihrer Plattform registrieren), verwenden Sie den OAuth 2.0-Webserverablauf mit Aktualisierungstokens pro Nutzer oder Partnerlinks, wenn Sie ein zugelassener Datenpartner sind.

Allgemeine Informationen zur Google Cloud-Authentifizierung finden Sie im Entscheidungsbaum zur Google Cloud-Authentifizierung.

Arbeitslasten in Google Cloud

Wenn Sie in Google Cloud arbeiten, hängen Sie ein Dienstkonto direkt an Ihre Compute-Ressource an oder konfigurieren Sie Workload Identity Federation for GKE. Clientbibliotheken verwenden ADC, um automatisch kurzlebige Anmeldedaten für das Dienstkonto abzurufen, ohne dass Anmeldedatendateien oder Umgebungsvariablen erforderlich sind.

Compute Engine

Geben Sie beim Erstellen einer VM-Instanz das Dienstkonto und den Data Manager API-Bereich an, damit die vom Instanz-Metadatenserver zurückgegebenen Zugriffstokens die erforderliche Autorisierung enthalten.

gcloud compute instances create INSTANCE_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform"

Wenn Sie die Bereiche oder das Dienstkonto für eine vorhandene Instanz aktualisieren möchten, beenden Sie die Instanz, aktualisieren Sie die Konfiguration mit set-service-account und starten Sie die Instanz neu:

gcloud compute instances stop INSTANCE_NAME

gcloud compute instances set-service-account \
  INSTANCE_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform"

gcloud compute instances start INSTANCE_NAME

Cloud Run

Geben Sie das Dienstkonto beim Bereitstellen des Dienstes an:

gcloud run deploy SERVICE_NAME \
  --image="IMAGE_URL" \
  --service-account="SERVICE_ACCOUNT_EMAIL"

Cloud Functions

Geben Sie das Dienstkonto beim Bereitstellen der Funktion an:

gcloud functions deploy FUNCTION_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --runtime="RUNTIME" \
  --trigger-http

GKE

1. Aktivieren Sie Workload Identity Federation for GKE in Ihrem Cluster.

2. Binden Sie Ihr Kubernetes-Dienstkonto (Kubernetes Service Account, KSA) an das Google-Dienstkonto (Google Service Account, GSA):

   # Define the Kubernetes service account member:
   KUBERNETES_MEMBER="serviceAccount:PROJECT_ID.svc.id.goog[KUBERNETES_NAMESPACE/KUBERNETES_SA_NAME]"
   
   # Grant the Workload Identity User role to the Kubernetes service account:
   gcloud iam service-accounts add-iam-policy-binding \
     SERVICE_ACCOUNT_EMAIL \
     --role="roles/iam.workloadIdentityUser" \
     --member="${KUBERNETES_MEMBER}"
   

3. Annotieren Sie das Kubernetes-Dienstkonto mit der E-Mail-Adresse des Google-Dienstkontos:

   kubectl annotate serviceaccount KUBERNETES_SA_NAME \
     --namespace="KUBERNETES_NAMESPACE" \
     iam.gke.io/gcp-service-account="SERVICE_ACCOUNT_EMAIL"
   

4. Geben Sie das Kubernetes-Dienstkonto in der Pod-Spezifikation an:

   apiVersion: v1
   kind: Pod
   metadata:
     name: data-manager-worker
   spec:
     serviceAccountName: KUBERNETES_SA_NAME
     containers:
     - name: worker
       image: IMAGE_URL
   

IAM- und Kontozugriff überprüfen

Prüfen Sie vor der Bereitstellung Ihrer Produktionsanwendung, ob Ihr Dienstkonto die erforderlichen Berechtigungen hat:

1. Google Cloud-IAM-Berechtigungen: Weisen Sie dem Dienstkonto die Rolle „Service Usage Consumer“ (roles/serviceusage.serviceUsageConsumer) im Google Cloud-Projekt zu, in dem die Data Manager API aktiviert ist.

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
     --role="roles/serviceusage.serviceUsageConsumer"
   

2. Zugriff auf Zielkonto: Gewähren Sie dem Dienstkonto den erforderlichen Zugriff auf Ihre Zielkonten. Eine detaillierte Anleitung finden Sie unter Kontozugriff einrichten.

Arbeitslasten außerhalb von Google Cloud

Wenn Sie Code in lokalen Rechenzentren oder bei anderen Cloud-Anbietern ausführen, wählen Sie einen der folgenden Authentifizierungsmechanismen aus:

• Workload Identity Federation (empfohlen): Konfigurieren Sie Workload Identity Federation, damit Ihre Anwendung Anmeldedaten von Ihrem externen Identitätsanbieter gegen kurzlebige Google Cloud-Anmeldedaten austauschen kann, ohne Dienstkontoschlüssel verwalten zu müssen. Generieren Sie eine Konfigurationsdatei für Anmeldedaten und stellen Sie sie ADC über die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS zur Verfügung.

• Dienstkontoschlüssel (Fallback): Wenn Workload Identity Federation nicht verfügbar ist, erstellen Sie einen Dienstkontoschlüssel und stellen Sie ihn ADC über die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS zur Verfügung.

  Achtung: Dienstkontoschlüssel sind langlebige Anmeldedaten, die ein Sicherheitsrisiko darstellen, wenn sie weitergegeben oder falsch verwaltet werden. Folgen Sie den Best Practices für die Verwaltung von Dienstkontoschlüsseln, speichern Sie Schlüssel in einem sicheren Secret Manager, beschränken Sie die Dateiberechtigungen und rotieren Sie Schlüssel regelmäßig.

GOOGLE_APPLICATION_CREDENTIALS festlegen

Legen Sie für die GOOGLE_APPLICATION_CREDENTIALS Umgebungsvariable den absoluten Pfad der Konfigurationsdatei für Anmeldedaten für Workload Identity Federation oder der Dienstkontoschlüsseldatei fest, damit Clientbibliotheken Ihre Anmeldedaten automatisch mit ADC finden können.

Linux / macOS

Legen Sie die Umgebungsvariable in Ihrem Shell-Profil oder Bereitstellungsskript fest:

export GOOGLE_APPLICATION_CREDENTIALS=\
  "/path/to/credentials.json"

Windows (PowerShell)

Legen Sie die Umgebungsvariable in PowerShell fest:

$env:GOOGLE_APPLICATION_CREDENTIALS = `
  "C:\path\to\credentials.json"

Docker / Container

Stellen Sie die Anmeldedatendatei im Container bereit und legen Sie die Umgebungsvariable fest:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Oder übergeben Sie die Umgebungsvariable zur Laufzeit:

HOST_CREDS="/host/path/credentials.json"
docker run -e GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json" \
  -v "${HOST_CREDS}:/secrets/credentials.json:ro" \
  IMAGE_NAME

Kubernetes

Stellen Sie die Anmeldedaten als Secret bereit und verweisen Sie in der Umgebung des Pods darauf:

apiVersion: v1
kind: Pod
metadata:
  name: data-manager-worker
spec:
  containers:
  - name: worker
    image: IMAGE_URL
    env:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: "/etc/secrets/google/credentials.json"
    volumeMounts:
    - name: credentials-volume
      mountPath: "/etc/secrets/google"
      readOnly: true
  volumes:
  - name: credentials-volume
    secret:
      secretName: data-manager-credentials

REST- und curl-Anfragen authentifizieren

Wenn Ihre automatisierte Pipeline mit curl Roh-HTTP-Anfragen stellt, anstatt eine Clientbibliothek zu verwenden, authentifizieren Sie sich nicht interaktiv mit der Google Cloud CLI und verwalten Sie Zugriffstokens, ohne Tokens manuell zu signieren:

1. Autorisieren Sie die Google Cloud CLI mit der in Ihrer Umgebung konfigurierten Anmeldedatendatei:

   gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"
   

2. Übergeben Sie das generierte Zugriffstoken im Authorization-Header Ihrer API-Anfragen:

   curl -X POST "https://datamanager.googleapis.com/v1/..." \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json
   

   Die Google Cloud CLI speichert das Zugriffstoken automatisch im Cache und aktualisiert es vor Ablauf.

IAM- und Kontozugriff überprüfen

Prüfen Sie vor der Bereitstellung Ihrer Produktionsanwendung, ob Ihr Dienstkonto die erforderlichen Berechtigungen hat:

1. Google Cloud-IAM-Berechtigungen: Weisen Sie dem Dienstkonto die Rolle „Service Usage Consumer“ (roles/serviceusage.serviceUsageConsumer) im Google Cloud-Projekt zu, in dem die Data Manager API aktiviert ist.

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
     --role="roles/serviceusage.serviceUsageConsumer"
   

2. Zugriff auf Zielkonto: Gewähren Sie dem Dienstkonto den erforderlichen Zugriff auf Ihre Zielkonten. Eine detaillierte Anleitung finden Sie unter Kontozugriff einrichten.

Im Namen von Nutzern handeln

Drittanbieterplattformen wie Marketingplattformen und ‑agenturen müssen häufig API-Anfragen im Namen mehrerer Werbetreibender senden, die sich für ihren Dienst registrieren.

Verwenden Sie in dieser Architektur anstelle von Standardanmeldedaten für Anwendungen den OAuth 2.0-Webserverablauf, um Nutzeranmeldedaten mit Offlinezugriff von jedem Werbetreibenden abzurufen. Konfigurieren Sie dann die Clientbibliothek zur Laufzeit basierend darauf, welches Werbetreibendenkonto mit der Anfrage verwaltet wird.

OAuth 2.0-Webablauf implementieren

So richten Sie die Nutzerdelegierung für mehrmandantenfähige Anwendungen ein:

1. Offlinezugriff anfordern: Leiten Sie Nutzer zum OAuth-Zustimmungsbildschirm von Google weiter und fordern Sie den Bereich https://www.googleapis.com/auth/datamanager mit access_type=offline und prompt=consent an. Ihr Server tauscht den Autorisierungscode gegen ein Zugriffstoken und ein refresh_token aus. Eine detaillierte Anleitung finden Sie unter OAuth 2.0 für Webserveranwendungen.

2. Anmeldedaten sicher speichern: Speichern Sie das Aktualisierungstoken jedes Nutzers sicher in einem verschlüsselten Anmeldedatenspeicher, der mit seinem Konto auf Ihrer Plattform verknüpft ist.

3. Clientbibliotheken zur Laufzeit initialisieren: Wenn Sie eine API-Anfrage im Namen eines bestimmten Nutzers senden, erstellen Sie Nutzeranmeldedaten aus dem für den Nutzer gespeicherten Aktualisierungstoken sowie der Client-ID und dem Clientschlüssel für Ihre Anwendung und übergeben Sie sie beim Initialisieren des Clients:

   .NET

   using Google.Ads.DataManager.V1;
   using Google.Apis.Auth.OAuth2;
   
   UserCredential credential = CredentialFactory.FromJsonParameters<UserCredential>(
       new JsonCredentialParameters
       {
           Type = JsonCredentialParameters.AuthorizedUserCredentialType,
           ClientId = clientId,
           ClientSecret = clientSecret,
           RefreshToken = refreshToken
       });
   
   IngestionServiceClient client = new IngestionServiceClientBuilder
   {
       Credential = credential
   }.Build();
   

   Go

   import (
       "context"
   
       datamanager "cloud.google.com/go/datamanager/apiv1"
       "golang.org/x/oauth2"
       "golang.org/x/oauth2/google"
       "google.golang.org/api/option"
   )
   
   cfg := &oauth2.Config{
       ClientID:     clientID,
       ClientSecret: clientSecret,
       Endpoint:     google.Endpoint,
   }
   ts := cfg.TokenSource(ctx, &oauth2.Token{RefreshToken: refreshToken})
   
   client, err := datamanager.NewIngestionClient(ctx, option.WithTokenSource(ts))
   

   Java

   import com.google.ads.datamanager.v1.IngestionServiceClient;
   import com.google.ads.datamanager.v1.IngestionServiceSettings;
   import com.google.api.gax.core.FixedCredentialsProvider;
   import com.google.auth.oauth2.UserCredentials;
   
   UserCredentials credentials =
       UserCredentials.newBuilder()
           .setClientId(clientId)
           .setClientSecret(clientSecret)
           .setRefreshToken(refreshToken)
           .build();
   
   IngestionServiceSettings settings =
       IngestionServiceSettings.newBuilder()
           .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
           .build();
   
   try (IngestionServiceClient client = IngestionServiceClient.create(settings)) {
     // Send API requests using client...
   }
   

   Node.js

   const {IngestionServiceClient} = require('@google-ads/datamanager').v1;
   const {UserRefreshClient} = require('google-auth-library');
   
   const authClient = new UserRefreshClient({
     clientId,
     clientSecret,
     refreshToken,
   });
   
   const client = new IngestionServiceClient({authClient});
   

   PHP

   use Google\Ads\DataManager\V1\Client\IngestionServiceClient;
   use Google\Auth\Credentials\UserRefreshCredentials;
   
   $credentials = new UserRefreshCredentials(
       null,
       [
           'client_id' => $clientId,
           'client_secret' => $clientSecret,
           'refresh_token' => $refreshToken,
       ]
   );
   
   $client = new IngestionServiceClient(['credentials' => $credentials]);
   

   Python

   from google.ads.datamanager_v1 import IngestionServiceClient
   from google.oauth2.credentials import Credentials
   
   credentials = Credentials.from_authorized_user_info({
       "client_id": client_id,
       "client_secret": client_secret,
       "refresh_token": refresh_token,
   })
   
   client = IngestionServiceClient(credentials=credentials)
   

   Ruby

   require "google/ads/data_manager/v1"
   require "googleauth"
   
   credentials = Google::Auth::UserRefreshCredentials.new(
     client_id: client_id,
     client_secret: client_secret,
     refresh_token: refresh_token
   )
   
   client = Google::Ads::DataManager::V1::IngestionService::Client.new do |config|
     config.credentials = credentials
   end
   

OAuth-App-Überprüfung abschließen

Da Data Manager API-Bereiche vertrauliche Zugriffsbereiche sind, muss jede Google Cloud-App, die zum Abrufen von Nutzeranmeldedaten von externen Google-Konten verwendet wird, vor der Produktionsbereitstellung die Google OAuth-Überprüfung durchlaufen:

• Entwicklung: Wenn der Veröffentlichungsstatus der Anwendung auf der Seite „Zielgruppe“ in der Google Cloud Console auf Test gesetzt ist, können nur bestimmte Testkonten Ihre Anwendung autorisieren.
• Produktion: Bevor Sie Ihre Anwendung externen Nutzern zur Verfügung stellen, legen Sie den Veröffentlichungsstatus auf In Produktion fest und reichen Sie die Anwendung zur Überprüfung ein.

Wichtig: Wenn Sie die OAuth-App-Überprüfung nicht abschließen, bevor Sie die Anwendung für externe Nutzer bereitstellen, wird Nutzern ein Bildschirm mit einer nicht überprüften Anwendung angezeigt und Sie können möglicherweise keine Anmeldedaten für neue Nutzer abrufen. Weitere Informationen zu den Phasen der Zielgruppenkonfiguration und den Anforderungen an Demovideos finden Sie unter OAuth-App-Überprüfung.

Die App-Überprüfung ist für Arbeitslasten, die mit Dienstkonten ausgeführt werden, nicht erforderlich. Außerdem gibt es einige Ausnahmen für Szenarien wie interne Anwendungen. Weitere Informationen finden Sie unter Wann ist eine Überprüfung nicht erforderlich?

Alternative: Partner links

Wenn Ihre Organisation ein zugelassener Datenpartner ist, können Sie anstelle der Verwaltung von OAuth-Tokens pro Nutzer Partnerlinks für die fortlaufende Datenaufnahme verwenden.

Mit Partnerlinks verknüpfen Werbetreibende ihre Konten mit Ihrem Datenpartnerkonto in der Google Ads-, Display &Video 360- oder Google Ad Manager-UI. Nachdem die Verknüpfung hergestellt wurde, sendet Ihre Anwendung Erfassungsanfragen mit den Anmeldedaten Ihres eigenen Dienstkontos über ADC. So müssen Sie keine langlebigen Aktualisierungstokens für Nutzer speichern und verwalten.

Best Practices für die Produktion

Beachten Sie beim Übergang zur Produktion diese wichtigen betrieblichen Überlegungen:

• Fehlerbehandlung und ‑validierung: Informationen dazu, wie die API Anfragen mit dem Fast-Fail-Modell validiert und strukturierte Fehlerdetails zurückgibt.
• Wiederholungsstrategie: Implementieren Sie exponentiellen Backoff mit Jitter für vorübergehende Serverfehler.
• Batching und Nebenläufigkeit: Maximieren Sie den Durchsatz, indem Sie Datensätze in Batches zusammenfassen und Anfragen innerhalb der Limits gleichzeitig senden.
• Diagnose und Monitoring: Erfassen Sie Anfragen-IDs für Antworten und fragen Sie den Diagnosedienst ab, um die asynchrone Verarbeitung zu überprüfen und Warnungen und Fehler zu erkennen.