Развертывание в рабочей среде

Это руководство поможет вам выбрать и настроить подходящий способ аутентификации для рабочего развертывания Data Manager API.

Выберите сценарий развертывания

Выберите подход к аутентификации, который соответствует архитектуре вашего приложения и среде развертывания:

• Рабочие нагрузки в Google Cloud. Для автоматизированных рабочих нагрузок (таких как конвейеры ETL, пакетные задания или бэкенд-службы), выполняемых в Compute Engine, Cloud Run, Cloud Functions или GKE, используйте стандартные учетные данные приложения (ADC) с прикрепленным сервисным аккаунтом или федерацию идентификационных данных рабочей нагрузки для GKE.
• Рабочие нагрузки за пределами Google Cloud. Для автоматизированных рабочих нагрузок, выполняемых локально или у других поставщиков облачных сервисов, используйте Application Default Credentials (ADC) с Workload Identity Federation или ключом сервисного аккаунта.
• Действия от имени пользователей. Для сторонних платформ и многопользовательских приложений, которые управляют аккаунтами внешних пользователей (например, рекламодателей, зарегистрированных на вашей платформе), используйте поток веб-сервера OAuth 2.0 с токенами обновления для каждого пользователя или связи с партнерами, если вы являетесь одобренным партнером по обработке данных.

Общие рекомендации по аутентификации в Google Cloud приведены в дереве решений по аутентификации в Google Cloud.

Рабочие нагрузки в Google Cloud

При работе в Google Cloud прикрепите сервисный аккаунт непосредственно к вычислительному ресурсу или настройте Workload Identity Federation для GKE. Клиентские библиотеки используют ADC, чтобы автоматически получать временные учетные данные для сервисного аккаунта без файлов учетных данных или переменных среды.

Compute Engine

При создании экземпляра виртуальной машины укажите сервисный аккаунт и область действия Data Manager API, чтобы токены доступа, возвращаемые сервером метаданных экземпляра, включали необходимые разрешения.

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"

Чтобы обновить области действия или сервисный аккаунт в существующем экземпляре, остановите его, обновите конфигурацию с помощью set-service-account и перезапустите экземпляр:

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

Укажите сервисный аккаунт при развертывании сервиса:

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

Cloud Functions

Укажите сервисный аккаунт при развертывании функции:

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

GKE

1. Включите Workload Identity Federation для GKE в кластере.

2. Привяжите сервисный аккаунт Kubernetes (KSA) к сервисному аккаунту 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. Добавьте аннотацию к сервисному аккаунту Kubernetes с адресом электронной почты сервисного аккаунта Google:

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

4. Укажите сервисный аккаунт Kubernetes в спецификации pod:

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

Проверьте доступ к аккаунту и IAM

Прежде чем развертывать рабочее приложение, убедитесь, что у сервисного аккаунта есть необходимые разрешения:

1. Разрешения Google Cloud IAM. Предоставьте сервисному аккаунту роль Пользователь Service Usage (roles/serviceusage.serviceUsageConsumer) в проекте Google Cloud, в котором включен Data Manager API.

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

2. Доступ к целевому аккаунту. Предоставьте сервисному аккаунту необходимый доступ к целевым аккаунтам. Подробные инструкции приведены в статье Как настроить доступ к аккаунту.

Рабочие нагрузки за пределами Google Cloud

При запуске кода в локальных центрах обработки данных или у других поставщиков облачных сервисов выберите один из следующих механизмов аутентификации:

• Федерация идентификационных данных рабочих нагрузок (рекомендуется). Настройте федерацию идентификационных данных рабочих нагрузок, чтобы ваше приложение могло обменивать учетные данные внешнего поставщика идентификационной информации на краткосрочные учетные данные Google Cloud без управления ключами сервисных аккаунтов. Создайте файл конфигурации учетных данных и передайте его в ADC с помощью переменной среды GOOGLE_APPLICATION_CREDENTIALS.

• Ключи сервисных аккаунтов (резервный вариант). Если федерация идентификации рабочей нагрузки недоступна, создайте ключ сервисного аккаунта и предоставьте его ADC с помощью переменной среды GOOGLE_APPLICATION_CREDENTIALS.

  Внимание! Ключи сервисных аккаунтов – это долгосрочные учетные данные, которые представляют угрозу безопасности в случае утечки или неправильного управления. Следуйте рекомендациям по управлению ключами сервисных аккаунтов, храните ключи в безопасном менеджере секретов, ограничивайте разрешения файлов и регулярно меняйте ключи.

Установить GOOGLE_APPLICATION_CREDENTIALS

Установите для переменной среды GOOGLE_APPLICATION_CREDENTIALS абсолютный путь к файлу конфигурации учетных данных Workload Identity или файлу ключа сервисного аккаунта, чтобы клиентские библиотеки могли автоматически находить ваши учетные данные с помощью ADC.

Linux и macOS

Задайте переменную среды в профиле оболочки или скрипте развертывания:

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

Windows (PowerShell)

Задайте переменную среды в PowerShell:

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

Docker / контейнеры

Смонтируйте файл учетных данных в контейнер и задайте переменную среды:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

или передайте переменную среды во время выполнения:

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

Смонтируйте учетные данные как секрет и укажите его в среде пода:

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 и curl

Если ваш автоматизированный конвейер отправляет необработанные HTTP-запросы с помощью curl, а не клиентской библиотеки, используйте Google Cloud CLI для неинтерактивной аутентификации и управления токенами доступа без их подписания вручную.

1. Авторизуйте Google Cloud CLI с помощью файла учетных данных, настроенного в вашей среде:

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

2. Передайте сгенерированный токен доступа в заголовке Authorization запросов к 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 автоматически кеширует токен доступа и обновляет его до истечения срока действия.

Проверьте доступ к аккаунту и IAM

Прежде чем развертывать рабочее приложение, убедитесь, что у вашего сервисного аккаунта есть необходимые разрешения:

1. Разрешения Google Cloud IAM. Предоставьте сервисному аккаунту роль Пользователь Service Usage (roles/serviceusage.serviceUsageConsumer) в проекте Google Cloud, в котором включен Data Manager API.

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

2. Доступ к целевому аккаунту. Предоставьте сервисному аккаунту необходимый доступ к целевым аккаунтам. Подробные инструкции приведены в статье Как настроить доступ к аккаунту.

Действия от имени пользователей

Сторонним платформам, например маркетинговым платформам и агентствам, часто требуется отправлять запросы к API от имени нескольких рекламодателей, которые зарегистрировались в их сервисе.

В этой архитектуре вместо учетных данных по умолчанию для приложения используйте процесс веб-сервера OAuth 2.0, чтобы получить учетные данные пользователя с офлайн-доступом от каждого рекламодателя, а затем используйте эти учетные данные для настройки клиентской библиотеки во время выполнения на основе того, каким аккаунтом рекламодателя управляет запрос.

Как реализовать веб-процесс OAuth 2.0

Чтобы настроить делегирование пользователей для мультиарендных приложений, выполните следующие действия:

1. Запросите офлайн-доступ. Направьте пользователей на окно запроса доступа OAuth, где запрашивается область действия https://www.googleapis.com/auth/datamanager с параметрами access_type=offline и prompt=consent. Сервер обменивает код авторизации на токен доступа и refresh_token. Пошаговые инструкции приведены в статье Использование OAuth 2.0 для веб-серверных приложений.

2. Безопасное хранение учетных данных. Храните токен обновления каждого пользователя в зашифрованном хранилище учетных данных, связанном с его аккаунтом на вашей платформе.

3. Инициализируйте клиентские библиотеки во время выполнения. При отправке запроса к API от имени определенного пользователя создайте учетные данные пользователя на основе токена обновления, который вы сохранили для пользователя, а также идентификатора клиента и секретного кода клиента для вашего приложения. Передайте эти данные при инициализации клиента:

   .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();
   

   Проложить маршрут

   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

Поскольку области действия Data Manager API являются конфиденциальными, любое облачное приложение Google Cloud, используемое для получения учетных данных пользователя из внешних аккаунтов Google, должно пройти проверку OAuth в Google перед запуском в рабочую версию:

• Разработка. Пока для приложения на странице Аудитория в консоли Google Cloud выбран статус публикации Тестирование, авторизовать его могут только назначенные тестовые аккаунты.
• Рабочая версия. Прежде чем сделать приложение доступным для внешних пользователей, установите статус публикации Рабочая версия и отправьте приложение на проверку.

Важно! Если вы не завершите проверку приложения OAuth до его запуска для внешних пользователей, они увидят экран непроверенного приложения и вы не сможете получить учетные данные для новых пользователей. Подробную информацию об этапах настройки аудитории и требованиях к демонстрационному видео можно найти в статье Проверка приложения OAuth.

Для рабочих нагрузок, выполняемых с помощью сервисных аккаунтов, проверка приложений не требуется. Кроме того, есть исключения для некоторых сценариев, например для внутренних приложений. Подробнее о том, когда подтверждение не требуется…

Альтернатива: ссылки партнеров

Если ваша организация является одобренным партнером по обработке данных, вы можете использовать партнерские ссылки вместо управления токенами OAuth для каждого пользователя, чтобы обеспечить непрерывное добавление данных.

С помощью партнерских связей рекламодатели могут подключать свои аккаунты к вашему аккаунту партнера по обработке данных в интерфейсе Google Рекламы, Дисплея и Видео 360 или Google Менеджера рекламы. После установления связи ваше приложение отправляет запросы на загрузку, используя учетные данные собственного сервисного аккаунта через ADC. Это позволяет избежать необходимости хранить и поддерживать долгоживущие токены обновления пользователей.

Рекомендации по созданию видео

При переходе к рабочей среде учитывайте следующие ключевые операционные аспекты:

• Обработка ошибок и проверка. Узнайте, как API проверяет запросы с помощью модели быстрого сбоя и возвращает структурированные сведения об ошибках.
• Стратегия повторных попыток. Реализуйте экспоненциальную выдержку с джиттером для временных ошибок сервера.
• Пакетная обработка и параллелизм. Увеличьте производительность, объединив записи в пакеты и отправив запросы одновременно в пределах ограничений.
• Диагностика и мониторинг. Получайте идентификаторы запросов ответов и запрашивайте сервис диагностики, чтобы проверять асинхронную обработку и обнаруживать предупреждения и ошибки.