Utilisation avancée

Ce guide explique comment personnaliser plusieurs aspects plus avancés de la bibliothèque cliente Java. De nombreuses fonctionnalités reposent sur l'élément Callable sous-jacent plutôt que sur les méthodes pratiques standards. L'élément callable est généralement un bon point de départ pour rechercher d'autres fonctionnalités par RPC qui ne sont pas documentées ici.

Délai avant expiration

La bibliothèque Java fournit une interface permettant de définir des délais avant expiration au niveau de chaque appel. La valeur par défaut est définie en fonction du param0/}ètre dans googleads_grpc_service_config.json.method_config/timeout Définissez une valeur inférieure si vous devez appliquer une limite plus courte à la durée maximale d'un appel d'API.

Pour utiliser cette fonctionnalité, appelez directement l'objet Callable. Par exemple, lorsque vous appelez GoogleAdsService.searchStream(), définissez le délai avant expiration comme suit :

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery("SELECT campaign.id, campaign.name FROM campaign")
          .build();

  // Executes the API call with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient
          .searchStreamCallable()
          .call(
              request,
              GrpcCallContext.createDefault()
                  .withTimeout(Duration.of(5, ChronoUnit.MINUTES)));
  for (SearchGoogleAdsStreamResponse response : stream) {
    // Processes the response rows.
  }
}

Vous pouvez définir le délai avant expiration sur deux heures ou plus, mais l'API peut toujours expirer les requêtes très longues et renvoyer une DEADLINE_EXCEEDED erreur. Si cela devient un problème, il est généralement préférable de diviser la requête et d'exécuter les blocs en parallèle. Cela évite qu'une requête longue échoue et que la seule façon de la récupérer soit de la déclencher à nouveau depuis le début.

Paramètres de nouvelle tentative

La bibliothèque Java fournit également une interface permettant de configurer les paramètres de nouvelle tentative au niveau de chaque appel. Pour utiliser cette fonctionnalité, appelez directement l'objet Callable. Par exemple, lorsque vous appelez GoogleAdsService.searchStream(), configurez les paramètres de nouvelle tentative comme suit :

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery("SELECT campaign.id, campaign.name FROM campaign")
          .build();

  // 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());

  // Issues the streaming search request.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient.searchStreamCallable().call(request, context);
  for (SearchGoogleAdsStreamResponse response : stream) {
    // Processes the response rows.
  }
}

Optimisation des performances au démarrage

Vous remarquerez peut-être un léger délai la première fois qu'une instance GoogleAdsClient est créée. Cela est dû à l'interface fluide pour les services (GoogleAdsClient.getLatestVersion()), qui charge les classes de service API en une seule fois pour fournir un mécanisme pratique de création de clients de service.

Si les performances de la première requête sont essentielles pour votre application, procédez comme suit :

  1. Créez le GoogleAdsClient au démarrage, avant de traiter les requêtes des utilisateurs.

  2. Envoyez quelques requêtes de préchauffage à l'API Google Ads lorsque le processus démarre. Exemple :

    // 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 (ApiException ex) {
      // Do nothing, we're expecting this to fail.
    }
  }
}

Les requêtes de préchauffage ne doivent être exécutées qu'une seule fois par processus. Chaque création de client de service ultérieure réutilise automatiquement les classes préchargées.

Réutilisation du client de service

Vous devez réutiliser les instances de client de service lorsque cela est possible, car chaque appel à GoogleAdsClient.getLatestVersion().createYYYServiceClient() (ou à un accesseur spécifique à une version, tel que getVersion26()) crée une nouvelle connexion sous-jacente et les ressources associées.

Assurez-vous de fermer le client de service lorsqu'il n'est plus nécessaire. Vous pouvez le faire dans un bloc try-with-resources ou en appelant close() sur le client de service.

Si vous tentez d'utiliser un client de service fermé pour effectuer des requêtes API, la méthode du client de service génère une java.util.concurrent.RejectedExecutionException.

Échec du déploiement d'App Engine si le fichier JAR est supérieur à 32 Mo

App Engine dispose d'un quota de 32 Mo pour chaque fichier importé. Le fichier JAR de google-ads est beaucoup plus volumineux, en particulier lorsque vous utilisez des déploiements de fichiers JAR shade ou shadow. Si vous déployez des fichiers JAR manuellement, vous pouvez recevoir des erreurs telles que :

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

À la place, effectuez le déploiement à l'aide du plug-in Gradle d'App Engine ou Maven. Chaque plug-in fournit une option enableJarSplitting qui divise chaque fichier JAR en blocs de 10 Mo et les importe à la place.

Dépendances shadow

Si votre projet comporte des dépendances qui entrent en conflit avec celles de la bibliothèque, inspectez la hiérarchie des dépendances de votre projet à l'aide de l'une des commandes suivantes, puis modifiez les dépendances de votre projet si nécessaire (ou utilisez la nomenclature des composants) :

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Si la résolution des conflits de dépendances n'est pas possible, vous pouvez dépendre de la version ombrée de la bibliothèque :

Maven

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

Gradle

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