고급 사용법

이 가이드에서는 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 인스턴스가 처음 생성될 때 약간의 지연이 발생할 수 있습니다. 이는 서비스 클래스를 구성하는 더 편리한 메커니즘을 제공하기 위해 모든 API 클래스를 한 번에 로드하는 서비스용 유창한 인터페이스(GoogleAdsClient.getVersionXX()) 때문입니다.

첫 번째 요청 실적이 애플리케이션의 중요 경로에 있는 경우 다음 단계를 따르세요.

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은 훨씬 더 커지며, Shade/Shadow JAR 배포를 사용하면 더 커집니다. 수동으로 jar를 배포하면 다음과 같은 오류가 발생할 수 있습니다.

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

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

쉐도우 종속 항목

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

종속 항목 충돌을 해결할 수 없는 경우 대신 라이브러리의 쉐이딩된 버전에 종속할 수 있습니다.

Maven

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

Gradle

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