Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

구성

Google Ads API PHP 클라이언트 라이브러리는 라이브러리 동작을 맞춤설정하는 데 사용할 수 있는 여러 구성 설정을 제공합니다.

구성 파일

이러한 구성 설정 대부분을 INI 구성 파일에 저장하고 클라이언트를 인스턴스화할 때(예: google_ads_php.ini) 사용할 수 있습니다.

사용자 인증 정보와 클라이언트 빌더는 모두 이러한 파일에서 설정을 로드하는 fromFile 메서드를 제공합니다.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

구성 경로가 인수로 제공되지 않으면 fromFile 메서드가 다음 기본 구성 경로에서 로드됩니다.

설정된 경우 GOOGLE_ADS_CONFIGURATION_FILE_PATH이라는 환경 변수의 값입니다.
그렇지 않은 경우 HOME 디렉터리의 google_ads_php.ini 파일

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

동적 구성

클라이언트를 인스턴스화할 때 다음 구성 설정을 동적으로 설정할 수 있습니다.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

구성 환경 변수

클라이언트를 인스턴스화할 때 환경 변수에서 일부 구성 설정을 설정할 수 있습니다 (표준 환경 변수 참고).

사용자 인증 정보와 클라이언트 빌더는 모두 환경 변수에서 설정을 로드하는 fromEnvironmentVariables 메서드를 제공합니다.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

구성 필드

구성 설정은 카테고리로 정리된 여러 필드를 지원합니다.

OAuth2TokenBuilder에서 사용되는 필드:
- 애플리케이션 모드:
  - [OAUTH2] clientId: OAuth2 클라이언트 ID입니다.
  - [OAUTH2] clientSecret: OAuth2 클라이언트 보안 비밀번호입니다.
  - [OAUTH2] refreshToken: OAuth2 갱신 토큰입니다.
- 서비스 계정 모드:
  - [OAUTH2] jsonKeyFilePath: JSON 키 경로입니다.
  - [OAUTH2] scopes: OAuth2 범위입니다 (v32.1.0 이상에서는 https://www.googleapis.com/auth/adwords이 기본값임. v32.1.0 이전 버전이나 맞춤 범위를 사용하는 경우에는 필수임. fromEnvironmentVariables()에서는 환경 변수에서 읽지 않음).
  - [OAUTH2] impersonatedEmail: Google Workspace 도메인 전체 위임을 사용할 때 가장할 이메일 주소(선택사항)
- 애플리케이션 기본 사용자 인증 정보 모드:
  - 애플리케이션 모드 필드와 서비스 계정 모드 필드가 모두 설정되지 않은 경우 OAuth2TokenBuilder는 애플리케이션 기본 사용자 인증 정보 (ADC)로 자동 대체됩니다.
GoogleAdsClientBuilder에서 사용되는 필드:
- [GOOGLE_ADS] developerToken: (2026년 9월 9일 지원 종료) Google Ads API 개발자 토큰입니다. 선택사항이며, 클라이언트 라이브러리 버전과 관계없이 API 서버에서 무시되며, 향후 Google Ads API의 메이저 버전에서 거부됩니다.
  - v35.0.0 이상: 클라이언트 초기화 시 필요하지 않음(GoogleAdsClientBuilder에서 로컬 클라이언트 측 개발자 토큰 검증 삭제).
  - v35.0.0 이전 버전: 로컬 클라이언트 측 구성 유효성 검사에 필요합니다.
- [GOOGLE_ADS] loginCustomerId: 요청에 사용할 승인된 고객의 ID입니다.
- [GOOGLE_ADS] linkedCustomerId: 연결된 고객 ID입니다.
- [GOOGLE_ADS] endpoint: 선택사항인 대체 Google Ads API 서버 엔드포인트입니다.
- [LOGGING] logFilePath: 로깅 출력의 경로입니다.
- [LOGGING] logLevel: 로깅 수준입니다.
- [CONNECTION] proxy: 인터넷 연결에 사용되는 프록시 서버 URL입니다.
- [CONNECTION] transport: 네트워크 전송 (grpc 또는 rest)
- [CONNECTION] grpcChannelIsSecure: gRPC 채널이 보안 채널인지 여부입니다.
- [CONNECTION] grpcChannelCredential: gRPC 채널 사용자 인증 정보입니다.
- [CONNECTION] unaryMiddlewares: 단항 미들웨어입니다.
- [CONNECTION] streamingMiddlewares: 스트리밍 미들웨어입니다.
- [CONNECTION] grpcInterceptors: gRPC 인터셉터입니다.

구성 검증

구성 설정은 클라이언트를 인스턴스화할 때 확인되며, 유효하지 않으면 예외가 발생합니다. 유효성 검사 규칙은 다음과 같습니다.

[OAUTH2] 필드는 애플리케이션 모드와 서비스 계정 모드에 동시에 설정하면 안 됩니다.
서비스 계정 모드를 사용하는 경우 [OAUTH2] jsonKeyFilePath를 설정해야 합니다 (v32.1.0 이전 버전에서는 [OAUTH2] scopes도 설정해야 함. v32.1.0 이상에서는 scopes가 기본적으로 https://www.googleapis.com/auth/adwords로 설정됨).
애플리케이션 모드를 사용하는 경우 [OAUTH2] clientId, [OAUTH2] clientSecret, [OAUTH2] refreshToken를 설정해야 합니다.
v35.0.0 이전 버전에서는 [GOOGLE_ADS] developerToken이 로컬 클라이언트 측 유효성 검사에 의해 확인됩니다 (v35.0.0 이상에서는 [GOOGLE_ADS] developerToken이 필요하지 않음).
설정된 경우 [GOOGLE_ADS] loginCustomerId 및 [GOOGLE_ADS] linkedCustomerId은 양수여야 합니다.
설정된 경우 [CONNECTION] proxy은 유효한 URL이어야 합니다 (FILTER_VALIDATE_URL 필터 참고).
설정된 경우 [LOGGING] logLevel는 대문자로 된 유효한 PSR 로그 수준(예: INFO)이어야 합니다.
설정된 경우 [CONNECTION] transport은 grpc 또는 rest여야 합니다.
[CONNECTION] transport이 grpc로 설정된 경우 gRPC 전송이 환경에서 지원되어야 합니다 (전송 가이드 참고).
[CONNECTION] transport이 grpc로 설정되지 않은 경우 [CONNECTION] grpcChannelIsSecure은 true이어야 합니다 (REST 연결에는 항상 HTTPS가 필요함).
[CONNECTION] grpcChannelCredential는 [CONNECTION] transport이 grpc로 설정된 경우에만 설정할 수 있습니다.
[CONNECTION] grpcChannelCredential는 [CONNECTION] grpcChannelIsSecure이 true인 경우에만 설정할 수 있습니다.