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 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 fournit une surface permettant 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é, vous devez utiliser directement l'objet appelable. Par exemple, si vous appelez GoogleAdsService.searchStream(), le délai avant expiration est défini comme suit :

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)));
}

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 qu'une requête de longue durée é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 réessai

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é, vous devez utiliser directement l'objet appelable. Par exemple, si vous appelez GoogleAdsService.searchStream(), les paramètres de nouvelle tentative sont configurés comme suit :

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

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.getVersionXX()), qui charge toutes les classes d'API à la fois afin de fournir un mécanisme plus pratique pour construire des classes de service.

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

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

  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 (GoogleAdsException 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éutilisera 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.getVersionXXX().createYYYServiceClient() créera une nouvelle connexion TCP.

Vous devez vous assurer de fermer le client lorsqu'il n'est plus nécessaire. Cela peut être fait 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érera 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 pour google-ads sera considérablement plus volumineux, et encore plus si vous utilisez des déploiements de fichiers JAR ombrés/fantômes. Si vous déployez des fichiers JAR manuellement, vous pouvez obtenir des erreurs telles que :

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

Dépendances des ombres

Si votre projet comporte des dépendances qui entrent en conflit avec celles de la bibliothèque, vous devez inspecter les dépendances de votre projet à l'aide de l'une des commandes suivantes, puis modifier les dépendances de votre projet si nécessaire.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

Si la résolution des conflits de dépendances est impossible, vous pouvez à la place 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>38.0.0</version>
</dependency>

Gradle

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