Развертывание в производство

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

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

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

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

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

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

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

Вычислительный движок

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

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"

Облачные функции

При развертывании функции укажите учетную запись службы:

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

ГКЕ

1. Включите федерацию идентификации рабочих нагрузок для 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 в спецификации вашего пода:

   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 : Предоставьте учетной записи службы роль «Потребитель использования службы » ( roles/serviceusage.serviceUsageConsumer ) в проекте Google Cloud, где включен API Data Manager.

   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 на абсолютный путь к файлу конфигурации учетных данных федерации идентификации рабочей нагрузки или файлу ключа учетной записи службы, чтобы клиентские библиотеки могли автоматически находить ваши учетные данные с помощью 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 автоматически кэширует токен доступа и обновляет его перед истечением срока действия.

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

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

1. Разрешения Google Cloud IAM : Предоставьте учетной записи службы роль «Потребитель использования службы » ( roles/serviceusage.serviceUsageConsumer ) в проекте Google Cloud, где включен API Data Manager.

   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. Запрос на офлайн-доступ : перенаправьте пользователей на экран согласия Google OAuth, запрашивающий доступ к данным по адресу https://www.googleapis.com/auth/datamanager с access_type=offline и prompt=consent . Ваш сервер обменяет код авторизации на токен доступа и refresh_token . Пошаговые инструкции см. в разделе OAuth 2.0 для веб-серверных приложений .

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

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

   .СЕТЬ

   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)
   

   Руби

   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.

Поскольку https://www.googleapis.com/auth/datamanager содержит конфиденциальную информацию, любое приложение Google Cloud, используемое для получения учетных данных пользователей из внешних учетных записей Google, должно пройти проверку Google OAuth перед запуском в рабочую среду:

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

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

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

Альтернативный вариант: Партнерские ссылки

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

Благодаря партнерским ссылкам рекламодатели подключают свои аккаунты к вашему партнерскому аккаунту данных в интерфейсе Google Ads, Display & Video 360 или Google Ad Manager. После установления связи ваше приложение отправляет запросы на получение данных, используя учетные данные вашей собственной сервисной учетной записи через ADC, что избавляет от необходимости хранить и поддерживать долгосрочные токены обновления пользователей.

Передовые методы производства

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

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