Utilisation avancée

Ce guide explique comment personnaliser plusieurs aspects les plus avancés de la bibliothèque cliente Java. Il est courant qu'un grand nombre de ces fonctionnalités s'appuient sur le Callable sous-jacent plutôt que sur les méthodes standards. L'appelable est généralement un bon endroit pour rechercher d'autres fonctionnalités par RPC qui ne sont pas décrites ici.

Délai avant expiration

La bibliothèque Java fournit une surface pour définir les 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 sur 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 des 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 fragments en parallèle. Cela permet d'éviter l'échec d'une requête de longue durée, et la seule façon de récupérer est de déclencher à nouveau la requête depuis le début.

Paramètres des nouvelles tentatives

La bibliothèque Java fournit également une surface pour 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 seront 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 en même temps afin de fournir un mécanisme plus pratique pour créer des classes de service.

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

1. Créez le GoogleAdsClient au démarrage, avant de diffuser 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 (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. Toute création ultérieure de client de service réutilisera 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.getVersionXXX().createYYYServiceClient() crée une nouvelle connexion TCP.

Veillez à fermer le client lorsqu'il n'est plus nécessaire. Pour ce faire, vous pouvez utiliser un bloc try-with-resources ou appeler 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 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 par fichier importé. Le fichier JAR pour google-ads sera considérablement plus volumineux que cela, surtout si vous utilisez des déploiements de mise en miroir ombrée/shadow JAR. Si vous déployez manuellement vos fichiers JAR, vous risquez d'obtenir des messages d'erreur tels que:

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

Effectuez plutôt le déploiement à l'aide du plug-in App Engine Gradle ou du plug-in Maven. Chacun d'eux comporte une option pour enableJarSplitting, qui divisera chaque fichier JAR en fragments de 10 Mo et les importera à la place.

Dépendances fantômes

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

mvn dependency:tree

./gradlew dependencies

S'il vous est impossible de résoudre les conflits de dépendances, vous pouvez dépendre de la version shaded de la bibliothèque.

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

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