Generare librerie client con Bazelisk (Automotive)

Le librerie client sono interfacce specifiche del linguaggio per un'API. Questo documento descrive come utilizzare Bazelisk, un programma di avvio di Bazel, per generare librerie client per l'API Routes for Automotive in una varietà di linguaggi di programmazione. Bazelisk garantisce che venga utilizzata la versione corretta di Bazel per eseguire i comandi di build.

Il codice necessario per generare le librerie è ospitato in un repository Gerrit privato. Per una spiegazione del funzionamento delle librerie client, consulta la sezione Spiegazione delle librerie client.

Prerequisiti

Requisiti software

Installa quanto segue:

Requisiti relativi alle autorizzazioni

  • L'accesso al repository è fornito ai membri di un gruppo <partner>@google.com specifico, gestito da un rappresentante della tua azienda. Per essere aggiunto a questo gruppo, rivolgiti al punto di contatto della tua azienda o al partner commerciale di Google.

Passaggio 1: accedi a Gerrit

Per accedere a Gerrit:
  1. Assicurati di aver completato i requisiti di autorizzazione per i repository elencati nella sezione Prerequisiti.
  2. Crea un Account Google con un indirizzo email aziendale seguendo le istruzioni riportate in Creare un Account Google.
    • Quando crei un Account Google, assicurati di non aver eseguito l'accesso a gmail.com o a un altro account dei servizi del dominio Google prima di visitare la pagina di accesso dell'Account Google. Per assicurarti che il profilo sia pulito, chiudi e riavvia il browser e apri una finestra di navigazione in incognito (privata).
    • Quando richiedi l'accesso ad altri utenti, crea un account per ogni persona che deve accedere. Quindi, invia l'elenco dei nuovi Account Google al tuo partner commerciale Google. Il tuo partner commerciale aggiungerà gli indirizzi email ai gruppi di accesso appropriati.
  3. Utilizzando l'Account Google appena creato, vai alla pagina https://partner-code.googlesource.com. Quando accedi all'host Gerrit, viene creato un utente che esegue automaticamente l'accesso.
  4. In https://partner-code.googlesource.com, fai clic su Genera password. Segui le istruzioni sullo schermo per selezionare il tuo Account Google, consentire l'accesso a googlesource.com e seguire le altre istruzioni sullo schermo.
  5. Quando ti viene presentato uno script, copialo e incollalo nel terminale.

Passaggio 2: clona i repository

In questo passaggio clonerai i repository googleapis e routes-auto-early-access.

  1. Clona il repository routes-auto-early-access: 
    git clone https://partner-code.googlesource.com/routes-auto-early-access
  2. Clona il repository pubblico googleapis di Google: 
    git clone https://github.com/googleapis/googleapis.git

Passaggio 3: unisci i repository

In questo passaggio, sposterai la sottodirectory routes-auto-early-access/google/maps/routing/v2 in googleapis/google/maps/routing/v2.

  1. Dopo aver clonato i repository, assicurati che la tua directory di lavoro attuale (pwd) includa le sottodirectory routes-auto-early-access e googleapis. 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. Crea una directory routing/v2 nella posizione di destinazione e copia routing/v2 in 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"

Per confermare l'unione della directory routing/v2 alla directory googleapis/google/maps/routing/v2, vai a googleapis/google/maps/routing/v2. La cartella deve contenere i file proto, un file BUILD.bazel e gli altri file necessari per la build.

Passaggio 4: crea una libreria client utilizzando Bazelisk

Per creare la libreria client per una determinata lingua, identifica la destinazione della build per quella lingua nel file BUILD.bazel (in googleapis/google/maps/routing/v2/BUILD.bazel) e crea la destinazione. Puoi trovare la destinazione name all'interno degli oggetti <LANGUAGE>_gapic_assembly_pkg. Per ulteriori informazioni, consulta Creazione di un target nella documentazione di Bazel.

Ad esempio, per creare la libreria client Java, segui questi passaggi:

  1. Passa alla directory googleapis: 
    cd googleapis
  2. Esegui questo comando: 
    bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java

    Questo comando genera la libreria client Java all'indirizzo googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

Per praticità, la seguente tabella elenca i comandi di build per ogni lingua disponibile.

Lingua Comando di build 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
Nodo bazelisk build google/maps/routing/v2:maps-routing-v2-nodejs

Incorporare gli aggiornamenti quando ci sono nuove uscite

Quando sono disponibili nuove release dell'API, devi ricreare le librerie client. Supponendo che tu abbia già clonato i repository seguendo le istruzioni riportate nelle sezioni precedenti, procedi nel seguente modo per le nuove release:

  1. Passa all'attuale directory di lavoro che contiene entrambi i repository: 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. Rimuovi l'istanza precedente di routing/v2 all'interno di googleapis/google/maps: 
    rm -rf googleapis/google/maps/routing/v2
  3. Vai ai repository routes-auto-early-access e googleapis ed esegui git pull per ricevere gli aggiornamenti più recenti.
  4. Copia routing/v2 in googleapis/google/maps/routing/v2, simile a prima: 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

    Per confermare che il repository routing/v2 è stato unito correttamente alla directory googleapis/google/maps/routing/v2, vai a googleapis/google/maps/routing/v2. La cartella deve contenere i file proto, un file BUILD.bazel e gli altri file necessari per la build Bazel.

  5. Esegui i comandi di compilazione di Bazelisk elencati nella sezione precedente Passaggio 4: crea una libreria client utilizzando Bazelisk.

Generare Javadocs per la libreria client Java

La libreria client ti offre la possibilità di chiamare l'API Routes for Automotive utilizzando corsi e metodi specifici per la lingua. Sfortunatamente, l'output non include la documentazione Javadoc per la libreria client. Questa sezione spiega come generare Javadoc per la libreria client Java.

Prerequisiti

Per creare il Javadoc:

  1. Assicurati di avere installato versioni compatibili di Gradle (8.0 o versioni successive) e JDK (17 o versioni precedenti). Puoi controllare le versioni installate eseguendo ./gradlew --version e java -version nel terminale.

  2. La libreria client Java è stata creata nel seguente file tar.gz, che dovrai estrarre: googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

    Supponendo che ti trovi nella directory googleapis, esegui questo comando, sostituendo /PATH/TO/PARENT/DIRECTORY con il percorso che hai scelto per la libreria estratta:

    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. Vai alla directory padre:

    cd /PATH/TO/PARENT/DIRECTORY

  4. Dalla directory google-cloud-maps-routing-v2-java, apri i file build.gradle in ciascuna delle seguenti directory:

    • 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

    Assicurati che ciascuno contenga le attività riportate di seguito. A causa di un bug, sostituisci le due attività e gli artefatti simili esistenti con questo codice:

    
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. Verifica di utilizzare Gradle 8.0 o versioni successive: ./gradlew --version. Se la tua versione è la 7, procedi nel seguente modo: dalla directory google-cloud-maps-routing-v2-java, elimina i file gradlew e gradlew.bat. Quindi esegui gradle wrapper --gradle-version=8.0 per passare alla versione 8.0.

  6. Dalla directory google-cloud-maps-routing-v2-java, usa Gradle per creare i documenti Java:

    ./gradlew build

    Il Javadoc generato viene visualizzato in queste directory:

    • 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. Apri il file overview-tree.html di ogni directory utilizzando un browser web.