Utilisation avancée

Ce guide explique comment personnaliser plusieurs des aspects les plus avancés de la bibliothèque cliente Java. Un modèle courant est que bon nombre de ces fonctionnalités s'appuient sur le Callable sous-jacent plutôt que sur les méthodes pratiques standards. L'objet appelable 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 par 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 pour 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 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 fragments en parallèle. Cela évite qu'une requête de longue durée échoue et que le seul moyen de récupérer soit de déclencher à nouveau la requête 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é, 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 lors de la première création d'une instance GoogleAdsClient. Cela est dû à l'interface fluide des services (GoogleAdsClient.getLatestVersion()), qui charge les classes de service d'API en une seule fois pour fournir un mécanisme pratique de construction des 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 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 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 de client de service ultérieure réutilise 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.getLatestVersion().createYYYServiceClient() (ou à un accesseur spécifique à une version, tel que getVersion26()) crée une connexion sous-jacente et des ressources associées.

Veillez à fermer le client de service 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 applique un quota de 32 Mo pour chaque fichier importé. Le fichier JAR pour google-ads est considérablement plus volumineux, en particulier lorsque vous utilisez des déploiements JAR shade ou shadow. 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-48.1.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

Déployez plutôt l'application à l'aide du plug-in Gradle ou du plug-in Maven d'App Engine. Chaque plug-in fournit une option enableJarSplitting qui divise chaque fichier JAR en fragments de 10 Mo et les importe à la place.

Dépendances fantômes

Si votre projet comporte des dépendances 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

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

Maven

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

Gradle

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