구성

경고: 버전 19.0.0부터 .NET용 Google Ads API 클라이언트 라이브러리는 더 이상 .NET 5.0을 지원하지 않습니다. 원활한 작동을 위해 2024년 말 이전에 .NET 버전을 업그레이드하는 것이 좋습니다.

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

런타임에 라이브러리 구성

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

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

GoogleAdsClient client = new GoogleAdsClient(config);

대체 구성 옵션

클라이언트 라이브러리를 구성하는 몇 가지 추가 옵션도 제공됩니다. 이러한 옵션을 사용 설정하려면 프로젝트의 Google.Ads.GoogleAds.Extensions 패키지에 Nuget 참조를 추가하세요.

이러한 옵션 중 하나를 사용하면 구성 설정이 자동으로 선택되지 않습니다. 아래와 같이 명시적으로 로드해야 합니다.

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=""/>

    <!-- API-specific settings -->
    <add key="DeveloperToken" value="******"/>

    <!-- OAuth2 settings -->
    <add key = "OAuth2Mode" value="APPLICATION"/>
    <add key = "OAuth2ClientId" value = "******.apps.googleusercontent.com" />
    <add key = "OAuth2ClientSecret" value = "******" />
    <add key = "OAuth2RefreshToken" value = "******" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.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에서 지정한 이름으로 다른 구성 파일을 만들고 구성 노드를 App.config에서 이 파일로 이동합니다.

<?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": "",

    "DeveloperToken": "******",

    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "******.apps.googleusercontent.com",
    "OAuth2ClientSecret": "******",
    "OAuth2RefreshToken": "******",
}

구성 로드

그런 다음 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을 사용한 구성

여기서 프로세스는 키가 GoogleAdsApi라는 섹션에 있어야 한다는 점을 제외하고 맞춤 JSON을 사용하는 것과 유사합니다.

{
    "GoogleAdsApi":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

다음으로 페이지에서 IConfiguration 인스턴스를 사용할 수 있습니다.

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

환경 변수를 사용한 구성

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

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
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입니다.

특정 ResourceExhausted 오류를 수정하려면 MaxReceiveMessageLengthInBytes 및 MaxMetadataSizeInBytes 설정을 조정합니다. 이 설정은 Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)" 형식의 오류를 해결합니다.

이 예에서 오류는 메시지 크기 (423184132 bytes)가 라이브러리가 처리할 수 있는 크기 (67108864 bytes)보다 크기 때문에 발생합니다. 이 오류를 방지하려면 MaxReceiveMessageLengthInBytes를 500000000로 늘리세요.

이 오류는 코드가 매우 큰 Response 객체 (예: 큰 SearchGoogleAdsResponse)를 처리했음을 나타냅니다. 이는 .NET의 대형 객체 힙으로 인해 코드의 성능에 영향을 미칠 수 있습니다. 이로 인해 성능 문제가 발생하면 API 호출을 재구성하거나 앱의 일부를 다시 설계하는 방법을 살펴봐야 할 수 있습니다.

OAuth2 설정

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

• AuthorizationMethod: OAuth2로 설정합니다.
• OAuth2Mode: APPLICATION 또는 SERVICE_ACCOUNT로 설정합니다.
• OAuth2ClientId: 이 값을 OAuth2 클라이언트 ID로 설정합니다.
• OAuth2ClientSecret: 이 값을 OAuth2 클라이언트 보안 비밀로 설정합니다.
• OAuth2Scope: 여러 API에 대해 OAuth2 토큰을 승인하려면 이 값을 다른 범위로 설정하세요. 이 설정은 선택사항입니다.

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

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

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

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

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

• OAuth2PrnEmail: 이 값을 명의 도용하려는 계정의 이메일 주소로 설정합니다.
• OAuth2SecretsJsonPath: 이 값을 OAuth2 JSON 구성 파일 경로로 설정합니다.

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

운송 설정

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

Google Ads API 설정

다음 설정은 Google Ads API에만 적용됩니다.

• DeveloperToken: 개발자 토큰으로 설정합니다.
• LoginCustomerId: 요청에 사용할 승인된 고객의 고객 ID입니다(하이픈(-) 제외).
• LinkedCustomerId: 이 헤더는 Google Ads UI (Google Ads API의 AccountLink 리소스)에서 연결된 계정을 통해 권한이 부여된 경우 항목의 리소스를 업데이트하는 메서드에만 필요합니다. 이 값을 지정된 고객 ID의 리소스를 업데이트하는 데이터 제공업체의 고객 ID로 설정합니다. 하이픈 없이 설정해야 합니다 (-). 연결된 계정에 대해 자세히 알아보기