Wdróż w środowisku produkcyjnym

Ten przewodnik pomoże Ci wybrać i skonfigurować odpowiednią metodę uwierzytelniania na potrzeby wdrożenia produkcyjnego interfejsu Data Manager API.

Wybieranie scenariusza wdrożenia

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 dotyczącym uwierzytelniania w Google Cloud.

Zadania w Google Cloud

Gdy uruchamiasz zadania w Google Cloud, dołącz konto usługi bezpośrednio do zasobu obliczeniowego lub skonfiguruj Workload Identity Federation for 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 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 instancję, zaktualizuj konfigurację za pomocą polecenia 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

Podczas wdrażania usługi określ konto 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 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 dostępu do uprawnień i konta

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

  1. Uprawnienia Google Cloud IAM: przyznaj kontu usługi rolę Użytkownik usługi (roles/serviceusage.serviceUsageConsumer) w projekcie Google Cloud, w którym jest włączony 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

Gdy 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 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 kont usługi (rezerwowe): jeśli federacja tożsamości zadań jest niedostępna, utwórz klucz konta usługi i udostępnij go ADC za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS.

Ustawianie zmiennej GOOGLE_APPLICATION_CREDENTIALS

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na bezwzględną ścieżkę do 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 wdrożenia:

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

Zamontuj plik danych logowania w kontenerze 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

Zamontuj 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 zautomatyzowany potok wysyła surowe żądania HTTP za pomocą polecenia 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ń 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 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 Google Cloud IAM: przyznaj kontu usługi rolę Użytkownik usługi (roles/serviceusage.serviceUsageConsumer) w projekcie Google Cloud, w którym jest włączony 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 używać 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 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

Oto jak skonfigurować delegowanie użytkowników w aplikacjach wielodostępnych:

  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. Twój serwer wymienia kod autoryzacji na token dostępu i refresh_token. Szczegółowe instrukcje znajdziesz w artykule OAuth 2.0 w aplikacjach udostępnianych przez serwer WWW.

  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

Zakończ weryfikację aplikacji OAuth

Zakresy interfejsu Data Manager API są zakresami poufnymi, dlatego każda aplikacja chmurowa Google Cloud używana do uzyskiwania danych logowania użytkownika z zewnętrznych kont Google musi przed przejściem do wersji produkcyjnej przejść weryfikację OAuth Google:

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

Weryfikacja aplikacji nie jest wymagana w przypadku zadań uruchamianych za pomocą kont usługi. Istnieją też pewne wyjątki w przypadku scenariuszy takich jak aplikacje wewnętrzne. Więcej informacji znajdziesz w artykule Kiedy weryfikacja nie jest potrzebna.

Jeśli Twoja organizacja jest zatwierdzonym dostawcą danych, możesz używać linków partnerskich zamiast zarządzać tokenami protokołu OAuth dla każdego użytkownika na potrzeby ciągłego pozyskiwania danych.

Dzięki linkom partnerskim reklamodawcy mogą łączyć swoje konta z kontem dostawcy danych w interfejsie Google Ads, Display &Video 360 lub Google Ad Manager. Po utworzeniu linku Twoja aplikacja wysyła żądania pozyskiwania danych za pomocą własnych danych logowania konta usługi przez ADC, co eliminuje konieczność przechowywania i utrzymywania długotrwałych tokenów odświeżania użytkownika.

Sprawdzone metody w wersji produkcyjnej

Przed przejściem do wersji produkcyjnej zapoznaj się z tymi najważniejszymi kwestiami operacyjnymi: