Utilisation avancée

Ce guide explique comment personnaliser plusieurs aspects avancés de la bibliothèque cliente Java. Un schéma courant est que la plupart de ces fonctionnalités s'appuient sur le Callable sous-jacent plutôt que sur les méthodes pratiques standards. Le callable est généralement un bon endroit pour rechercher d'autres fonctionnalités par RPC qui ne sont pas documentées ici.

Délai avant expiration

La bibliothèque Java permet de définir des délais d'attente au niveau de chaque appel. La valeur par défaut est définie en fonction du paramètre method_config/timeout dans googleads_grpc_service_config.json. 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 d'attente 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 pour les requêtes de très longue durée et renvoyer une erreur DEADLINE_EXCEEDED. 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 le cas où une requête de longue durée échoue et où la seule façon de la récupérer est de la déclencher à nouveau depuis le début.

Paramètres de réessai

La bibliothèque Java fournit également une interface permettant de configurer les paramètres de réessai 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 du temps de 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 d'API à la fois pour fournir un mécanisme pratique de création de clients de service.

Si les performances de la première requête se trouvent sur le chemin critique de votre application, procédez comme suit :

  1. Créez GoogleAdsClient au démarrage, avant de traiter les demandes des utilisateurs.

  2. Envoyez quelques requêtes d'échauffement à l'API Google Ads au début du processus. 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 ultérieure de client de service réutilise automatiquement les classes préchargées.

Réutilisation du service client

Dans la mesure du possible, réutilisez les instances de client de service, car chaque appel à GoogleAdsClient.getLatestVersion().createYYYServiceClient() (ou à un accesseur spécifique à une version, tel que getVersion25()) 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 d'API, la méthode du client de service génère une erreur 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 pour google-ads est beaucoup plus volumineux, en particulier lorsque vous utilisez des déploiements de fichiers JAR d'ombrage ou fantômes. Si vous déployez des fichiers JAR manuellement, vous pouvez rencontrer des erreurs telles que :

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-46.1.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 ou du plug-in Maven App Engine. Chaque plug-in fournit une option enableJarSplitting qui divise chaque fichier JAR en blocs de 10 Mo et les importe à la place.

Dépendances fantômes

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) :

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>46.1.0</version>
</dependency>

Gradle

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