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 웹 흐름 구현

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

오프라인 액세스 요청: access_type=offline 및 prompt=consent와 함께 https://www.googleapis.com/auth/datamanager 범위를 요청하는 Google의 OAuth 동의 화면으로 사용자를 안내합니다. 서버는 승인 코드를 액세스 토큰과 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 앱 인증 완료

https://www.googleapis.com/auth/datamanager는 민감한 범위이므로 외부 Google 계정에서 사용자 인증 정보를 가져오는 데 사용되는 Google Cloud 앱은 프로덕션으로 이동하기 전에 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` 설정