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

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

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

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

Общие рекомендации по аутентификации в 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 в спецификации пода:

    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, в котором включен Data Manager API.

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

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

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

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

  • Workload Identity Federation (рекомендуется): Настройте Workload Identity Federation, чтобы ваше приложение могло обменивать учетные данные от внешнего поставщика идентификационной информации на краткосрочные учетные данные 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, чтобы неинтерактивно аутентифицироваться и управлять токенами доступа без подписи токенов вручную:

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

    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. Предоставьте сервисному аккаунту роль Потребитель сервисов (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 от имени нескольких рекламодателей, которые зарегистрировались в их сервисе.

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

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

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

  1. Запросите офлайн-доступ. Перенаправьте пользователей на окно запроса доступа OAuth от Google, запросив область действия 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

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

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

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

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

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

Рекомендации по производству

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