Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

프로덕션에 배포

이 가이드는 Data Manager API 프로덕션 배포에 적합한 인증 방법을 선택하고 구성하는 데 도움이 됩니다.

배포 시나리오 선택

애플리케이션 아키텍처 및 배포 환경과 일치하는 인증 방법을 선택합니다.

Google Cloud의 워크로드: Compute Engine, Cloud Run, Cloud Functions 또는 GKE에서 실행되는 자동화된 워크로드 (예: ETL 파이프라인, 일괄 작업 또는 백엔드 서비스)의 경우 연결된 서비스 계정 또는 GKE용 워크로드 아이덴티티 제휴와 함께 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용합니다.
Google Cloud 외부의 워크로드: 온프레미스 또는 다른 클라우드 제공업체에서 실행되는 자동화된 워크로드의 경우 워크로드 아이덴티티 제휴 또는 서비스 계정 키와 함께 애플리케이션 기본 사용자 인증 정보 (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}"

Google 서비스 계정 이메일로 Kubernetes 서비스 계정에 주석을 추가합니다.

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

포드 사양에서 Kubernetes 서비스 계정을 지정합니다.

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

IAM 및 계정 액세스 확인

프로덕션 애플리케이션을 배포하기 전에 서비스 계정에 필요한 권한이 있는지 확인합니다.

Google Cloud IAM 권한: Data Manager API가 사용 설정된 Google Cloud 프로젝트에서 서비스 계정에 서비스 사용 소비자 역할(roles/serviceusage.serviceUsageConsumer)을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"
```
대상 계정 액세스: 서비스 계정에 대상 계정에 필요한 액세스 권한을 부여합니다. 단계별 안내는 계정 액세스 설정을 참고하세요.

Google Cloud 외부의 워크로드

온프레미스 데이터 센터 또는 다른 클라우드 제공업체에서 코드를 실행할 때는 다음 인증 메커니즘 중 하나를 선택합니다.

워크로드 아이덴티티 제휴 (권장): 서비스 계정 키를 관리하지 않고도 애플리케이션이 외부 ID 공급업체의 사용자 인증 정보를 단기 Google Cloud 사용자 인증 정보로 교환할 수 있도록 워크로드 아이덴티티 제휴를 구성합니다. 사용자 인증 정보 구성 파일을 생성하고 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용하여 ADC에 제공합니다.
서비스 계정 키 (대체): 워크로드 아이덴티티 제휴를 사용할 수 없는 경우 서비스 계정 키를 만들고 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용하여 ADC에 제공합니다.

주의: 서비스 계정 키는 유출되거나 잘못 관리될 경우 보안 위험을 초래하는 장기 사용자 인증 정보입니다. 서비스 계정 키 관리 권장사항을 따르고 보안 비밀 관리자에 키를 저장하고, 파일 권한을 제한하고, 키를 정기적으로 순환합니다.

`GOOGLE_APPLICATION_CREDENTIALS` 설정

클라이언트 라이브러리가 ADC를 사용하여 사용자 인증 정보를 자동으로 찾을 수 있도록 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 워크로드 아이덴티티 제휴 사용자 인증 정보 구성 파일 또는 서비스 계정 키 파일의 절대 경로로 설정합니다.

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 요청 인증

자동화된 파이프라인이 클라이언트 라이브러리를 사용하는 대신 curl로 원시 HTTP 요청을 하는 경우 Google Cloud CLI를 사용하여 토큰을 수동으로 서명하지 않고도 비대화형으로 액세스 토큰을 인증하고 관리합니다.

환경에 구성된 사용자 인증 정보 파일을 사용하여 Google Cloud CLI를 승인합니다.
```
gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"
```

생성된 액세스 토큰을 API 요청의 Authorization 헤더에 전달합니다.

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 권한: Data Manager API가 사용 설정된 Google Cloud 프로젝트에서 서비스 계정에 서비스 사용 소비자 역할(roles/serviceusage.serviceUsageConsumer)을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"
```
대상 계정 액세스: 서비스 계정에 대상 계정에 필요한 액세스 권한을 부여합니다. 단계별 안내는 계정 액세스 설정을 참고하세요.

사용자 대신 작업

마케팅 플랫폼 및 대행사와 같은 서드 파티 플랫폼은 서비스에 가입하는 여러 광고주를 대신하여 API 요청을 보내야 하는 경우가 많습니다.

이 아키텍처에서는 애플리케이션 기본 사용자 인증 정보를 사용하는 대신 OAuth 2.0 웹 서버 흐름을 사용하여 각 광고주로부터 오프라인 액세스 권한이 있는 사용자 인증 정보를 가져온 다음 요청이 관리하는 광고주 계정에 따라 런타임 시 이러한 사용자 인증 정보를 사용하여 클라이언트 라이브러리를 구성합니다.

OAuth 2.0 웹 흐름 구현

멀티 테넌트 애플리케이션의 사용자 위임을 설정하는 방법은 다음과 같습니다.

오프라인 사용 요청: 사용자에게 Google의 OAuth 동의 화면으로 안내합니다. https://www.googleapis.com/auth/datamanager 범위를 access_type=offline 및 prompt=consent로 요청합니다. 서버는 승인 코드를 액세스 토큰 및 refresh_token으로 교환합니다. 단계별 안내는 웹 서버 애플리케이션용 OAuth 2.0을 참고하세요.
사용자 인증 정보를 안전하게 저장: 각 사용자의 갱신 토큰을 플랫폼의 계정과 연결된 암호화된 사용자 인증 정보 저장소에 안전하게 저장합니다.

런타임 시 클라이언트 라이브러리 초기화: 특정 사용자를 대신하여 API 요청을 보낼 때 사용자를 위해 저장한 갱신 토큰과 앱의 클라이언트 ID 및 클라이언트 보안 비밀에서 사용자 인증 정보를 구성하고 클라이언트를 초기화할 때 전달합니다.

.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 계정에서 사용자 인증 정보를 가져오는 데 사용되는 모든 Google 클라우드 앱은 프로덕션으로 전환하기 전에 Google OAuth 인증을 거쳐야 합니다.

개발: Google Cloud 콘솔의 잠재고객 페이지에서 앱의 게시 상태가 테스트 중으로 설정된 동안에는 지정된 테스트 계정만 애플리케이션을 승인할 수 있습니다.
프로덕션: 외부 사용자가 애플리케이션을 사용할 수 있도록 하기 전에 게시 상태를 프로덕션 중으로 설정하고 인증을 위해 앱을 제출합니다.

서비스 계정을 사용하여 실행되는 워크로드에는 앱 인증이 필요하지 않습니다. 또한 내부 애플리케이션과 같은 시나리오에는 몇 가지 예외가 있습니다. 자세한 내용은 인증이 필요하지 않은 경우를 참고하세요.

대체: 파트너 링크

조직이 승인된 데이터 파트너인 경우 지속적인 데이터 수집을 위해 사용자별 OAuth 토큰을 관리하는 대신 파트너 링크를 사용할 수 있습니다.

파트너 링크를 사용하면 광고주가 Google Ads, Display &Video 360 또는 Google Ad Manager UI에서 계정을 데이터 파트너 계정에 연결합니다. 연결이 설정되면 애플리케이션은 ADC를 통해 자체 서비스 계정 사용자 인증 정보를 사용하여 수집 요청을 보내므로 장기 사용자 갱신 토큰을 저장하고 유지관리할 필요가 없습니다.

프로덕션 권장사항

프로덕션으로 전환할 때 다음과 같은 주요 운영 고려사항을 검토하세요.

오류 처리 및 유효성 검사: API가 빠른 실패 모델을 사용하여 요청의 유효성을 검사하고 구조화된 오류 세부정보를 반환하는 방법을 이해합니다.
재시도 전략: 일시적인 서버 오류에 지터가 있는 지수 백오프를 구현합니다.
일괄 처리 및 동시 실행: 레코드를 일괄 처리하고 제한 내에서 요청을 동시에 전송하여 처리량을 극대화합니다.
진단 및 모니터링: 응답 요청 ID를 캡처하고 진단 서비스를 쿼리하여 비동기 처리를 확인하고 경고 및 오류를 감지합니다.

프로덕션에 배포 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

배포 시나리오 선택

Google Cloud의 워크로드

Compute Engine

Cloud Run

Cloud Functions

GKE

IAM 및 계정 액세스 확인

Google Cloud 외부의 워크로드

GOOGLE_APPLICATION_CREDENTIALS 설정

Linux / macOS

Windows (PowerShell)

Docker / 컨테이너

Kubernetes

REST 및 curl 요청 인증

IAM 및 계정 액세스 확인

사용자 대신 작업

OAuth 2.0 웹 흐름 구현

.NET

Go

Java

Node.js

PHP

Python

Ruby

OAuth 앱 인증 완료

대체: 파트너 링크

프로덕션 권장사항

프로덕션에 배포

`GOOGLE_APPLICATION_CREDENTIALS` 설정