Wdróż w środowisku produkcyjnym

Ten przewodnik pomoże Ci wybrać i skonfigurować odpowiednie podejście do uwierzytelniania we wdrożeniu produkcyjnym interfejsu Data Manager API.

Wybieranie scenariusza wdrażania

Wybierz metodę uwierzytelniania, która pasuje do architektury aplikacji i środowiska wdrożenia:

• Zadania w Google Cloud: w przypadku zautomatyzowanych zadań (takich jak potoki ETL, zadania wsadowe lub usługi backendu) działających w Compute Engine, Cloud Run, Cloud Functions lub GKE używaj domyślnego uwierzytelniania aplikacji (ADC) z dołączonym kontem usługi lub Workload Identity Federation for GKE.
• Zadania poza Google Cloud: w przypadku zautomatyzowanych zadań uruchamianych lokalnie lub u innych dostawców chmury używaj domyślnego uwierzytelniania aplikacji (ADC) z federacją tożsamości zadań lub kluczem konta usługi.
• Działanie w imieniu użytkowników: w przypadku platform innych firm i aplikacji z wieloma najemcami, które zarządzają kontami użytkowników zewnętrznych (np. reklamodawców, którzy zarejestrowali się na Twojej platformie), używaj przepływu serwera WWW OAuth 2.0 z tokenami odświeżania dla poszczególnych użytkowników lub linków partnerów, jeśli jesteś zatwierdzonym dostawcą danych.

Ogólne wskazówki dotyczące uwierzytelniania w Google Cloud znajdziesz w drzewie decyzyjnym uwierzytelniania w Google Cloud.

Zadania w Google Cloud

Jeśli korzystasz z Google Cloud, podłącz konto usługi bezpośrednio do zasobu obliczeniowego lub skonfiguruj Workload Identity Federation for GKE. Biblioteki klienta używają ADC do automatycznego pobierania danych logowania o ograniczonym czasie ważności dla konta usługi bez konieczności używania plików danych logowania ani zmiennych środowiskowych.

Compute Engine

Podczas tworzenia instancji maszyny wirtualnej określ konto usługi i zakres interfejsu Data Manager API, aby tokeny dostępu zwracane przez serwer metadanych instancji zawierały wymagane uprawnienia.

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"

Aby zaktualizować zakresy lub konto usługi w istniejącej instancji, zatrzymaj ją, zaktualizuj konfigurację za pomocą set-service-account i uruchom ponownie instancję:

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

Podaj konto usługi podczas wdrażania usługi:

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

Cloud Functions

Podaj konto usługi podczas wdrażania funkcji:

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

GKE

1. Włącz Workload Identity Federation for GKE w klastrze.

2. Powiąż konto usługi Kubernetes (KSA) z kontem usługi Google (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. Dodaj do konta usługi Kubernetes adnotację z adresem e-mail konta usługi Google:

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

4. Określ konto usługi Kubernetes w specyfikacji poda:

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

Sprawdzanie uprawnień i dostępu do konta

Przed wdrożeniem aplikacji produkcyjnej sprawdź, czy konto usługi ma niezbędne uprawnienia:

1. Uprawnienia Google Cloud IAM: przypisz do konta usługi rolę konsument Wykorzystania usług (roles/serviceusage.serviceUsageConsumer) w projekcie Google Cloud, w którym włączony jest interfejs Data Manager API.

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

2. Dostęp do konta docelowego: przyznaj kontu usługi wymagany dostęp do kont docelowych. Szczegółowe instrukcje znajdziesz w artykule Konfigurowanie dostępu do konta.

Zadania poza Google Cloud

Jeśli uruchamiasz kod w lokalnych centrach danych lub u innych dostawców chmury, wybierz jeden z tych mechanizmów uwierzytelniania:

• Federacja tożsamości zadań (zalecana): skonfiguruj federację tożsamości zadań, aby umożliwić aplikacji wymianę danych logowania z zewnętrznego dostawcy tożsamości na krótkotrwałe dane logowania Google Cloud bez zarządzania kluczami kont usługi. Wygeneruj plik konfiguracji danych logowania i udostępnij go ADC za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS.

• Klucze konta usługi (opcja zapasowa): jeśli federacja tożsamości zadań jest niedostępna, utwórz klucz konta usługi i podaj go ADC za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS.

  Uwaga: klucze kont usługi to długotrwałe dane logowania, które stanowią zagrożenie dla bezpieczeństwa, jeśli zostaną ujawnione lub będą nieprawidłowo zarządzane. Postępuj zgodnie ze sprawdzonymi metodami zarządzania kluczami kont usługi, przechowuj klucze w bezpiecznym menedżerze obiektów tajnych, ogranicz uprawnienia do plików i regularnie rotuj klucze.

Zestaw GOOGLE_APPLICATION_CREDENTIALS

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę bezwzględną pliku konfiguracji danych logowania federacji tożsamości zadań lub pliku klucza konta usługi, aby biblioteki klienta mogły automatycznie lokalizować dane logowania za pomocą ADC.

Linux / macOS

Ustaw zmienną środowiskową w profilu powłoki lub skrypcie wdrażania:

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

Windows (PowerShell)

Ustaw zmienną środowiskową w PowerShell:

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

Docker / kontenery

Podłącz plik z danymi logowania do kontenera i ustaw zmienną środowiskową:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Możesz też przekazać zmienną środowiskową w czasie działania:

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

Podłącz dane logowania jako obiekt tajny i odwołaj się do niego w środowisku poda:

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

Uwierzytelnianie żądań REST i curl

Jeśli Twój zautomatyzowany potok wysyła nieprzetworzone żądania HTTP za pomocą curl, zamiast używać biblioteki klienta, użyj Google Cloud CLI do nieinteraktywnego uwierzytelniania i zarządzania tokenami dostępu bez ręcznego podpisywania tokenów:

1. Autoryzuj Google Cloud CLI za pomocą pliku danych logowania skonfigurowanego w środowisku:

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

2. Przekaż wygenerowany token dostępu w nagłówku Authorization żądań do interfejsu API:

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

   Google Cloud CLI automatycznie zapisuje token dostępu w pamięci podręcznej i odświeża go przed wygaśnięciem.

Sprawdzanie uprawnień i dostępu do konta

Przed wdrożeniem aplikacji produkcyjnej sprawdź, czy konto usługi ma niezbędne uprawnienia:

1. Uprawnienia Google Cloud IAM: przypisz do konta usługi rolę konsument Wykorzystania usług (roles/serviceusage.serviceUsageConsumer) w projekcie Google Cloud, w którym włączony jest interfejs Data Manager API.

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

2. Dostęp do konta docelowego: przyznaj kontu usługi wymagany dostęp do kont docelowych. Szczegółowe instrukcje znajdziesz w artykule Konfigurowanie dostępu do konta.

Działanie w imieniu użytkowników

Platformy innych firm, takie jak platformy marketingowe i agencje, często muszą wysyłać żądania do interfejsu API w imieniu wielu reklamodawców, którzy zarejestrowali się w ich usłudze.

W tej architekturze zamiast domyślnego uwierzytelniania aplikacji użyj przepływu serwera WWW OAuth 2.0, aby uzyskać dane logowania użytkownika z dostępem offline od każdego reklamodawcy, a następnie użyj tych danych do skonfigurowania biblioteki klienta w czasie działania na podstawie konta reklamodawcy, którym zarządza żądanie.

Implementowanie przepływu OAuth 2.0 w internecie

Aby skonfigurować przekazywanie dostępu użytkowników w przypadku aplikacji z wieloma najemcami:

1. Poproś o dostęp offline: przekieruj użytkowników na ekran zgody OAuth Google, na którym wyświetli się prośba o zakres https://www.googleapis.com/auth/datamanager z parametrami access_type=offline i prompt=consent. Serwer wymienia kod autoryzacji na token dostępu i refresh_token. Szczegółowe instrukcje znajdziesz w artykule o używaniu OAuth 2.0 w internetowych aplikacjach serwerowych.

2. Bezpieczne przechowywanie danych logowania: przechowuj token odświeżania każdego użytkownika w bezpieczny sposób w zaszyfrowanym magazynie danych logowania powiązanym z jego kontem na Twojej platformie.

3. Inicjowanie bibliotek klienta w czasie działania: gdy wysyłasz żądanie do interfejsu API w imieniu konkretnego użytkownika, utwórz dane logowania użytkownika na podstawie tokena odświeżania zapisanego dla użytkownika oraz identyfikatora klienta i tajnego klucza klienta aplikacji, a następnie przekaż je podczas inicjowania klienta:

   .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
   

Ukończ weryfikację aplikacji OAuth

Zakresy interfejsu Data Manager API są zakresami poufnymi, dlatego każda aplikacja chmurowa Google używana do uzyskiwania danych logowania użytkowników z zewnętrznych kont Google musi przejść weryfikację Google OAuth przed wprowadzeniem do środowiska produkcyjnego:

• Programowanie: gdy stan publikacji aplikacji jest ustawiony na Testowanie na stronie Odbiorcy w konsoli Google Cloud, tylko wyznaczone konta testowe mogą autoryzować aplikację.
• Wersja produkcyjna: zanim udostępnisz aplikację użytkownikom zewnętrznym, ustaw stan publikacji na W wersji produkcyjnej i prześlij aplikację do weryfikacji.

Ważne: jeśli nie ukończysz weryfikacji aplikacji OAuth przed udostępnieniem jej użytkownikom zewnętrznym, zobaczą oni ekran niezweryfikowanej aplikacji i możesz nie być w stanie uzyskać danych logowania dla nowych użytkowników. Szczegółowe informacje o etapach konfiguracji odbiorców i wymaganiach dotyczących filmu demonstracyjnego znajdziesz w artykule Weryfikacja aplikacji OAuth.

Weryfikacja aplikacji nie jest wymagana w przypadku zadań, które są uruchamiane przy użyciu kont usługi. Istnieją też pewne wyjątki, np. w przypadku aplikacji wewnętrznych. Szczegółowe informacje znajdziesz w sekcji Kiedy weryfikacja nie jest wymagana.

Alternatywa: linki partnerów

Jeśli Twoja organizacja jest zatwierdzonym dostawcą danych, możesz używać linków partnera zamiast zarządzać tokenami OAuth poszczególnych użytkowników na potrzeby bieżącego pozyskiwania danych.

Dzięki linkom partnerów reklamodawcy mogą łączyć swoje konta z Twoim kontem dostawcy danych w interfejsie Google Ads, Display & Video 360 lub Google Ad Managera. Po utworzeniu połączenia aplikacja wysyła żądania pozyskiwania danych, używając danych logowania do konta usługi przez ADC, co eliminuje konieczność przechowywania i utrzymywania długotrwałych tokenów odświeżania użytkownika.

Sprawdzone metody dotyczące produkcji

Przed przejściem do środowiska produkcyjnego zapoznaj się z tymi kluczowymi kwestiami operacyjnymi:

• Obsługa błędów i weryfikacja: dowiedz się, jak interfejs API weryfikuje żądania za pomocą modelu szybkiego niepowodzenia i zwraca uporządkowane szczegóły błędów.
• Strategia ponawiania prób: w przypadku przejściowych błędów serwera zastosuj wzrastający czas do ponowienia z fluktuacją.
• Grupowanie i równoczesność: zmaksymalizuj przepustowość, grupując rekordy i wysyłając żądania równocześnie w ramach limitów.
• Diagnostyka i monitorowanie: przechwytywanie identyfikatorów żądań odpowiedzi i wysyłanie zapytań do usługi diagnostycznej w celu weryfikacji przetwarzania asynchronicznego oraz wykrywania ostrzeżeń i błędów.