Ü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çin

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

• Google Cloud'daki iş yükleri: Compute Engine, Cloud Run, Cloud Functions veya GKE'de çalışan otomatik iş yükleri (ör. ETL işlem hatları, toplu işler veya arka uç hizmetleri) için eklenmiş bir hizmet hesabıyla Uygulama Varsayılan Kimlik Bilgileri (ADC)'ni ya da GKE için Workload Identity Federasyonu'nu kullanın.
• Google Cloud dışındaki iş yükleri: Şirket içi veya diğer bulut sağlayıcılarında çalışan otomatik iş yükleri için Workload Identity Federation ile Uygulama Varsayılan Kimlik Bilgileri (ADC)'ı ya da bir hizmet hesabı anahtarı kullanın.
• Kullanıcılar adına işlem yapma: Harici kullanıcıların hesaplarını yöneten üçüncü taraf platformları ve çok kiracılı uygulamalar (ör. platformunuza kaydolan reklamverenler) için kullanıcı başına yenileme jetonlarıyla OAuth 2.0 web sunucusu akışını veya onaylı bir veri iş ortağıysanız iş ortağı bağlantılarını kullanın.

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ı, hizmet hesabı için kısa ömürlü kimlik bilgilerini kimlik bilgisi dosyaları veya ortam değişkenleri gerektirmeden otomatik olarak almak üzere 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ını Google hizmet hesabı e-postasıyla açıklama:

   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'nin etkinleştirildiği Google Cloud projesinde Service Usage Consumer (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ıza erişim için gerekli izinleri 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 Federation (Önerilir): Uygulamanızın, hizmet hesabı anahtarlarını yönetmeden kısa süreli Google Cloud kimlik bilgileri için harici kimlik sağlayıcınızdan kimlik bilgilerini değiştirmesine izin vermek üzere Workload Identity Federation'ı yapılandırın. Bir kimlik bilgisi yapılandırma dosyası oluşturun ve GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini kullanarak bu dosyayı ADC'ye sağlayın.

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

  Dikkat: Hizmet hesabı anahtarları, sızdırılırsa veya yanlış yönetilirse güvenlik riski oluşturan uzun ömürlü kimlik bilgileridir. Hizmet hesabı anahtarlarını yönetmeyle ilgili en iyi uygulamaları uygulayın, anahtarları güvenli bir gizli yöneticiye kaydedin, dosya izinlerini kısıtlayın ve anahtarları düzenli olarak döndürün.

GOOGLE_APPLICATION_CREDENTIALS ayarla

İstemci kitaplıklarının ADC 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

Ortam değişkenini kabuk profilinizde veya dağıtım komut dosyanızda 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 bunlara 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 gönderiyorsa Google Cloud KSA'yı kullanarak jetonları manuel olarak imzalamadan etkileşimli olmayan bir şekilde kimlik doğrulayın ve erişim jetonlarını yönetin:

1. Ortamınızda yapılandırılan kimlik bilgileri 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 üstbilgisinde 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'nin etkinleştirildiği Google Cloud projesinde Service Usage Consumer (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ıza erişim için gerekli izinleri 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, hizmetlerine kaydolan birden fazla reklamveren adına genellikle API istekleri göndermeleri gerekir.

Bu mimaride, uygulama varsayılan kimlik bilgilerini 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 istemci kitaplığını çalışma zamanında 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ı yetkisi ayarlama adımları:

1. Çevrimdışı erişim isteğinde bulunma: Kullanıcıları, https://www.googleapis.com/auth/datamanager kapsamını access_type=offline ve prompt=consent ile 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ı makaleye bakın.

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. Çalışma zamanında istemci kitaplıklarını başlatma: Belirli bir kullanıcı adına API isteği gönderirken, kullanıcı için sakladığınız yenileme jetonundan ve uygulamanızın istemci kimliği ile istemci sırrından kullanıcı kimlik bilgileri oluşturun ve istemciyi başlatırken 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

https://www.googleapis.com/auth/datamanager hassas bir kapsam olduğundan, harici Google Hesaplarından kullanıcı kimlik bilgilerini almak için kullanılan tüm Google Cloud uygulamaları, üretime geçmeden önce Google OAuth doğrulaması işleminden geçmelidir:

• Geliştirme: Uygulamanın yayınlanma durumu Google Cloud Console'daki Kitle sayfasında Test olarak ayarlanmışken uygulamanızı yalnızca belirlenmiş test hesapları yetkilendirebilir.
• Üretim: Uygulamanızı harici kullanıcıların kullanımına sunmadan önce yayınlama durumunu Üretimde olarak ayarlayın ve uygulamayı doğrulamaya gönderin.

Önemli: Harici kullanıcılara sunmadan önce OAuth uygulaması doğrulamasını tamamlamazsanız kullanıcılar doğrulanmamış uygulama ekranıyla karşılaşır ve yeni kullanıcılar için kimlik bilgisi alamayabilirsiniz. Kitle yapılandırma aşamaları ve tanıtım videosu şartları hakkında ayrıntılı bilgi için OAuth uygulaması doğrulama başlıklı makaleyi inceleyin.

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.

Alternatif: İş ortağı bağlantıları

Kuruluşunuz onaylı bir veri iş ortağıysa devam eden veri alı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ünde veri iş ortağı hesabınıza bağlar. Bağlantı kurulduktan sonra uygulamanız, ADC üzerinden kendi hizmet hesabı kimlik bilgilerini kullanarak alım istekleri gönderir. Böylece uzun süreli kullanıcı yenileme jetonlarını depolama ve sürdürme ihtiyacı ortadan kalkar.

Üretimle ilgili en iyi uygulamalar

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

• Hata işleme ve doğrulama: API'nin, hızlı hata modeli kullanarak istekleri nasıl doğruladığını ve yapılandırılmış hata ayrıntılarını nasıl döndürdüğünü anlayın.
• Yeniden deneme stratejisi: Geçici sunucu hataları için eksponansiyel geri yüklemeyi jitter ile uygulayın.
• Toplu işleme ve eşzamanlılık: Kayıtları toplu işleyerek ve istekleri sınırlar içinde eşzamanlı olarak göndererek işleme hızını en üst düzeye çıkarın.
• Teşhis ve izleme: Yanıt isteği kimliklerini yakalayın ve eşzamansız işlemeyi doğrulamak, uyarıları ve hataları tespit etmek için teşhis hizmetini sorgulayın.