서비스 계정

이 가이드에서는 서비스 계정으로 Google Ads API에 액세스하는 방법을 설명합니다.

서비스 계정은 개별 최종 사용자가 아닌 앱에 속한 계정입니다. 서비스 계정은 웹 앱과 Google 서비스 간의 서버 간 상호작용을 지원합니다. 앱은 서비스 계정을 대신하여 Google API를 호출하므로 사용자가 직접 관여하지 않습니다.

서비스 계정은 사람의 승인이 필요하지 않은 OAuth 2.0 흐름을 사용하며, 대신 앱만 액세스할 수 있는 키 파일을 사용합니다.

서비스 계정을 사용하면 다음과 같은 두 가지 주요 이점이 있습니다.

  • Google API 액세스 승인은 구성 단계로 실행되므로 사용자 상호작용이 필요한 다른 OAuth 2.0 흐름과 관련된 복잡성을 방지할 수 있습니다.

  • OAuth 2.0 어설션 흐름을 사용하면 필요한 경우 앱이 다른 사용자의 명의를 도용할 수 있습니다.

서비스 계정으로 승인하는 방법에는 직접 또는 명의 도용의 두 가지가 있습니다.

직접 계정 액세스 권한으로 승인

이 옵션에서는 서비스 계정에 Google Ads 계정에 대한 직접 액세스 권한을 부여합니다.

계정 액세스 설정

  1. 먼저 서비스 계정 및 사용자 인증 정보를 만듭니다.

    서비스 계정 키를 JSON 형식으로 다운로드하고 서비스 계정 ID와 이메일을 기록합니다.

  2. 관리자로 Google Ads 계정에 로그인합니다. 관리 > 액세스 및 보안으로 이동합니다.

  3. 사용자 탭 아래의 + 버튼을 클릭합니다.

  4. 이메일 입력 상자에 서비스 계정 이메일을 입력합니다. 적절한 계정 액세스 수준을 선택하고 계정 추가 버튼을 클릭합니다. 서비스 계정에는 이메일 및 관리 액세스 수준이 지원되지 않습니다.

  5. 서비스 계정에 액세스 권한이 부여됩니다.

클라이언트 라이브러리 구성

클라이언트 라이브러리를 구성하는 방법에 관한 안내는 프로그래밍 언어에 해당하는 탭을 선택하세요.

자바

구성에서 비공개 키 JSON 경로를 설정합니다. ads.properties 파일을 사용하는 경우 다음을 추가합니다.

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

자세한 내용은 구성 가이드를 참고하세요.

.NET

App.config / Web.config에서 다음 키를 구성합니다. 자세한 내용은 구성 가이드를 참고하세요.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Python

구성에서 비공개 키 JSON 경로를 설정합니다. google-ads.yaml file, YAML 문자열 또는 dict을 사용하는 경우 다음을 추가합니다.

json_key_file_path: JSON_KEY_FILE_PATH

환경 변수를 사용하는 경우 Bash 구성 또는 환경에 다음을 추가합니다.

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

google_ads_php.ini에서 다음 키를 구성합니다. 자세한 내용은 구성 가이드를 참고하세요.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Ruby

google_ads_config.rb에서 다음 키를 구성합니다.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

구성에서 비공개 키 JSON 경로를 설정하고 계정 ID를 위임합니다. googleads.properties 파일을 사용하는 경우 다음을 추가합니다.

jsonKeyFilePath=JSON_KEY_FILE_PATH

환경 변수를 사용하는 경우 Bash 구성 또는 환경에 다음을 추가합니다.

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

가장을 사용한 승인

이 옵션에서는 서비스 계정을 사용하여 Google Ads 계정에 액세스할 수 있는 사용자를 가장합니다. 이 방법은 Google Workspace 고객에게만 적용됩니다. 서비스 계정은 동일한 Google Workspace의 사용자 (이메일 주소)만 명의 도용할 수 있습니다.

기본 요건

  • 소유한 Google Workspace 도메인(예: mydomain.com 또는 mybusiness.com)

  • Google Ads API 개발자 토큰 및 선택적으로 테스트 계정

  • 사용 중인 언어의 클라이언트 라이브러리

  • Google Ads API용으로 구성된 Google API 콘솔 프로젝트

  • 액세스하려는 Google Ads 계정에 대한 권한이 있는 Google Ads 사용자 Google Ads에서는 명의 도용 없이 서비스 계정을 사용하는 것을 지원하지 않습니다.

서비스 계정 액세스 설정

사용자 명의 도용은 도메인 수준에서만 제어되므로 Google OAuth 2.0으로 서비스 계정 및 어설션 흐름을 사용하려면 Google Workspace에 등록된 자체 도메인이 있어야 합니다. 그러면 앱과 앱 사용자는 도메인의 모든 사용자를 명의 도용할 수 있습니다.

  1. 먼저 서비스 계정 및 사용자 인증 정보를 만듭니다.

    JSON 형식의 서비스 계정 키를 다운로드하고 서비스 계정 ID를 기록합니다.

  2. 서비스 계정 ID와 Google Ads API 범위(https://www.googleapis.com/auth/adwords)를 도메인 관리자와 공유합니다.

    도메인 관리자에게 서비스 계정에 도메인 전체 권한을 위임해 달라고 요청합니다.

  3. 도메인 관리자인 경우 고객센터 안내를 완료하세요.

이제 서비스 계정을 사용하여 OAuth 2.0 어설션 흐름으로 Google Ads 계정에 액세스할 수 있습니다.

클라이언트 라이브러리 구성

클라이언트 라이브러리를 구성하는 방법에 관한 안내는 프로그래밍 언어에 해당하는 탭을 선택하세요.

자바

구성에서 비공개 키 JSON 경로를 설정하고 계정 ID를 위임합니다. ads.properties 파일을 사용하는 경우 다음을 추가합니다.

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

자세한 내용은 구성 가이드를 참고하세요.

.NET

App.config / Web.config에서 다음 키를 구성합니다. 자세한 내용은 구성 가이드를 참고하세요.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Python

구성에서 비공개 키 JSON 경로와 명의 도용된 이메일을 설정합니다. google-ads.yaml file, YAML 문자열 또는 dict을 사용하는 경우 다음을 추가합니다.

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

환경 변수를 사용하는 경우 Bash 구성 또는 환경에 다음을 추가합니다.

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

google_ads_php.ini에서 다음 키를 구성합니다. 자세한 내용은 구성 가이드를 참고하세요.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Ruby

google_ads_config.rb에서 다음 키를 구성합니다.

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Perl

구성에서 비공개 키 JSON 경로를 설정하고 계정 ID를 위임합니다. googleads.properties 파일을 사용하는 경우 다음을 추가합니다.

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

환경 변수를 사용하는 경우 Bash 구성 또는 환경에 다음을 추가합니다.

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

보안 문제

서비스 계정에는 Google Workspace 도메인에 대한 도메인 수준 위임 제어가 있으므로 서비스 계정이 승인된 Google 서비스에 액세스할 수 있도록 허용하는 키 파일을 보호하는 것이 중요합니다. 이는 서비스 계정이 도메인의 모든 사용자를 가장할 수 있으므로 특히 중요합니다.

서비스 계정이 필요한 최소 API 집합에만 액세스하도록 허용하는 것도 좋습니다. 이는 서비스 계정의 키 파일이 손상된 경우 공격자가 액세스할 수 있는 데이터의 양을 제한하기 위한 사전 예방 조치입니다.