Générer des bibliothèques clientes avec Bazelisk (Automotive)

Les bibliothèques clientes sont des interfaces spécifiques à un langage pour une API. Ce document explique comment utiliser Bazelisk, un lanceur d'applications pour Bazel, afin de générer des bibliothèques clientes pour l'API Routes pour Automotive dans différents langages de programmation. Bazelisk s'assure que la bonne version de Bazel est utilisée pour exécuter les commandes de compilation.

Le code nécessaire pour générer les bibliothèques est hébergé dans un dépôt Gerrit privé. Pour en savoir plus sur le fonctionnement des bibliothèques clientes, consultez la section Présentation des bibliothèques clientes.

Prérequis

Logiciels requis

Installez les éléments suivants:

Conditions d'autorisation

  • L'accès au référentiel est accordé aux membres d'un groupe <partner>@google.com spécifique géré par un représentant de votre entreprise. Pour être ajouté à ce groupe, adressez-vous au contact de votre entreprise ou au partenaire commercial Google.

Étape 1: Accédez à Gerrit

Pour accéder à Gerrit :
  1. Assurez-vous d'avoir rempli les conditions d'autorisation requises pour le dépôt, répertoriées dans la section Prérequis.
  2. Créez un compte Google avec une adresse e-mail professionnelle en suivant les instructions de la section Créer un compte Google.
    • Lorsque vous créez un compte Google, vérifiez que vous n'êtes pas connecté à gmail.com ou à un autre compte de services du domaine Google avant de accéder à la page de connexion au compte Google. Pour garantir l'intégrité du profil, fermez et redémarrez votre navigateur, puis ouvrez une fenêtre de navigation privée.
    • Lorsque vous demandez l'accès pour d'autres personnes, créez un compte pour chaque personne qui en a besoin. Envoyez ensuite la liste des nouveaux comptes Google à votre partenaire commercial Google. Votre partenaire commercial ajoutera les adresses e-mail aux groupes d'accès appropriés.
  3. À l'aide du compte Google que vous venez de créer, accédez à https://partner-code.googlesource.com. Lorsque vous accédez à l'hôte Gerrit, un utilisateur est créé et connecté automatiquement pour vous.
  4. Sur la page https://partner-code.googlesource.com, cliquez sur Générer un mot de passe. Suivez les instructions à l'écran pour sélectionner votre compte Google, autoriser l'accès à googlesource.com et suivre les autres instructions à l'écran.
  5. Lorsque vous voyez un script, copiez-le et collez-le dans votre terminal.

Étape 2: Clonez les dépôts

Au cours de cette étape, vous allez cloner les dépôts googleapis et routes-auto-early-access.

  1. Clonez le dépôt routes-auto-early-access : 
    git clone https://partner-code.googlesource.com/routes-auto-early-access
  2. Clonez le dépôt googleapis public de Google : 
    git clone https://github.com/googleapis/googleapis.git

Étape 3: Fusionner les dépôts

Au cours de cette étape, vous allez déplacer le sous-répertoire routes-auto-early-access/google/maps/routing/v2 vers googleapis/google/maps/routing/v2.

  1. Après avoir cloné les dépôts, assurez-vous que votre répertoire de travail actuel (pwd) inclut les sous-répertoires routes-auto-early-access et googleapis. 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. Créez un répertoire routing/v2 à l'emplacement cible et copiez routing/v2 dans googleapis/google/maps/routing/v2 : 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

Pour vérifier que le répertoire routing/v2 a bien été fusionné avec le répertoire googleapis/google/maps/routing/v2, accédez à googleapis/google/maps/routing/v2. Le dossier doit contenir des fichiers proto, un fichier BUILD.bazel et les autres fichiers nécessaires à la compilation.

Étape 4: Créez une bibliothèque cliente à l'aide de Bazelisk

Pour compiler la bibliothèque cliente pour un langage particulier, identifiez la cible de compilation pour ce langage dans le fichier BUILD.bazel (dans googleapis/google/maps/routing/v2/BUILD.bazel), puis compilez cette cible. Vous trouverez la cible name dans les objets <LANGUAGE>_gapic_assembly_pkg. Pour en savoir plus, consultez la section Créer une cible dans la documentation de Bazel.

Par exemple, pour créer la bibliothèque cliente Java, procédez comme suit:

  1. Accédez au répertoire googleapis : 
    cd googleapis
  2. Exécutez la commande suivante : 
    bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java

    Cette commande génère la bibliothèque cliente Java à l'emplacement googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

Pour plus de commodité, le tableau suivant répertorie les commandes de compilation pour chaque langage disponible.

Langue Commande de compilation Bazelisk
Java bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java
Go bazelisk build google/maps/routing/v2:gapi-cloud-maps-routing-v2-go
PHP bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-php
Ruby bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-ruby
C# bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-csharp
Nœud bazelisk build google/maps/routing/v2:maps-routing-v2-nodejs

Intégrer les mises à jour lorsqu'une nouvelle version est disponible

Lorsque l'API comporte de nouvelles versions, vous devez recompiler les bibliothèques clientes. Si vous avez déjà cloné les dépôts en suivant les instructions des sections précédentes, procédez comme suit pour les nouvelles versions:

  1. Accédez au répertoire de travail actuel qui contient les deux dépôts : 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. Supprimez l'instance précédente de routing/v2 dans googleapis/google/maps : 
    rm -rf googleapis/google/maps/routing/v2
  3. Accédez aux dépôts routes-auto-early-access et googleapis, puis exécutez git pull pour obtenir les dernières mises à jour.
  4. Copiez routing/v2 dans googleapis/google/maps/routing/v2, comme précédemment : 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

    Pour vérifier que le dépôt routing/v2 a bien été fusionné avec le répertoire googleapis/google/maps/routing/v2, accédez à googleapis/google/maps/routing/v2. Le dossier doit contenir des fichiers proto, un fichier BUILD.bazel et les autres fichiers nécessaires au build Bazel.

  5. Exécutez les commandes de compilation Bazelisk répertoriées dans la section précédente Étape 4: Créez une bibliothèque cliente à l'aide de Bazelisk.

Générer des Javadocs pour la bibliothèque cliente Java

La bibliothèque cliente vous permet d'appeler l'API Routes pour Automotive à l'aide des classes et des méthodes propres au langage. Malheureusement, le résultat n'inclut pas la documentation Javadoc pour la bibliothèque cliente. Cette section explique comment générer le fichier Javadoc pour la bibliothèque cliente Java.

Prérequis

Pour compiler le Javadoc:

  1. Assurez-vous que des versions compatibles de Gradle (8.0 ou ultérieure) et de JDK (17 ou version antérieure) sont installées. Vous pouvez vérifier les versions installées en exécutant ./gradlew --version et java -version dans votre terminal.

  2. La bibliothèque cliente Java est basée sur le fichier tar.gz suivant, que vous devrez extraire: googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

    En supposant que vous vous trouvez dans le répertoire googleapis, exécutez la commande suivante en remplaçant /PATH/TO/PARENT/DIRECTORY par le chemin d'accès que vous avez choisi pour la bibliothèque extraite:

    mkdir -p /PATH/TO/PARENT/DIRECTORY && tar -xzpf bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz -C /PATH/TO/PARENT/DIRECTORY

  3. Accédez au répertoire parent :

    cd /PATH/TO/PARENT/DIRECTORY

  4. Dans le répertoire google-cloud-maps-routing-v2-java, ouvrez les fichiers build.gradle dans chacun des répertoires suivants:

    • gapic-google-cloud-maps-routing-v2-java/build.gradle
    • grpc-google-cloud-maps-routing-v2-java/build.gradle
    • proto-google-cloud-maps-routing-v2-java/build.gradle

    Assurez-vous que chacune d'entre elles contient les tâches suivantes. En raison d'un bug, remplacez les deux tâches et artefacts similaires existants par ce code:

    
task javadocJar(type: Jar, dependsOn: javadoc) {
  archiveClassifier.set('javadoc')
  from javadoc.destinationDir
}

task sourcesJar(type: Jar) {
  archiveClassifier.set('sources')
  from sourceSets.main.allSource
}

artifacts {
archives javadocJar
}

  5. Vérifiez que vous utilisez Gradle 8.0 ou une version ultérieure: ./gradlew --version. Si vous utilisez la version 7, procédez comme suit: à partir du répertoire google-cloud-maps-routing-v2-java, supprimez les fichiers gradlew et gradlew.bat. Exécutez ensuite gradle wrapper --gradle-version=8.0 pour passer à la version 8.0.

  6. À partir du répertoire google-cloud-maps-routing-v2-java, utilisez Gradle pour créer les Javadocs:

    ./gradlew build

    Le Javadoc généré apparaît dans les répertoires suivants:

    • google-cloud-maps-routing-v2-java/gapic-google-cloud-maps-routing-v2-java/build/docs/javadoc
    • google-cloud-maps-routing-v2-java/grpc-google-cloud-maps-routing-v2-java/build/docs/javadoc
    • google-cloud-maps-routing-v2-java/proto-google-cloud-maps-routing-v2-java/build/docs/javadoc

  7. Ouvrez le fichier overview-tree.html de chaque répertoire dans un navigateur Web.