Utilisation avancée

Ce guide explique comment personnaliser plusieurs des aspects les plus avancés de la bibliothèque cliente Java. De nombreuses fonctionnalités reposent 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 avant expiration 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 les requêtes extrêmement longues 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 segments en parallèle. Cela évite que la requête de longue durée échoue et que le seul moyen 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 surface 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 au démarrage

Vous remarquerez peut-être un léger retard 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 en même temps afin de fournir un mécanisme plus pratique pour la création de classes de services.

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 le GoogleAdsClient au démarrage, avant de répondre aux requêtes 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 (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 de client de service ultérieure réutilisera automatiquement les classes préchargées.

Réutilisation du client de service

Dans la mesure du possible, vous devez réutiliser les instances de client de service, car chaque appel à GoogleAdsClient.getVersionXXX().createYYYServiceClient() crée une nouvelle connexion TCP.

Vous devez vous assurer de fermer le client 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 essayez d'utiliser un client de service fermé pour envoyer des requêtes d'API, la méthode du client de service génère une exception java.util.concurrent.RejectedExecutionException.

Le déploiement d'App Engine échoue 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, encore plus en utilisant des déploiements de fichiers JAR ombrés/ombre. 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-37.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

Déployez plutôt à l'aide du plug-in Gradle ou du plug-in Maven App Engine. Chacune d'elles comporte une option pour enableJarSplitting, qui divise chaque fichier JAR en segments de 10 Mo et les importe à la place.

Dépendances d'ombre

Si votre projet comporte des dépendances 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 n'est pas possible, vous pouvez dépendre de la version ombre de la bibliothèque.

Maven

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

Gradle

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