使用 Bazelisk 生成客户端库 (Automotive)

客户端库是 API 特定于语言的接口。本文档介绍了如何使用 Bazelisk（一种适用于 Bazel 的启动器）以各种编程语言为 Routes API for Automotive 生成客户端库。Bazelisk 可确保在执行构建命令时使用正确版本的 Bazel。

生成库所需的代码托管在私有 Gerrit 代码库中。如需了解客户端库的工作原理，请参阅客户端库说明。

前提条件

软件要求

安装以下软件：

权限要求

  • 我们会向特定 <partner>@google.com 群组的成员提供该代码库的访问权限，该群组由贵公司的代表管理。要加入此群组，请与贵公司的联系人或 Google 业务合作伙伴联系。

第 1 步：访问 Gerrit

如需访问 Gerrit，请执行以下操作：
  1. 确保您已满足前提条件部分中列出的代码库权限要求。
  2. 按照创建 Google 帐号中的说明，使用公司电子邮件地址创建 Google 帐号。
    • 创建 Google 账号时，请确保您未登录 gmail.com 或其他 Google 网域服务账号，然后再访问 Google 账号登录页面。为确保个人资料简洁，请关闭并重启浏览器，然后打开无痕浏览窗口。
    • 为其他人申请访问权限时，请为需要访问权限的每个个人分别创建一个帐号。然后将新 Google 帐号列表发送给您的 Google 业务合作伙伴。 您的业务合作伙伴会将电子邮件地址添加到相应的访问权限群组。
  3. 使用您刚刚创建的 Google 账号，转到 https://partner-code.googlesource.com。当您访问 Gerrit 主机时，系统会为您创建一个用户并自动登录。
  4. 在 https://partner-code.googlesource.com 中，点击 Generate Password（生成密码）。按照屏幕上的提示选择您的 Google 账号，允许 googlesource.com 访问，然后按照屏幕上的其他说明操作。
  5. 当看到脚本时，复制脚本并将其粘贴到您的终端。

第 2 步：克隆代码库

在此步骤中，您将克隆 googleapis 和 routes-auto-early-access 代码库。

  1. 克隆 routes-auto-early-access 代码库： 
    git clone https://partner-code.googlesource.com/routes-auto-early-access
  2. 克隆公共 Google googleapis 代码库： 
    git clone https://github.com/googleapis/googleapis.git

第 3 步：合并代码库

在此步骤中，您需要将 routes-auto-early-access/google/maps/routing/v2 子目录移到 googleapis/google/maps/routing/v2 中。

  1. 克隆代码库后，请确保您的当前工作目录 (pwd) 同时包含 routes-auto-early-access 和 googleapis 子目录。 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. 在目标位置中创建一个 routing/v2 目录，并将 routing/v2 复制到 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"

如需确认 routing/v2 目录已成功合并到 googleapis/google/maps/routing/v2 目录中，请转到 googleapis/google/maps/routing/v2。 该文件夹应包含 proto 文件、BUILD.bazel 文件以及构建所需的其他文件。

第 4 步：使用 Bazelisk 构建客户端库

如需针对特定语言构建客户端库，请在 BUILD.bazel 文件（位于 googleapis/google/maps/routing/v2/BUILD.bazel 处）中标识该语言的构建目标，并构建该目标。您可以在 <LANGUAGE>_gapic_assembly_pkg 对象内找到目标 name。如需了解详情，请参阅 Bazel 文档中的构建一个目标。

例如，如需构建 Java 客户端库，请执行以下操作：

  1. 切换到 googleapis 目录： 
    cd googleapis
  2. 运行以下命令： 
    bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java

    此命令会在 googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz 中生成 Java 客户端库。

为方便起见，下表列出了每种可用语言的构建命令。

语言 Bazelisk 构建命令
Java bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java
前往 bazelisk build google/maps/routing/v2:gapi-cloud-maps-routing-v2-go
299 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
节点 bazelisk build google/maps/routing/v2:maps-routing-v2-nodejs

在有新版本时纳入更新

当 API 有新版本时，您需要重新构建客户端库。假设您已按照前几部分中的说明克隆了代码库，请针对新版本执行以下操作：

  1. 切换到包含这两个代码库的当前工作目录： 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. 移除 googleapis/google/maps 中的上一个 routing/v2 实例： 
    rm -rf googleapis/google/maps/routing/v2
  3. 转到 routes-auto-early-access 和 googleapis 代码库，然后运行 git pull 以获取最新更新。
  4. 将 routing/v2 复制到 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"

    如需确认 routing/v2 代码库已成功合并到 googleapis/google/maps/routing/v2 目录中，请转到 googleapis/google/maps/routing/v2。 该文件夹应包含 proto 文件、BUILD.bazel 文件以及 Bazel 构建所需的其他文件。

  5. 运行上文第 4 步：使用 Bazelisk 构建客户端库部分中列出的 Bazelisk 构建命令。

为 Java 客户端库生成 Javadocs

借助客户端库，您可以使用特定于该语言的类和方法调用 Routes API for Automotive。遗憾的是，输出结果中不包含客户端库的 Javadoc 文档。本部分介绍了如何为 Java 客户端库生成 Javadoc。

前提条件

如需构建 Javadoc，请执行以下操作：

  1. 确保已安装兼容版本的 Gradle（8.0 或更高版本）和 JDK（17 或更低版本）。您可以在终端中运行 ./gradlew --version 和 java -version 来检查安装的版本。

  2. Java 客户端库已构建到您需要提取的 tar.gz 文件中：googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz。

    假设您位于 googleapis 目录中，请运行以下命令，并将 /PATH/TO/PARENT/DIRECTORY 替换为您为提取的库选择的路径：

    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. 导航到父级目录：

    cd /PATH/TO/PARENT/DIRECTORY

  4. 从 google-cloud-maps-routing-v2-java 目录中，打开以下每个目录中的 build.gradle 文件：

    • 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

    确保每个文件均包含以下任务。由于存在 bug，请使用以下代码替换现有的两个类似任务和工件：

    
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. 检查您是否使用的是 Gradle 8.0 或更高版本：./gradlew --version。如果您的版本为 7，请执行以下操作：在 google-cloud-maps-routing-v2-java 目录中，删除 gradlew 和 gradlew.bat 文件。然后，运行 gradle wrapper --gradle-version=8.0 切换到 8.0。

  6. 从 google-cloud-maps-routing-v2-java 目录中，使用 Gradle 构建 Javadocs：

    ./gradlew build

    生成的 Javadoc 显示在以下目录中：

    • 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. 使用网络浏览器打开每个目录的 overview-tree.html 文件。