‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

פריסה בסביבת הייצור

המדריך הזה יעזור לכם לבחור ולהגדיר את שיטת האימות המתאימה לפריסת הייצור של Data Manager API.

בחירת תרחיש הפריסה

בוחרים את גישת האימות שמתאימה לארכיטקטורה של האפליקציה ולסביבת הפריסה:

עומסי עבודה ב-Google Cloud: לעומסי עבודה אוטומטיים (כמו צינורות עיבוד נתונים של ETL, משימות באצווה או שירותים לקצה העורפי) שפועלים ב-Compute Engine, ב-Cloud Run, ב-Cloud Functions או ב-GKE, משתמשים בApplication Default Credentials‏ (ADC) עם חשבון שירות מצורף או באיחוד זהויות של עומסי עבודה ל-GKE.
עומסי עבודה מחוץ ל-Google Cloud: לעומסי עבודה אוטומטיים שפועלים באופן מקומי או אצל ספקי שירותי ענן אחרים, משתמשים בApplication Default Credentials ‏ (ADC) עם איחוד שירותי אימות הזהות של עומסי עבודה או עם מפתח של חשבון שירות.
ביצוע פעולות בשם המשתמשים: בפלטפורמות של צד שלישי ובאפליקציות עם כמה דיירים שמנהלות חשבונות של משתמשים חיצוניים (כמו מפרסמים שנרשמים לפלטפורמה שלכם), השתמשו בתהליך של שרת אינטרנט עם OAuth 2.0 עם טוקני רענון לכל משתמש, או בקישורי שותפים אם אתם שותפי נתונים מאושרים.

הנחיות כלליות בנושא אימות ב-Google Cloud זמינות בעץ ההחלטות בנושא אימות ב-Google Cloud.

עומסי עבודה ב-Google Cloud

כשמפעילים את Google Cloud, מצרפים חשבון שירות ישירות למשאב המחשוב או מגדירים איחוד זהויות של עומסי עבודה ל-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

מפעילים באשכול את איחוד הזהויות של עומסי העבודה ל-GKE.

מקשרים את חשבון השירות של 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}"

מוסיפים הערה לחשבון השירות ב-Kubernetes עם כתובת האימייל של חשבון השירות ב-Google:

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

מציינים את חשבון השירות של Kubernetes במפרט ה-pod:

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

אימות של IAM ושל גישה לחשבון

לפני שפורסים את האפליקציה בסביבת הייצור, צריך לוודא שלחשבון השירות יש את ההרשאות הנדרשות:

הרשאות 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"
```
גישה לחשבון היעד: נותנים לחשבון השירות את הגישה הנדרשת לחשבונות היעד. להוראות מפורטות, ראו הגדרת גישה לחשבון.

עומסי עבודה מחוץ ל-Google Cloud

כשמריצים קוד במרכזי נתונים מקומיים או בספקי שירותי ענן אחרים, בוחרים באחד ממנגנוני האימות הבאים:

איחוד שירותי אימות הזהות של עומסי עבודה (מומלץ): מגדירים את איחוד שירותי אימות הזהות של עומסי עבודה כדי לאפשר לאפליקציה להחליף את פרטי הכניסה מספק הזהויות החיצוני בפרטי כניסה ל-Google Cloud לזמן קצר, בלי לנהל את המפתחות של חשבון השירות. יוצרים קובץ תצורה של פרטי הכניסה ומספקים אותו ל-ADC באמצעות משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.
מפתחות של חשבונות שירות (Fallback): אם איחוד שירותי אימות הזהות של עומסי עבודה לא זמין, יוצרים מפתח של חשבון שירות ומספקים אותו ל-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 / Containers

מגדירים את קובץ פרטי הכניסה בקונטיינר ומגדירים את משתנה הסביבה:

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

טוענים את פרטי הכניסה כסוד ומשתמשים בהם בסביבת ה-Pod:

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 כדי לבצע אימות לא אינטראקטיבי ולנהל טוקני גישה בלי לחתום על טוקנים באופן ידני:

נותנים הרשאה ל-Google Cloud CLI באמצעות קובץ פרטי הכניסה שהוגדר בסביבה:
```
gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"
```
מעבירים את אסימון הגישה שנוצר בכותרת 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 ושל הגישה לחשבון

לפני שפורסים את האפליקציה בסביבת הייצור, צריך לוודא שלחשבון השירות יש את ההרשאות הנדרשות:

הרשאות 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"
```
גישה לחשבון היעד: נותנים לחשבון השירות את הגישה הנדרשת לחשבונות היעד. להוראות מפורטות, ראו הגדרת גישה לחשבון.

לבצע פעולות בשם המשתמשים

פלטפורמות של צד שלישי, כמו פלטפורמות שיווק וסוכנויות, צריכות לעיתים קרובות לשלוח בקשות API בשם כמה מפרסמים שנרשמים לשירות שלהן.

בארכיטקטורה הזו, במקום להשתמש ב-Application Default Credentials, משתמשים בתהליך של שרת אינטרנט ב-OAuth 2.0 כדי לקבל מכל מפרסם פרטי כניסה של משתמש עם גישה אופליין, ואז משתמשים בפרטי הכניסה האלה כדי להגדיר את ספריית הלקוח בזמן הריצה על סמך חשבון המפרסם שהבקשה מנהלת.

הטמעת תהליך האימות של OAuth 2.0 באינטרנט

כך מגדירים הקצאת הרשאות למשתמשים באפליקציות עם כמה דיירים:

בקשת גישה אופליין: מפנים את המשתמשים למסך ההסכמה של OAuth ב-Google, ומבקשים את היקף ההרשאות https://www.googleapis.com/auth/datamanager עם access_type=offline ו-prompt=consent. השרת מחליף את קוד ההרשאה בטוקן גישה וב-refresh_token. הוראות מפורטות זמינות במאמר OAuth 2.0 לאפליקציות של שרת אינטרנט.
אחסון מאובטח של פרטי הכניסה: צריך לאחסן בצורה מאובטחת את טוקן הרענון של כל משתמש במאגר פרטי כניסה מוצפן שמקושר לחשבון שלו בפלטפורמה שלכם.

הפעלת ספריות לקוח בזמן הריצה: כששולחים בקשת 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();

Go

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 חיצוניים צריכה לעבור אימות של Google OAuth לפני המעבר לסביבת הייצור:

פיתוח: בזמן שסטטוס הפרסום של האפליקציה מוגדר כבדיקה בדף 'קהל' במסוף Google Cloud, רק חשבונות בדיקה ייעודיים יכולים לאשר את האפליקציה.
ייצור: לפני שמאפשרים למשתמשים חיצוניים להשתמש באפליקציה, צריך להגדיר את סטטוס הפרסום לערך בייצור ולשלוח את האפליקציה לאימות.

לא נדרש אימות אפליקציות לעומסי עבודה שפועלים באמצעות חשבונות שירות. בנוסף, יש כמה חריגים לתרחישים כמו אפליקציות פנימיות. פרטים נוספים זמינים בקטע מתי לא צריך אימות.

חלופה: קישורים לשותפים

אם הארגון שלכם הוא שותף נתונים מאושר, אתם יכולים להשתמש בקישורים לשותפים במקום לנהל אסימוני OAuth לכל משתמש לצורך הטמעת נתונים שוטפת.

באמצעות קישורים לשותפים, מפרסמים מקשרים את החשבונות שלהם לחשבון של שותף הנתונים בממשק המשתמש של Google Ads,‏ Display & Video 360 או Google Ad Manager. אחרי שהקישור נוצר, האפליקציה שולחת בקשות להעברת נתונים באמצעות פרטי הכניסה של חשבון השירות שלכם דרך ADC, וכך נמנע הצורך לאחסן ולתחזק אסימוני רענון של משתמשים לטווח ארוך.

שיטות מומלצות להפקה

כשעוברים לסביבת הייצור, חשוב לבדוק את השיקולים התפעוליים העיקריים הבאים:

טיפול בשגיאות ואימות: הסבר על האופן שבו ה-API מאמת בקשות באמצעות מודל של כשל מהיר ומחזיר פרטי שגיאה מובנים.
אסטרטגיית ניסיון חוזר: כדאי להטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם רעידות (jitter) לשגיאות בחיבור לשרת זמניות.
אצווה וביצוע בו-זמני: כדי למקסם את קצב העברת הנתונים, צריך ליצור אצווה של רשומות ולשלוח בקשות בו-זמנית במסגרת המגבלות.
אבחון ומעקב: מתעדים את מזהי הבקשות בתגובה ושולחים שאילתות לשירות האבחון כדי לאמת את העיבוד האסינכרוני ולזהות אזהרות ושגיאות.