透過 Bazelisk (Automotive) 產生用戶端程式庫

用戶端程式庫是 API 的語言專屬介面。本文件說明如何使用 Bazelisk (適用於 Bazel) 的啟動器，為 Automotive 的 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
₱25 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. 執行前一節列出的 Bazelisk 建構指令步驟 4：使用 Bazelisk 建構用戶端程式庫。

為 Java 用戶端程式庫產生 Javadocs

這個用戶端程式庫可讓您使用特定語言專屬的類別和方法，呼叫 Automotive 適用的 Routes API。很抱歉，輸出結果不包含用戶端程式庫的 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

    並確認每項工作都包含以下工作。由於發生錯誤，請將現有的兩個相似的工作和構件替換為以下程式碼：

    
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 檔案。