Üretime dağıtma

Bu kılavuz, Data Manager API üretim dağıtımınız için uygun kimlik doğrulama yaklaşımını seçmenize ve yapılandırmanıza yardımcı olur.

Dağıtım senaryonuzu seçme

Uygulama mimarinize ve dağıtım ortamınıza uygun kimlik doğrulama yaklaşımını seçin:

Google Cloud kimlik doğrulamasıyla ilgili genel bilgiler için Google Cloud kimlik doğrulama karar ağacına bakın.

Google Cloud'daki iş yükleri

Google Cloud'da çalışırken doğrudan işlem kaynağınıza bir hizmet hesabı ekleyin veya GKE için Workload Identity Federasyonu'nu yapılandırın. İstemci kitaplıkları, kimlik bilgisi dosyaları veya ortam değişkenleri gerektirmeden hizmet hesabının kısa süreli kimlik bilgilerini otomatik olarak almak için ADC'yi kullanır.

Compute Engine

Sanal makine örneği oluştururken hizmet hesabını ve Data Manager API kapsamını belirtin. Böylece, örnek meta veri sunucusu tarafından döndürülen erişim jetonları gerekli yetkilendirmeyi içerir.

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"

Mevcut bir örnekteki kapsamları veya hizmet hesabını güncellemek için örneği durdurun, yapılandırmayı set-service-account ile güncelleyin ve örneği yeniden başlatın:

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

Hizmeti dağıtırken hizmet hesabını belirtin:

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

Cloud Functions

İşlevi dağıtırken hizmet hesabını belirtin:

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

GKE

  1. Kümenizde GKE için Workload Identity Federasyonu'nu etkinleştirin.

  2. Kubernetes hizmet hesabınızı (KSA) Google hizmet hesabına (GSA) bağlayın:

    # 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 hizmet hesabına Google hizmet hesabı e-posta adresiyle ek açıklama ekleyin:

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

  4. Pod spesifikasyonunuzda Kubernetes hizmet hesabını belirtin:

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

IAM ve hesap erişimini doğrulama

Üretim uygulamanızı dağıtmadan önce hizmet hesabınızın gerekli izinlere sahip olduğunu doğrulayın:

  1. Google Cloud IAM izinleri: Hizmet hesabına, Data Manager API'sinin etkinleştirildiği Google Cloud projesinde Hizmet Kullanımı Tüketicisi rolünü (roles/serviceusage.serviceUsageConsumer) verin.

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

  2. Hedef hesap erişimi: Hizmet hesabına hedef hesaplarınız için gerekli erişimi verin. Adım adım talimatlar için Hesap erişimini ayarlama başlıklı makaleyi inceleyin.

Google Cloud dışındaki iş yükleri

Şirket içi veri merkezlerinde veya diğer bulut sağlayıcılarda kod çalıştırırken aşağıdaki kimlik doğrulama mekanizmalarından birini seçin:

  • Workload Identity Federasyonu (Önerilen): Uygulamanızın, harici kimlik sağlayıcınızdaki kimlik bilgilerini kısa süreli Google Cloud kimlik bilgileriyle değiştirmesine olanak tanımak için Workload Identity Federasyonu'nu yapılandırın. Bu işlem için hizmet hesabı anahtarlarını yönetmeniz gerekmez. Bir kimlik bilgisi yapılandırma dosyası oluşturun ve bunu GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kullanarak ADC'ye sağlayın.

  • Hizmet hesabı anahtarları (Yedek): Workload Identity Federation kullanılamıyorsa bir hizmet hesabı anahtarı oluşturun ve GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kullanarak ADC'ye sağlayın.

GOOGLE_APPLICATION_CREDENTIALS ayarla

İstemci kitaplıklarının ADC'yi kullanarak kimlik bilgilerinizi otomatik olarak bulabilmesi için GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini Workload Identity Federasyonu kimlik bilgisi yapılandırma dosyasının veya hizmet hesabı anahtar dosyasının mutlak yoluna ayarlayın.

Linux / macOS

Kabuk profilinizde veya dağıtım komut dosyanızda ortam değişkenini ayarlayın:

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

Windows (PowerShell)

PowerShell'de ortam değişkenini ayarlayın:

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

Docker / Kapsayıcılar

Kimlik bilgileri dosyasını kapsayıcıya bağlayın ve ortam değişkenini ayarlayın:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Alternatif olarak, ortam değişkenini çalışma zamanında iletebilirsiniz:

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

Kimlik bilgilerini Secret olarak bağlayın ve pod'un ortamında referans verin:

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 ve curl isteklerinin kimliğini doğrulama

Otomatik ardışık düzeniniz, istemci kitaplığı kullanmak yerine curl ile ham HTTP istekleri yapıyorsa Google Cloud KSA'yı kullanarak etkileşimli olmayan bir şekilde kimlik doğrulayın ve erişim jetonlarını manuel olarak imzalamadan yönetin:

  1. Ortamınızda yapılandırılan kimlik bilgisi dosyasını kullanarak Google Cloud CLI'yı yetkilendirin:

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

  2. Oluşturulan erişim jetonunu API isteklerinizin Authorization başlığında iletin:

    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, erişim jetonunu otomatik olarak önbelleğe alır ve süresi dolmadan önce yeniler.

IAM ve hesap erişimini doğrulama

Üretim uygulamanızı dağıtmadan önce hizmet hesabınızın gerekli izinlere sahip olduğunu doğrulayın:

  1. Google Cloud IAM izinleri: Hizmet hesabına, Data Manager API'sinin etkinleştirildiği Google Cloud projesinde Hizmet Kullanımı Tüketicisi rolünü (roles/serviceusage.serviceUsageConsumer) verin.

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

  2. Hedef hesap erişimi: Hizmet hesabına hedef hesaplarınız için gerekli erişimi verin. Adım adım talimatlar için Hesap erişimini ayarlama başlıklı makaleyi inceleyin.

Kullanıcılar adına işlem yapma

Pazarlama platformları ve ajanslar gibi üçüncü taraf platformların, hizmetlerine kaydolan birden fazla reklamveren adına API istekleri göndermesi gerekir.

Bu mimaride, Uygulama Varsayılan Kimlik Bilgileri'ni kullanmak yerine her reklamverenden çevrimdışı erişimle kullanıcı kimlik bilgilerini almak için OAuth 2.0 Web Sunucusu akışını kullanın. Ardından, isteğin hangi reklamveren hesabını yönettiğine bağlı olarak çalışma zamanında istemci kitaplığını yapılandırmak için bu kimlik bilgilerini kullanın.

OAuth 2.0 web akışını uygulama

Çok kiracılı uygulamalar için kullanıcı yetkilendirmesini şu şekilde ayarlayabilirsiniz:

  1. Çevrimdışı erişim isteğinde bulunma: Kullanıcıları, access_type=offline ve prompt=consent ile https://www.googleapis.com/auth/datamanager kapsamını isteyen Google'ın OAuth kullanıcı rızası ekranına yönlendirin. Sunucunuz, yetkilendirme kodunu bir erişim jetonu ve refresh_token ile değiştirir. Adım adım talimatlar için Web Sunucusu Uygulamaları için OAuth 2.0 başlıklı makaleyi inceleyin.

  2. Kimlik bilgilerini güvenli bir şekilde saklayın: Her kullanıcının yenileme jetonunu, platformunuzdaki hesabıyla ilişkili şifrelenmiş bir kimlik bilgisi deposunda güvenli bir şekilde saklayın.

  3. İstemci kitaplıklarını çalışma zamanında ilk kullanıma hazırlama: Belirli bir kullanıcı adına API isteği gönderirken kullanıcı için depoladığınız yenileme jetonundan ve uygulamanızın istemci kimliği ile istemci gizli anahtarından kullanıcı kimlik bilgilerini oluşturun ve istemciyi ilk kullanıma hazırlarken bunları iletin:

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

    Git

    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 uygulama doğrulamasını tamamlama

Data Manager API kapsamları hassas kapsamlar olduğundan, harici Google Hesaplarından kullanıcı kimlik bilgilerini almak için kullanılan tüm Google Cloud uygulamalarının üretime geçmeden önce Google OAuth doğrulamasından geçmesi gerekir:

  • Geliştirme: Google Cloud Console'daki Kitle sayfasında uygulamanın yayınlanma durumu Test olarak ayarlandığında uygulamanız yalnızca belirlenen test hesapları tarafından yetkilendirilebilir.
  • Üretim: Uygulamanızı harici kullanıcıların erişimine açmadan önce yayınlama durumunu Üretimde olarak ayarlayın ve uygulamayı doğrulama için gönderin.

Hizmet hesapları kullanılarak çalıştırılan iş yükleri için uygulama doğrulaması gerekmez. Ayrıca, dahili uygulamalar gibi senaryolar için bazı istisnalar vardır. Ayrıntılar için Doğrulama ne zaman gerekli değildir? başlıklı makaleyi inceleyin.

Kuruluşunuz onaylı bir veri iş ortağıysa devam eden veri kullanımı için kullanıcı başına OAuth jetonlarını yönetmek yerine iş ortağı bağlantılarını kullanabilirsiniz.

İş ortağı bağlantıları sayesinde reklamverenler, hesaplarını Google Ads, Display & Video 360 veya Google Ad Manager kullanıcı arayüzündeki veri iş ortağı hesabınıza bağlar. Bağlantı kurulduktan sonra uygulamanız, ADC aracılığıyla kendi hizmet hesabı kimlik bilgilerinizi kullanarak besleme istekleri gönderir. Böylece, uzun ömürlü kullanıcı yenileme jetonlarını depolama ve saklama ihtiyacı ortadan kalkar.

Prodüksiyonla ilgili en iyi uygulamalar

Üretime geçerken aşağıdaki önemli operasyonel hususları gözden geçirin: