인증 및 승인

다른 Google API와 마찬가지로 Google Ads API는 인증 및 승인에 OAuth 2.0 프로토콜을 사용합니다. OAuth 2.0을 사용하면 Google Ads API 클라이언트 앱이 사용자의 로그인 정보를 처리하거나 저장하지 않고도 사용자의 Google Ads 계정에 액세스할 수 있습니다.

Google Ads 액세스 모델 이해하기

Google Ads API를 효과적으로 사용하려면 Google Ads 액세스 모델의 작동 방식을 이해해야 합니다. Google Ads 액세스 모델 가이드를 읽어보시기 바랍니다.

OAuth 워크플로

Google Ads API를 사용할 때 일반적으로 사용되는 워크플로는 세 가지입니다.

서비스 계정 흐름

워크플로에 사람의 상호작용이 필요하지 않은 경우 이 워크플로를 사용하는 것이 좋습니다. 이 워크플로에는 사용자가 Google Ads 계정에 서비스 계정을 추가하는 구성 단계가 필요합니다. 그러면 앱이 서비스 계정의 사용자 인증 정보를 사용하여 사용자의 Google Ads 계정을 관리할 수 있습니다. 이를 구성하려면 Google Cloud 콘솔에서 JSON 키 파일을 만들고 다운로드한 다음 google_ads_config.rb를 홈 디렉터리에 복사하고 서비스 계정 키 파일 위치와 가장할 사용자의 이메일 주소를 지정하도록 수정합니다.

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

이 정보를 파일에 저장하지 않고 환경 변수를 사용하려면 GOOGLE_ADS_JSON_KEY_FILE_PATH 및 GOOGLE_ADS_IMPERSONATED_EMAIL을 각각 설정하면 됩니다.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

googleauth gem을 사용하여 서비스 계정 JSON 파일에서 사용자 인증 정보를 만들어 런타임에 프로그래매틱 방식으로 정보를 전달할 수도 있습니다.

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

자세한 내용은 서비스 계정 워크플로 가이드를 참고하세요.

단일 사용자 인증 흐름

서비스 계정을 사용할 수 없는 경우 이 워크플로를 사용할 수 있습니다. 이 워크플로에는 두 가지 구성 단계가 필요합니다.

  1. Google Ads API를 사용하여 관리할 모든 계정에 대한 액세스 권한을 단일 사용자에게 부여합니다. 일반적인 방법은 사용자에게 Google Ads API 관리자 계정을 부여하고 해당 관리자 계정 아래의 모든 Google Ads 계정을 연결하는 것입니다.
  2. 사용자가 gcloud 또는 GenerateUserCredentials 코드 예시와 같은 명령줄 도구를 실행하여 사용자를 대신해 모든 Google Ads 계정을 관리하도록 앱에 권한을 부여합니다.

google_ads_config.rb 파일을 홈 디렉터리에 복사하고 개발자 토큰, 클라이언트 ID, 클라이언트 보안 비밀번호, 갱신 토큰을 포함하도록 수정하여 Ruby용 OAuth 2.0 사용자 인증 정보를 구성할 수 있습니다.

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

인수 없이 인스턴스화하면 클라이언트가 홈 디렉터리에서 구성 파일을 자동으로 읽습니다.

client = Google::Ads::GoogleAds::GoogleAdsClient.new

또는 파일을 다른 곳에 저장하려면 이 파일을 보관하는 경로를 전달하여 클라이언트를 인스턴스화하면 됩니다.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

이 정보를 파일에 저장하지 않고 환경 변수를 사용하려면 각 변수를 설정하면 됩니다.

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

런타임에 프로그래매틱 방식으로 정보를 전달할 수도 있습니다.

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

자세한 내용은 단일 사용자 인증 워크플로 가이드를 참고하세요.

다중 사용자 인증 흐름

앱에서 사용자가 로그인하고 앱이 사용자를 대신하여 Google Ads 계정을 관리하도록 승인할 수 있는 경우 이 워크플로를 사용하는 것이 좋습니다. 앱이 OAuth 2.0 사용자 인증 정보를 빌드하고 관리합니다. 이 워크플로는 단일 사용자 흐름과 유사하게 구성할 수 있지만 login_customer_id도 지정해야 합니다.

구성 파일을 사용하는 것이 좋습니다. google_ads_config.rb 파일을 홈 디렉터리에 복사하고 개발자 토큰, 클라이언트 ID, 클라이언트 보안 비밀, 새로고침 토큰, 고객 ID를 포함하도록 수정합니다.

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

  # Required for manager accounts only: Specify the login customer ID used to
  # authenticate API calls. This will be the customer ID of the authenticated
  # manager account. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

인수 없이 인스턴스화하면 클라이언트가 홈 디렉터리에서 구성 파일을 자동으로 읽습니다.

client = Google::Ads::GoogleAds::GoogleAdsClient.new

또는 파일을 다른 곳에 저장하려면 이 파일을 보관하는 경로를 전달하여 클라이언트를 인스턴스화하면 됩니다.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

이 정보를 파일에 저장하지 않고 환경 변수를 사용하려면 각 변수를 설정하면 됩니다.

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

런타임에 프로그래매틱 방식으로 정보를 전달할 수도 있습니다.

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

자세한 내용은 다중 사용자 인증 워크플로 가이드를 참고하세요. Ruby 클라이언트 라이브러리에는 참조용 코드 예제가 포함되어 있습니다. GenerateUserCredentials는 런타임에 사용자 인증을 획득하여 사용자를 대신해 Google Ads 계정을 관리하는 방법을 보여주는 명령줄 코드 예입니다. 이 코드 예시를 참조하여 사용자 인증이 필요한 데스크톱 앱을 빌드할 수 있습니다.

사용자가 여러 계정을 관리하는 경우 어떻게 해야 하나요?

사용자가 계정에 직접 액세스하거나 Google Ads 관리자 계정을 통해 두 개 이상의 Google Ads 계정을 관리하는 것은 일반적입니다. Ruby 클라이언트 라이브러리는 이러한 사례를 처리하는 방법을 보여주는 다음 코드 예시를 제공합니다.

  1. GetAccountHierarchy 코드 예시에서는 Google Ads 관리자 계정의 모든 계정 목록을 가져오는 방법을 보여줍니다.
  2. ListAccessibleCustomers 코드 예시에서는 사용자가 직접 액세스할 수 있는 모든 계정의 목록을 가져오는 방법을 보여줍니다. 그런 다음 이러한 계정을 LoginCustomerId 설정의 유효한 값으로 사용할 수 있습니다.

애플리케이션 기본 사용자 인증 정보

Ruby 클라이언트 라이브러리는 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용한 인증도 지원합니다. 이를 통해 애플리케이션 구성 내에서 OAuth 2.0 정보를 구성하지 않고도 애플리케이션의 기본 사용자 인증 정보를 설정할 수 있습니다.

올바른 OAuth 2.0 범위에 액세스할 수 있는 경우 동일한 사용자 인증 정보를 재사용할 수 있으므로 로컬 개발이나 다양한 Google API에 대한 개발에 특히 유용합니다.

Google Ads API의 경우 애플리케이션 기본 사용자 인증 정보가 https://www.googleapis.com/auth/adwords OAuth 2.0 범위에 액세스할 수 있는지 확인하세요.

애플리케이션 기본 사용자 인증 정보를 사용하려면 Google Cloud 명령줄 도구를 사용하여 ADC를 인증하는 것이 좋습니다.

gcloud auth application-default login

이 명령어를 실행하면 Google 계정의 인증 흐름을 완료할 웹브라우저가 열립니다. 승인이 완료되면 사용자 인증 정보를 표준 위치에 저장합니다. 그런 다음 ADC를 사용하도록 애플리케이션을 업데이트해야 합니다.

구성 파일을 사용하는 것이 좋습니다. google_ads_config.rb 파일을 홈 디렉터리에 복사한 다음 개발자 토큰을 추가하고 use_application_default_credentials을 true로 설정합니다.

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

이 정보를 파일에 저장하지 않고 환경 변수를 사용하려면 GOOGLE_ADS_DEVELOPER_TOKEN 및 GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS를 설정하면 됩니다.

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

런타임에 프로그래매틱 방식으로 정보를 전달할 수도 있습니다. Ruby 코드에서 클라이언트를 초기화할 때 명시적 OAuth2 사용자 인증 정보를 제공하지 마세요. 라이브러리는 Google Cloud 명령줄 도구에서 설정한 사용자 인증 정보를 자동으로 감지하여 사용합니다. 개발자 토큰은 계속 지정해야 합니다.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

Ruby 클라이언트 라이브러리를 구성하는 데 사용할 수 있는 옵션에 관한 자세한 내용은 구성 페이지를 참고하세요.