Wdróż w środowisku produkcyjnym

Ten przewodnik pomoże Ci wybrać i skonfigurować odpowiednie podejście do uwierzytelniania w przypadku wdrożenia produkcyjnego interfejsu Data Manager API.

Wybierz scenariusz wdrożenia

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

• Zbiory zadań w Google Cloud: w przypadku zautomatyzowanych zbiorów 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.
• Zbiory zadań poza Google Cloud: w przypadku zautomatyzowanych zbiorów zadań działających lokalnie lub u innych dostawców usług w chmurze 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 wielodostępnych, które zarządzają kontami użytkowników zewnętrznych (np. reklamodawców rejestrujących się na Twojej platformie), używaj procesu serwera internetowego OAuth 2.0 z tokenami odświeżania dla poszczególnych użytkowników lub linków partnerskich, jeśli jesteś zatwierdzonym dostawcą danych.

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

Zadania w Google Cloud

Jeśli korzystasz z Google Cloud, dołącz konto usługi bezpośrednio do zasobu obliczeniowego lub skonfiguruj federację tożsamości zadań w GKE. Biblioteki klienta używają ADC do automatycznego pobierania krótkotrwałych danych logowania do konta usługi bez konieczności używania plików z danymi 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 przypadku istniejącej instancji, zatrzymaj instancję, zaktualizuj konfigurację za pomocą set-service-account i ponownie uruchom 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

Podczas wdrażania funkcji określ konto usługi:

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

GKE

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

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 dostępu do uprawnień i konta

Zanim wdrożysz aplikację produkcyjną, sprawdź, czy Twoje konto usługi ma niezbędne uprawnienia:

1. Uprawnienia IAM Google Cloud: przypisz do konta usługi rolę Użytkownik usługi (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 kod jest uruchamiany w lokalnych centrach danych lub u innych dostawców usług w chmurze, 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 od 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 (wersja zapasowa): jeśli federacja tożsamości zadań jest niedostępna, utwórz klucz konta usługi i przekaż go do ADC za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS.

  Ostrzeżenie: klucze kont usługi to długotrwałe dane logowania, które w przypadku ujawnienia lub nieprawidłowego zarządzania nimi stanowią zagrożenie dla bezpieczeństwa. 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 zmieniaj 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 PowerShellu:

$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 surowe żądania HTTP za pomocą curl zamiast korzystać z biblioteki klienta, użyj Google Cloud CLI, aby uwierzytelniać się w sposób nieinteraktywny i zarządzać tokenami dostępu bez ręcznego podpisywania tokenów:

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

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

2. Przekaż wygenerowany token dostępu w nagłówku Authorization żądań 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
   

   Interfejs Google Cloud CLI automatycznie buforuje token dostępu i odświeża go przed wygaśnięciem.

Sprawdzanie dostępu do uprawnień i konta

Zanim wdrożysz aplikację produkcyjną, sprawdź, czy Twoje konto usługi ma niezbędne uprawnienia:

1. Uprawnienia IAM Google Cloud: przypisz do konta usługi rolę Użytkownik usługi (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 zewnętrzne, takie jak platformy marketingowe i agencje, często muszą wysyłać żądania interfejsu API w imieniu wielu reklamodawców, którzy zarejestrują się w ich usłudze.

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

Wdrażanie przepływu internetowego OAuth 2.0

Aby skonfigurować przekazywanie uprawnień użytkownika w aplikacjach z wieloma klientami:

1. Poproś o dostęp offline: przekieruj użytkowników na ekran zgody OAuth Google, prosząc 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 OAuth 2.0 w internetowych aplikacjach serwerowych.

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

3. Inicjowanie bibliotek klienta w czasie działania: podczas wysyłania żądania do interfejsu API w imieniu konkretnego użytkownika utwórz dane logowania użytkownika na podstawie przechowywanego tokena odświeżania użytkownika oraz identyfikatora klienta i tajnego klucza klienta aplikacji i 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
   

Weryfikowanie aplikacji OAuth

Ponieważ zakres https://www.googleapis.com/auth/datamanager jest zakresem wrażliwym, każda aplikacja Google Cloud używana do uzyskiwania danych logowania użytkowników z zewnętrznych kont Google musi przed wdrożeniem w środowisku produkcyjnym przejść weryfikację OAuth w Google:

• Tworzenie: gdy stan publikacji aplikacji jest ustawiony na Testowanie na stronie Odbiorcy w Google Cloud Console, tylko wyznaczone konta testowe mogą autoryzować Twoją 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 przeprowadzisz weryfikacji aplikacji OAuth przed udostępnieniem jej użytkownikom zewnętrznym, będą oni widzieć ekran z informacją o nieweryfikowanej aplikacji i może się okazać, że nie możesz uzyskać danych logowania nowych użytkowników. Szczegółowe informacje o etapach konfigurowania odbiorców i wymaganiach dotyczących filmów demonstracyjnych znajdziesz w artykule Weryfikacja aplikacji OAuth.

Weryfikacja aplikacji nie jest wymagana w przypadku obciążeń uruchamianych przy użyciu kont usługi. Istnieją też wyjątki w przypadku aplikacji wewnętrznych. Więcej informacji znajdziesz w sekcji Kiedy weryfikacja nie jest potrzebna.

Alternatywa: linki partnerskie

Jeśli Twoja organizacja jest zatwierdzonym dostawcą danych, możesz używać linków partnera zamiast zarządzać tokenami protokołu OAuth poszczególnych użytkowników w celu ciągłego pozyskiwania danych.

Za pomocą połączeń z partnerem reklamodawcy łączą swoje konta z kontem dostawcy danych w interfejsie Google Ads, Display & Video 360 lub Google Ad Managera. Po utworzeniu połączenia aplikacja wysyła żądania pozyskiwania danych za pomocą własnego konta usługi przez ADC, dzięki czemu nie trzeba przechowywać i aktualizować długoterminowych tokenów odświeżania użytkownika.

Sprawdzone metody produkcji

Podczas przechodzenia do wersji produkcyjnej 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 wykrywania błędów i zwraca szczegółowe informacje o błędach w ustrukturyzowanej formie.
• Strategia ponawiania: w przypadku przejściowych błędów serwera wdróż wzrastający czas do ponowienia z losowym opóźnieniem.
• Przetwarzanie wsadowe i równoczesność: maksymalizuj przepustowość, przetwarzając rekordy wsadowo i wysyłając żądania równocześnie w ramach limitów.
• Diagnostyka i monitorowanie: rejestrowanie identyfikatorów żądań odpowiedzi i wysyłanie zapytań do usługi diagnostycznej w celu weryfikowania przetwarzania asynchronicznego oraz wykrywania ostrzeżeń i błędów.