다른 Google API와 마찬가지로 Google Ads API는 인증 및 승인에 OAuth 2.0 프로토콜을 사용합니다. OAuth 2.0을 사용하면 Google Ads API 클라이언트 앱이 사용자의 로그인 정보를 처리하거나 저장하지 않고도 사용자의 Google Ads 계정에 액세스할 수 있습니다.
이 가이드에서는 가장 일반적인 세 가지 OAuth 2.0 흐름을 사용하여 Google Ads API 인증을 위한 Java 클라이언트 라이브러리를 구성하는 방법과 필요한 사용자 인증 정보를 설명합니다.
Google Ads API 액세스 모델에 대해 자세히 알아보려면 Google Ads 액세스 모델 가이드를 참고하세요.
사용자 인증 정보
Google Ads API에 액세스하려면 개발자 토큰, OAuth 2.0 사용자 인증 정보, 경우에 따라 로그인 고객 ID가 필요합니다.
개발자 토큰
개발자 토큰은 관리자 계정에 연결되어 있으며 Google Ads 웹 인터페이스에서 확인할 수 있습니다.
개발자 토큰은 관리자 계정에 연결되지만 해당 계정에 대한 액세스 권한을 제공하지는 않습니다. 대신 개발자 토큰은 API에 대한 액세스 권한을 부여하며 계정 수준 액세스는 OAuth 2.0을 통해 구성됩니다.
클라이언트 라이브러리에서 개발자 토큰은 ads.properties 파일의 api.googleads.developerToken 키로 지정됩니다.
OAuth 2.0 사용자 인증 정보
Google Ads 계정에 액세스할 수 있는 Google 계정 사용자로 승인하려면 OAuth 2.0 사용자 인증 정보 집합을 제공해야 합니다. 필요한 사용자 인증 정보의 유형은 사용 중인 OAuth 2.0 흐름에 따라 다릅니다.
이 라이브러리는 다음 세 가지 흐름을 지원합니다.
- 서비스 계정 흐름
- 단일 사용자 인증 흐름
- 다중 사용자 인증 흐름
Google Ads API OAuth 흐름에 대한 자세한 내용은 OAuth 개요를 참고하고, 필요에 가장 적합한 흐름에 대한 안내를 따라 필요한 사용자 인증 정보를 획득하세요.
로그인 고객 ID
원하는 경우 게재 계정에 대한 액세스 권한을 제공하는 관리자 계정의 고객 ID를 지정합니다. 고객 계정에 대한 액세스가 관리자 계정을 통해 이루어지는 경우 지정해야 합니다. 고객 ID로 이어지는 경로에 모든 관리자 계정을 지정할 필요는 없으며 액세스 권한에 사용하는 최상위 관리자 ID만 지정하면 됩니다. 자세한 내용은 관련 문서를 참고하세요.
클라이언트 라이브러리에서 로그인 고객 ID는 ads.properties 파일의 api.googleads.loginCustomerId 키로 지정됩니다.
구성
ads.properties 파일, 환경 변수 또는 프로그래매틱 방식으로 클라이언트 라이브러리를 구성할 수 있습니다. 이 가이드에서는 ads.properties 파일을 사용하는 데 중점을 둡니다. 모든 옵션에 관한 자세한 내용은 구성 가이드를 참고하세요.
ads.properties 파일을 사용하는 경우 홈 디렉터리(~/ads.properties)에 파일을 배치합니다.
OAuth 워크플로
Google Ads API를 사용할 때 일반적으로 사용되는 워크플로는 세 가지입니다.
서비스 계정 흐름
워크플로에 사람의 상호작용이 필요하지 않은 경우 이 워크플로를 사용하는 것이 좋습니다. 이 워크플로에는 사용자가 Google Ads 계정에 서비스 계정을 추가하는 구성 단계가 필요합니다. 그러면 앱이 서비스 계정의 사용자 인증 정보를 사용하여 사용자의 Google Ads 계정을 관리할 수 있습니다.
비공개 키 JSON 파일이 있으면 ads.properties 파일에 다음을 추가합니다.
api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE
자세한 내용은 서비스 계정 워크플로 가이드를 참고하세요.
단일 사용자 인증 흐름
서비스 계정을 사용할 수 없는 경우 이 워크플로를 사용할 수 있습니다. 이 워크플로는 두 가지 구성 단계가 필요합니다.
- Google Ads API를 사용하여 관리할 모든 계정에 대한 액세스 권한을 단일 사용자에게 부여합니다. 일반적인 방법은 사용자에게 Google Ads API 관리자 계정을 부여하고 해당 관리자 계정 아래의 모든 Google Ads 계정을 연결하는 것입니다.
- 사용자가 gcloud 또는
GenerateUserCredentials코드 예시와 같은 명령줄 도구를 실행하여 사용자를 대신해 모든 Google Ads 계정을 관리할 수 있도록 앱에 권한을 부여합니다.
이 사용자 인증 정보를 얻은 후 ads.properties 파일에 다음을 추가합니다.
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
자세한 내용은 단일 사용자 인증 워크플로 가이드를 참고하세요.
다중 사용자 인증 흐름
앱에서 사용자가 로그인하고 앱이 사용자를 대신하여 Google Ads 계정을 관리하도록 승인할 수 있는 경우 이 워크플로를 사용하는 것이 좋습니다. GenerateUserCredentials는 런타임에 사용자 인증을 획득하여 사용자를 대신해 Google Ads 계정을 관리하는 방법을 보여주는 명령줄 코드 예시입니다. 이 코드 예시를 참고하여 사용자 인증이 필요한 데스크톱 앱을 빌드할 수 있습니다.
ads.properties 파일에 다음을 추가합니다.
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
자세한 내용은 다중 사용자 인증 워크플로 가이드를 참고하세요.
사용자가 여러 계정을 관리하는 경우 어떻게 해야 하나요?
사용자가 계정에 직접 액세스하거나 Google Ads 관리자 계정을 통해 두 개 이상의 Google Ads 계정을 관리하는 것은 일반적입니다. Java 클라이언트 라이브러리는 이러한 사례를 처리하는 방법을 보여주는 다음 코드 예시를 제공합니다.
- GetAccountHierarchy 코드 예에서는 Google Ads 관리자 계정의 모든 계정 목록을 가져오는 방법을 보여줍니다.
- ListAccessibleCustomers 코드 예시에서는 사용자가 직접 액세스할 수 있는 모든 계정의 목록을 가져오는 방법을 보여줍니다.
그런 다음 이러한 계정을
LoginCustomerId설정의 유효한 값으로 사용할 수 있습니다.
애플리케이션 기본 사용자 인증 정보
Java 클라이언트 라이브러리는 애플리케이션 기본 사용자 인증 정보를 사용한 인증도 지원합니다.
이는 올바른 OAuth 2.0 범위에 액세스할 수 있는 경우 동일한 사용자 인증 정보를 재사용할 수 있으므로 로컬 개발이나 다양한 Google API에 대한 개발에 특히 유용합니다.
Google Ads API의 경우 애플리케이션 기본 사용자 인증 정보가 https://www.googleapis.com/auth/adwords OAuth 2.0 범위에 액세스할 수 있는지 확인하세요.
애플리케이션 기본 사용자 인증 정보를 사용하려면 ads.properties 파일에서 api.googleads.useApplicationDefaultCredentials 옵션을 true로 설정합니다. 애플리케이션 기본 사용자 인증 정보를 사용하는 경우 클라이언트 ID, 클라이언트 보안 비밀번호, 갱신 토큰을 설정하면 안 됩니다.