구성

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

런타임에 라이브러리 구성

클라이언트 라이브러리를 구성하는 기본 방법은 런타임에 GoogleAdsConfig 객체를 초기화하는 것입니다.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN"
};

GoogleAdsClient client = new GoogleAdsClient(config);

대체 구성 옵션

이 라이브러리는 구성 설정을 로드하는 추가 옵션도 제공합니다. 이를 사용 설정하려면 프로젝트에서 Google.Ads.GoogleAds.Extensions 패키지에 NuGet 참조를 추가하세요.

이러한 옵션 중 하나를 사용하는 경우 구성 설정이 자동으로 선택되지 않습니다. 다음 섹션에 표시된 대로 명시적으로 로드해야 합니다. 외부 파일이나 스트림에서 설정을 로드할 때 파일 I/O 예외 (예: FileNotFoundException 또는 UnauthorizedAccessException)를 처리해야 합니다.

App.config 사용

Google Ads API와 관련된 모든 설정은 App.config 파일의 GoogleAdsApi 노드에 저장됩니다. 일반적인 구성 App.config은 다음과 같습니다.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888" />
    <add key="ProxyUser" value="" />
    <add key="ProxyPassword" value="" />
    <add key="ProxyDomain" value="" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

App.config 파일에서 구성 설정을 로드하려면 GoogleAdsConfig 객체에서 LoadFromDefaultAppConfigSection 메서드를 호출합니다.

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

별도의 App.config 파일 지정

App.config이 복잡해지는 것을 원하지 않는 경우 configSource 속성을 사용하여 라이브러리별 구성을 자체 구성 파일로 이동할 수 있습니다.

1. App.config에서 configSource을 지정합니다. 외부 구성 파일을 참조하도록 App.config를 수정합니다.

   <?xml version="1.0" encoding="utf-8" ?>
   <configuration>
     <configSections>
       <section name="GoogleAdsApi"
                type="System.Configuration.DictionarySectionHandler" />
     </configSections>
     <GoogleAdsApi configSource="GoogleAdsApi.config" />
   </configuration>
   

2. 구성 파일의 콘텐츠를 지정합니다. configSource (GoogleAdsApi.config)에 지정한 이름으로 다른 구성 파일을 만들고 App.config에서 GoogleAdsApi 구성 노드를 이 파일로 이동합니다.

   <?xml version="1.0" encoding="utf-8" ?>
   <GoogleAdsApi>
     <!-- More settings. -->
   </GoogleAdsApi>
   

3. .csproj에서 빌드 규칙을 업데이트합니다. 새 구성 파일을 프로젝트에 포함하고 출력 디렉터리로 복사 속성을 항상 복사로 설정합니다. 애플리케이션이 새 구성 파일에서 값을 가져오도록 프로젝트를 다시 빌드하고 실행합니다.

맞춤 JSON 파일 사용

IConfigurationRoot 인스턴스를 사용하여 클라이언트 라이브러리를 구성할 수 있습니다.

JSON 파일 만들기

App.config 파일과 유사한 구조를 갖는 GoogleAdsApi.json이라는 JSON 파일을 만듭니다.

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

구성 로드

그런 다음 JSON 파일을 IConfigurationRoot에 로드합니다.

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

settings.json 사용

여기서의 프로세스는 커스텀 JSON 파일을 사용하는 것과 유사하지만 키는 GoogleAdsApi이라는 섹션 내에 있어야 합니다.

{
  "GoogleAdsApi": {
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

그런 다음 애플리케이션의 IConfiguration 인스턴스에서 GoogleAdsApi 섹션을 추출합니다 (예: ASP.NET Core에 의해 삽입되거나 ConfigurationBuilder로 빌드됨).

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

또는 config.LoadFromSettingsJson(filePath, "GoogleAdsApi")을 사용하여 경로로 직접 settings.json 파일을 로드하거나 config.TryLoadFromEnvironmentFilePath을 사용하여 GOOGLE_ADS_CONFIGURATION_FILE_PATH 환경 변수(EnvironmentVariableNames.CONFIG_FILE_PATH)에서 로드할 수 있습니다.

환경 변수 사용

환경 변수를 사용하여 GoogleAdsClient를 초기화할 수도 있습니다.

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

지원되는 환경 변수의 전체 목록을 참고하세요.

일반 스트림 사용

암호화된 스트림을 포함한 일반 스트림에서 구성 또는 구성의 일부를 로드할 수도 있습니다.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // Set some configuration properties in code.
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

GoogleAdsClient client = new GoogleAdsClient(config);

구성 필드

다음 섹션에는 Google Ads .NET 라이브러리에서 지원하는 설정이 나열되어 있습니다.

연결 설정

• Timeout: 이 키를 사용하여 서비스 제한 시간을 밀리초 단위로 설정합니다. 기본값은 googleads_grpc_service_config.json의 method_config/timeout 설정에 따라 설정됩니다. API 호출의 최대 시간에 더 짧은 제한을 적용해야 하는 경우 더 낮은 값을 설정합니다. 제한 시간을 2시간 이상으로 설정할 수 있지만 API는 여전히 매우 오래 실행되는 요청의 제한 시간을 초과하고 DEADLINE_EXCEEDED 오류를 반환할 수 있습니다.
• ProxyServer: 인터넷에 연결하는 데 프록시를 사용하는 경우 HTTP 프록시 서버 URL로 설정합니다.
• ProxyUser: 프록시 서버에 대해 인증하는 데 필요한 사용자 이름으로 설정합니다. 사용자 이름이 필요하지 않은 경우 비워 둡니다.
• ProxyPassword: ProxyUser 값을 설정한 경우 ProxyUser의 비밀번호로 설정합니다.
• ProxyDomain: 프록시 서버에 설정이 필요한 경우 ProxyUser의 도메인으로 설정합니다.
• MaxReceiveMessageLengthInBytes: 클라이언트 라이브러리에서 처리할 수 있는 API 응답의 최대 크기를 늘리려면 이 설정을 사용하세요. 기본값은 64MB입니다.
• MaxMetadataSizeInBytes: 클라이언트 라이브러리에서 처리할 수 있는 API 오류 응답의 최대 크기를 늘리려면 이 설정을 사용하세요. 기본값은 16MB입니다.

MaxReceiveMessageLengthInBytes 및 MaxMetadataSizeInBytes 설정을 조정하여 특정 ResourceExhausted 오류를 수정합니다. 이러한 설정은 다음과 같은 형식의 오류를 해결합니다.

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

이 예에서는 메시지 크기 (423184132 bytes)가 라이브러리에서 처리할 수 있는 크기 (67108864 bytes)보다 커서 오류가 발생합니다. MaxReceiveMessageLengthInBytes를 500000000로 늘려 이 오류를 방지하세요. 이 오류는 코드가 매우 큰 응답 객체 (예: 큰 SearchGoogleAdsResponse)를 처리했음을 나타내기도 합니다. 이는 .NET의 대형 객체 힙으로 인해 코드의 성능에 영향을 미칠 수 있습니다. 이 문제가 성능 문제로 이어지면 API 호출을 재구성하거나 앱의 일부를 재설계하는 방법을 살펴봐야 할 수 있습니다.

OAuth2 설정

OAuth 2.0을 사용하여 Google Ads API 서버에 대한 호출을 승인하는 경우 다음 구성 키를 설정해야 합니다.

• AuthorizationMethod: OAuth2로 설정합니다.
• OAuth2Mode: APPLICATION 또는 SERVICE_ACCOUNT로 설정합니다.
• OAuth2ClientId: 이 값을 OAuth 2.0 클라이언트 ID로 설정합니다.
• OAuth2ClientSecret: 이 값을 OAuth 2.0 클라이언트 보안 비밀번호로 설정합니다.
• OAuth2Scope: 여러 API에 대해 OAuth 2.0 토큰을 승인하려면 이 값을 다른 범위로 설정합니다. 이 설정은 선택사항입니다.
• UseApplicationDefaultCredentials: 애플리케이션 기본 사용자 인증 정보를 사용하여 인증하려면 이 값을 true로 설정합니다 (Google.Ads.GoogleAds v24.1.0 이상에서 지원됨. config.LoadFromEnvironmentVariables()은 접두사가 없는 USE_APPLICATION_DEFAULT_CREDENTIALS 환경 변수를 읽음).
• Credentials: (런타임 전용, v27.0.0 이상에서 지원) 런타임에 미리 구성된 ICredential 또는 GoogleCredential 인스턴스를 GoogleAdsConfig에 직접 삽입합니다.

OAuth2Mode == APPLICATION을 사용하는 경우 다음 추가 구성 키를 설정해야 합니다.

• OAuth2RefreshToken: OAuth 2.0 토큰을 재사용하려면 이 값을 미리 생성된 OAuth 2.0 갱신 토큰으로 설정합니다. 이 설정은 선택사항입니다.
• OAuth2RedirectUri: 이 값을 OAuth 2.0 리디렉션 URL로 설정합니다. 이 설정은 선택사항입니다.

자세한 내용은 다음 가이드를 참고하세요.

• OAuth 데스크톱 애플리케이션 흐름
• OAuth 웹 애플리케이션 흐름

OAuth2Mode == SERVICE_ACCOUNT를 사용하는 경우 다음 추가 구성 키를 설정해야 합니다.

• OAuth2SecretsJsonPath: 이 값을 OAuth 2.0 JSON 키 파일의 경로로 설정합니다.
• OAuth2PrnEmail: Google Workspace 도메인 전체 위임을 사용할 때 가장하는 계정의 이메일 주소로 이 값을 설정합니다. 이 설정은 선택사항입니다.

자세한 내용은 OAuth 서비스 계정 흐름 가이드를 참고하세요.

운송 설정

• UseGrpcCore: Grpc.Core 라이브러리를 기본 전송 계층으로 사용하려면 이 설정을 true로 설정합니다. Grpc.Core 라이브러리 사용을 참고하세요.

Google Ads API 설정

다음 설정은 Google Ads API 전용입니다.

• DeveloperToken: v27.3.0 이상에서 선택사항(GOOGLE_ADS_DEVELOPER_TOKEN). 개발자 토큰은 2026년 9월 9일에 지원이 종료되었습니다. API 서버에서 액세스 수준은 클라이언트 라이브러리 버전과 관계없이 Google Cloud 프로젝트에 따라 결정되며 API 서버는 developer-token 헤더를 무시합니다 (향후 Google Ads API의 메이저 버전에서 거부될 때까지). 구성에서 DeveloperToken를 생략하거나 삭제하려면 로컬 클라이언트 측 DeveloperToken 유효성 검사를 삭제한 Google.Ads.GoogleAds v27.3.0 이상을 사용하세요 (이전 버전에서는 로컬 유효성 검사를 위해 비어 있지 않은 DeveloperToken가 필요함).
• LoginCustomerId: 요청에서 사용할 승인된 고객의 ID입니다 (하이픈 제외, -).
• LinkedCustomerId: 이 헤더는 Google Ads UI의 연결된 계정을 통해 권한이 부여된 경우 엔티티의 리소스를 업데이트하는 메서드에만 필요합니다 (Google Ads API의 AccountLink 리소스). 이 값을 지정된 고객 ID의 리소스를 업데이트하는 데이터 제공업체의 고객 ID로 설정합니다. 하이픈 없이 설정해야 합니다 (-). 연결된 계정에 대해 자세히 알아보기