인증 및 승인

다른 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 계정을 관리할 수 있습니다. Python 라이브러리는 다음과 같이 구성됩니다.

  • google-ads.yaml 파일 또는 YAML 문자열을 사용하는 경우 다음을 구성에 추가하여 로컬 환경에서 비공개 키 JSON 파일의 경로를 설정합니다.

    json_key_file_path: JSON_KEY_FILE_PATH

    그런 다음 load_from_storage 또는 load_from_string 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • dict를 사용하여 라이브러리를 구성하는 경우 다음 키-값 쌍을 포함하고 구성 dict를 전달하여 load_from_dict 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    그런 다음 load_from_env 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

이러한 구성 방법 중 하나에 json_key_file_path 구성 옵션이 있고 use_application_default_credentials 옵션이 False이거나 설정되지 않은 경우 라이브러리는 서비스 계정 흐름을 사용하여 자동으로 승인합니다.

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

단일 사용자 인증 흐름

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

  1. Google Ads API를 사용하여 관리할 모든 계정에 대한 액세스 권한을 단일 사용자에게 부여합니다. 일반적인 방법은 사용자에게 Google Ads API 관리자 계정을 부여하고 해당 관리자 계정 아래의 모든 Google Ads 계정을 연결하는 것입니다.

  2. 사용자가 gcloud CLI 또는 generate_user_credentials 코드 예시와 같은 도구를 실행하여 사용자를 대신해 모든 Google Ads 계정을 관리할 수 있도록 앱을 승인합니다.

다음과 같이 사용자의 OAuth 2.0 사용자 인증 정보를 사용하여 라이브러리를 초기화할 수 있습니다.

gcloud CLI 도구를 사용하는 경우 (권장)

  1. 사용자 인증 정보 생성 문서를 따라 로컬 환경에서 애플리케이션 기본 사용자 인증 정보 (ADC)를 설정합니다.

  2. google-ads.yaml 또는 YAML 문자열에 다음 구성을 추가합니다.

    use_application_default_credentials: true

    그런 다음 load_from_storage 또는 load_from_string 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    dict를 사용하여 라이브러리를 구성하는 경우 다음 키-값 쌍을 포함하고 load_from_dict 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    그런 다음 load_from_env 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

OAuth 토큰을 직접 처리하는 경우

  1. 단계를 따라 콘솔 프로젝트를 설정하고 프로젝트의 클라이언트 ID와 클라이언트 보안 비밀이 포함된 JSON 파일을 다운로드합니다.

  2. Python 클라이언트 라이브러리를 머신에 클론하고 해당 디렉토리로 변경합니다.

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. 1단계에서 다운로드한 JSON 파일의 절대 경로를 제공하여 예시를 실행합니다.

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    완료되면 콘솔에 새로고침 토큰이 출력됩니다. 복사하여 다음 단계를 위해 저장합니다.

  4. 원하는 구성에 다음 설정을 추가하여 라이브러리를 구성합니다.

    google-ads.yaml 또는 YAML 문자열에 다음 구성을 추가합니다.

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    그런 다음 load_from_storage 또는 load_from_string 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    dict를 사용하여 라이브러리를 구성하는 경우 다음 키-값 쌍을 포함하고 load_from_dict 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    그런 다음 load_from_env 메서드를 호출합니다.

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

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

다중 사용자 인증 흐름

앱에서 사용자가 로그인하고 앱이 사용자를 대신하여 Google Ads 계정을 관리하도록 승인할 수 있는 경우 이 워크플로를 사용하는 것이 좋습니다. 앱이 OAuth 2.0 사용자 인증 정보를 빌드하고 관리합니다. 라이브러리는 다음과 같이 사용자의 사용자 인증 정보를 사용하여 초기화할 수 있습니다. 이는 애플리케이션이 승인 흐름을 실행하거나 데이터 스토어에서 로드하여 런타임에 사용자 인증 정보를 획득한다고 가정합니다.

dict은 런타임에 사용자 인증 정보를 획득할 때 사용할 수 있는 가장 간단한 구성 메커니즘입니다.

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

수동 인증

어떤 방식으로든 인증 사용자 인증 정보를 생성하고 클라이언트 클래스를 직접 인스턴스화하여 GoogleAdsClient에 수동으로 제공할 수 있습니다. 만든 사용자 인증 정보 객체가 google.auth.credentials.Credentials의 인스턴스라고 가정하면 다음과 같이 전달할 수 있습니다.

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

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

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