透過 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:複製存放區

在這個步驟中,您將複製 googleapisroutes-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-accessgoogleapis 子目錄。
    .
       ├── 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-accessgoogleapis 存放區,並執行 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 --versionjava -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 目錄中刪除 gradlewgradlew.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 檔案。