Für Produktion bereitstellen

In diesem Leitfaden erfahren Sie, wie Sie die geeignete Authentifizierungsmethode 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: Verwenden Sie für automatisierte Arbeitslasten (z. B. ETL-Pipelines, Batchjobs oder Backend-Dienste), die auf Compute Engine, Cloud Run, Cloud Functions oder GKE ausgeführt werden, Standardanmeldedaten für Anwendungen (ADC) mit einem angehängten Dienstkonto oder Workload Identity Federation for GKE.
• Arbeitslasten außerhalb von Google Cloud: Verwenden Sie für automatisierte Arbeitslasten, die lokal oder bei anderen Cloud-Anbietern ausgeführt werden, Standardanmeldedaten für Anwendungen mit der Workload Identity-Föderation oder einem Dienstkontoschlüssel.
• Im Namen von Nutzern handeln: Verwenden Sie für Drittanbieterplattformen und mandantenfähige Anwendungen, die Konten für externe Nutzer verwalten (z. B. Werbetreibende, die sich auf Ihrer Plattform registrieren), den OAuth 2.0-Webserver-Ablauf mit nutzerspezifischen Aktualisierungstokens oder Partnerlinks, wenn Sie ein genehmigter Datenpartner sind.

Allgemeine Informationen zur Google Cloud-Authentifizierung finden Sie im Entscheidungsbaum für die 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 die Workload Identity-Föderation für GKE. Clientbibliotheken verwenden ADC, um kurzlebige Anmeldedaten für das Dienstkonto automatisch 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 Instanzmetadatenserver 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 einer vorhandenen 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 (KSA) an das Google-Dienstkonto (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 Ihrer 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) in dem 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-Föderation (empfohlen): Konfigurieren Sie die Workload Identity-Föderation, 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 mithilfe der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS zur Verfügung.

• Dienstkontoschlüssel (Fallback): Wenn die Workload Identity-Föderation 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 offengelegt 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, schränken Sie Dateiberechtigungen ein und rotieren Sie Schlüssel regelmäßig.

GOOGLE_APPLICATION_CREDENTIALS festlegen

Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den absoluten Pfad der Konfigurationsdatei für die Anmeldedaten der Workload Identity-Föderation oder der Schlüsseldatei des Dienstkontos fest, damit Clientbibliotheken Ihre Anmeldedaten automatisch mithilfe von 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

Hängen Sie die Datei mit den Anmeldedaten im Container an 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 Roh-HTTP-Anfragen mit curl stellt, anstatt eine Clientbibliothek zu verwenden, verwenden Sie die Google Cloud CLI, um sich nicht interaktiv zu authentifizieren und Zugriffstokens zu verwalten, ohne Tokens manuell zu signieren:

1. Autorisieren Sie die Google Cloud CLI mit der in Ihrer Umgebung konfigurierten Datei mit den Anmeldedaten:

   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 dem 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) in dem 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.

In dieser Architektur verwenden Sie anstelle von Standardanmeldedaten für Anwendungen den OAuth 2.0-Webserver-Ablauf, um Nutzeranmeldedaten mit Offlinezugriff von jedem Werbetreibenden abzurufen. Anschließend verwenden Sie diese Anmeldedaten, um die Clientbibliothek zur Laufzeit basierend auf dem Werbetreibendenkonto zu konfigurieren, das die Anfrage verwaltet.

OAuth 2.0-Webvorgang implementieren

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

1. Offlinezugriff anfordern: Leiten Sie Nutzer zum OAuth-Zustimmungsbildschirm von Google weiter, auf dem der Bereich https://www.googleapis.com/auth/datamanager mit access_type=offline und prompt=consent angefordert wird. 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 Aktualisierungstoken, das Sie für den Nutzer gespeichert haben, sowie der Client-ID und dem Clientschlüssel für Ihre App. Übergeben Sie diese dann bei der Initialisierung 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 sensible Bereiche sind, muss jede Google Cloud-App, die zum Abrufen von Nutzeranmeldedaten von externen Google-Konten verwendet wird, vor der Bereitstellung in der Produktion die Google OAuth-Überprüfung durchlaufen:

• Entwicklung: Wenn der Veröffentlichungsstatus der App in der Google Cloud Console auf der Seite „Zielgruppe“ auf Test festgelegt ist, können nur festgelegte Testkonten Ihre Anwendung autorisieren.
• Produktion: Bevor Sie Ihre Anwendung für externe Nutzer verfügbar machen, setzen Sie den Veröffentlichungsstatus auf In Produktion und reichen Sie die Anwendung zur Überprüfung ein.

Wichtig: Wenn Sie die OAuth-App-Überprüfung nicht abschließen, bevor Sie die App für externe Nutzer veröffentlichen, wird Nutzern ein Bildschirm für nicht bestätigte Apps 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 das Demonstrationsvideo finden Sie unter OAuth-App-Überprüfung.

Für Arbeitslasten, die mit Dienstkonten ausgeführt werden, ist keine App-Überprüfung erforderlich. Darüber hinaus gibt es einige Ausnahmen für Szenarien wie interne Anwendungen. Weitere Informationen finden Sie unter Wann ist keine Bestätigung erforderlich?.

Alternative: Partner links

Wenn Ihre Organisation ein genehmigter Datenpartner ist, können Sie Partnerlinks verwenden, anstatt für die laufende Datenaufnahme OAuth-Tokens pro Nutzer zu verwalten.

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

Best Practices für die Produktion

Beachten Sie beim Übergang zur Produktion die folgenden wichtigen betrieblichen Aspekte:

• Fehlerbehandlung und Validierung: Hier erfahren Sie, wie die API Anfragen mithilfe des Fast-Fail-Modells validiert und strukturierte Fehlerdetails zurückgibt.
• Wiederholungsstrategie: Implementieren Sie einen exponentiellen Backoff mit Jitter für vorübergehende Serverfehler.
• Batching und Nebenläufigkeit: Maximieren Sie den Durchsatz, indem Sie Datensätze im Batch verarbeiten und Anfragen gleichzeitig innerhalb der Limits senden.
• Diagnose und Monitoring: Erfassen Sie Antwortanfrage-IDs und fragen Sie den Diagnosedienst ab, um die asynchrone Verarbeitung zu prüfen und Warnungen und Fehler zu erkennen.