Für Produktion bereitstellen

In diesem Leitfaden erfahren Sie, wie Sie den richtigen Authentifizierungsansatz für die Produktionsbereitstellung Ihrer Data Manager API 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 in 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 Multi-Tenant-Anwendungen, die Konten für externe Nutzer verwalten (z. B. Werbetreibende, die sich auf Ihrer Plattform registrieren), 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 ausgeführt werden, hängen Sie ein Dienstkonto direkt an Ihre Compute-Ressource an oder konfigurieren Sie Workload Identity Federation for 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 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) 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 eintauschen 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 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. Befolgen Sie die 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 Anmeldedaten für die Workload Identity-Föderation oder der Dienstkontoschlüsseldatei 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)

Umgebungsvariable in PowerShell festlegen:

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

Docker / Container

Hängen Sie die Datei mit den Anmeldedaten in den Container ein 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 in Ihrer automatisierten Pipeline mit curl rohe HTTP-Anfragen gestellt werden, anstatt eine Clientbibliothek zu verwenden, können Sie die Google Cloud CLI verwenden, um sich nicht interaktiv zu authentifizieren und Zugriffstokens zu verwalten, ohne Tokens manuell zu signieren:

1. Autorisieren Sie die Google Cloud CLI mit der Anmeldedatendatei, die in Ihrer Umgebung konfiguriert ist:

   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-Webserverablauf, um Nutzeranmeldedaten mit Offlinezugriff von jedem Werbetreibenden abzurufen. Anschließend konfigurieren Sie die Clientbibliothek zur Laufzeit mit diesen Anmeldedaten, je nachdem, welches Werbetreibendenkonto mit der Anfrage verwaltet wird.

OAuth 2.0-Web-Flow implementieren

So richten Sie die Nutzerdelegierung für Mehrmandantenanwendungen 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 ein. Eine detaillierte Anleitung finden Sie unter OAuth 2.0 für Webserveranwendungen verwenden.

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 und der Client-ID und dem Client-Secret für Ihre App 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 https://www.googleapis.com/auth/datamanager ein sensibler Bereich ist, muss jede Google Cloud-App, die zum Abrufen von Nutzeranmeldedaten von externen Google-Konten verwendet wird, vor der Produktionsumgebung 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 bestimmte Testkonten Ihre Anwendung autorisieren.
• Produktion: Bevor Sie Ihre Anwendung für externe Nutzer verfügbar machen, legen Sie den Veröffentlichungsstatus auf In Produktion fest und reichen Sie die App zur Überprüfung ein.

Wichtig: Wenn Sie die Überprüfung der OAuth-App nicht abschließen, bevor Sie die App für externe Nutzer freigeben, wird Nutzern ein Bildschirm für nicht überprüfte 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. Außerdem 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 zugelassener Datenpartner ist, können Sie Partnerlinks verwenden, anstatt OAuth-Tokens für die laufende Datenaufnahme pro Nutzer zu verwalten.

Über Partnerverknüpfungen können Werbetreibende ihre Konten in der Google Ads-, Display & Video 360- oder Google Ad Manager-Benutzeroberfläche mit Ihrem Datenpartnerkonto verknüpfen. Nachdem die Verknüpfung hergestellt wurde, sendet Ihre Anwendung Erfassungsanfragen mit den Anmeldedaten Ihres eigenen Dienstkontos über ADC. So müssen keine langlebigen Nutzer-Aktualisierungstokens gespeichert und verwaltet werden.

Best Practices für die Produktion

Beachten Sie beim Umstieg auf die Produktion die folgenden wichtigen betrieblichen Aspekte:

• Fehlerbehandlung und Validierung: Hier erfahren Sie, wie die API Anfragen mit dem Fast-Fail-Modell 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 in Batches zusammenfassen und Anfragen gleichzeitig innerhalb der Grenzwerte senden.
• Diagnose und Monitoring: Erfassen Sie IDs für Antwortanfragen und fragen Sie den Diagnosedienst ab, um die asynchrone Verarbeitung zu prüfen und Warnungen und Fehler zu erkennen.