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:

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.

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.

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.

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: