고급 사용법

이 가이드에서는 Java 클라이언트 라이브러리의 고급 기능을 맞춤설정하는 방법을 설명합니다. 일반적인 패턴은 이러한 기능 중 다수가 표준 메서드가 아닌 기본 Callable를 사용하는 것입니다. 일반적으로 호출 가능 함수는 여기에 설명되지 않은 다른 RPC별 기능을 찾기에 좋은 위치입니다.

시간 초과

Java 라이브러리는 호출별 수준에서 제한 시간을 설정하기 위한 노출 영역을 제공합니다. 기본값은 googleads_grpc_service_config.json의 method_config/timeout 설정에 따라 설정됩니다. API 호출의 최대 시간에 더 짧은 제한을 적용해야 하는 경우 더 낮은 값을 설정합니다.

이 기능을 사용하려면 호출 가능 객체를 직접 사용해야 합니다. 예를 들어 GoogleAdsService.searchStream()를 호출하는 경우 제한 시간은 다음과 같이 설정됩니다.

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request = ...

  // Executes the API call, with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> result = googleAdsServiceClient
      .searchStreamCallable()
      .call(request,
          GrpcCallContext.createDefault().withTimeout(Duration.of(5, ChronoUnit.MINUTES)));
}

제한 시간을 2시간 이상으로 설정할 수 있지만 API가 여전히 매우 오래 실행되는 요청을 타임아웃하고 DEADLINE_EXCEEDED 오류를 반환할 수 있습니다. 이것이 문제가 되면 일반적으로 쿼리를 분할하고 청크를 동시에 실행하는 것이 가장 좋습니다. 이렇게 하면 장기 실행 요청이 실패하는 상황을 피할 수 있으며 복구 방법은 처음부터 다시 요청을 트리거하는 것입니다.

재시도 설정

Java 라이브러리는 호출별 수준에서 재시도 설정을 구성하기 위한 노출 영역도 제공합니다. 이 기능을 사용하려면 호출 가능 객체를 직접 사용해야 합니다. 예를 들어 GoogleAdsService.searchStream()를 호출하면 재시도 설정은 다음과 같이 구성됩니다.

// Creates a context object with the custom retry settings.
GrpcCallContext context = GrpcCallContext.createDefault()
    .withRetrySettings(RetrySettings.newBuilder()
    .setInitialRetryDelay(Duration.ofMillis(10L))
    .setMaxRetryDelay(Duration.ofSeconds(10L))
    .setRetryDelayMultiplier(1.4)
    .setMaxAttempts(10)
    .setLogicalTimeout(Duration.ofSeconds(30L))
    .build());

// Creates and issues a search Google Ads stream request.
ServerStream<SearchGoogleAdsStreamResponse> stream =
    googleAdsServiceClient.searchStreamCallable().call(request, context);

시작 시간 성능 최적화

GoogleAdsClient 인스턴스를 처음 만들 때 약간의 지연이 발생할 수 있습니다. 이는 서비스의 유연한 인터페이스(GoogleAdsClient.getVersionXX()) 때문입니다. 이 인터페이스는 서비스 클래스를 구성하는 데 더 편리한 메커니즘을 제공하기 위해 모든 API 클래스를 한 번에 로드합니다.

첫 번째 요청 성능이 애플리케이션의 중요한 경로에 있는 경우 다음 단계를 따라야 합니다.

1. 시작 시 사용자 요청을 처리하기 전에 GoogleAdsClient를 만듭니다.

2. 프로세스가 처음 시작될 때 Google Ads API에 몇 가지 준비 요청을 보냅니다. 예를 들면 다음과 같습니다.

   // Runs some warm-up requests.
   try (GoogleAdsServiceClient googleAdsServiceClient =
       googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
     // Runs 5 warm-up requests. In our profiling we see that 90% of performance
     // loss is only experienced on the first API call. After 3 subsequent calls we
     // saw a negligible improvement in performance.
     for (int i = 0; i < 5;   i) {
       // Warm-up queries are run with a nonexistent CID so the calls will fail. If
       // you have a CID that you know will be accessible with the OAuth
       // credentials provided you may want to provide that instead and avoid the
       // try-catch.
       try {
         googleAdsServiceClient.search("-1", "Warm-up query");
       } catch (GoogleAdsException ex) {
         // Do nothing, we're expecting this to fail.
       }
     }
   }
   

준비 요청은 프로세스당 한 번만 실행하면 됩니다. 이후의 모든 서비스 클라이언트 생성은 미리 로드된 클래스를 자동으로 재사용합니다.

서비스 클라이언트 재사용

GoogleAdsClient.getVersionXXX().createYYYServiceClient()를 호출할 때마다 새 TCP 연결이 생성되므로 실용적인 서비스 클라이언트 인스턴스를 재사용해야 합니다.

더 이상 필요하지 않은 클라이언트는 종료해야 합니다. try-with-resources 블록에서 또는 서비스 클라이언트에서 close()를 호출하여 이 작업을 실행할 수 있습니다.

폐쇄형 서비스 클라이언트를 사용하여 API 요청을 하려고 하면 서비스 클라이언트 메서드에서 java.util.concurrent.RejectedExecutionException이 발생합니다.

JAR가 32MB를 초과하면 App Engine이 배포되지 않음

App Engine에는 업로드된 파일마다 32MB의 할당량이 있습니다. google-ads의 JAR은 이보다 훨씬 큽니다. 셰이드/섀도우 jar 배포를 사용하면 훨씬 더 커집니다. jar을 수동으로 배포하면 다음과 같은 오류가 발생할 수 있습니다.

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-14.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

대신 AppEngine Gradle 플러그인 또는 Maven 플러그인을 사용하여 배포하세요. 각각에는 각 jar을 10MB 청크로 분할하여 업로드하는 enableJarSplitting 옵션이 있습니다.

섀도 종속 항목

프로젝트에 라이브러리와 충돌하는 종속 항목이 있는 경우 다음 명령어 중 하나를 사용하여 프로젝트의 종속 항목을 검사한 후 필요에 따라 프로젝트의 종속 항목을 수정해야 합니다.

mvn dependency:tree

./gradlew dependencies

종속 항목 충돌을 해결할 수 없다면 대신 shaded 버전의 라이브러리를 사용할 수 있습니다.

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads-shadowjar</artifactId>
  <version>31.0.0</version>
</dependency>

implementation 'com.google.api-ads:google-ads-shadowjar:31.0.0'