本指南將概略說明如何使用 Notebooks API 和參考說明文件。
REST、gRPC 和用戶端程式庫
您可以透過 REST、gRPC 或我們提供的其中一個用戶端程式庫 (以 gRPC 建構) 來存取 API。
用戶端程式庫
Google 提供多種常用語言的用戶端程式庫，方便您存取這個 API。如果用戶端程式庫支援您偏好的程式設計語言，請使用這個選項。
| 優點 | 缺點 |
|---|---|
|
由 Google 維護。
內建驗證。 內建重試機制。 各語言的慣用語。 效率高的通訊協定緩衝區 HTTP 要求主體。 |
不適用於所有程式設計語言。 |
REST
這個 API 支援 REST。請參閱這個 API 的 REST 參考資料。另請參閱「如何呼叫 Google API：REST 版」。
| 優點 | 缺點 |
|---|---|
|
簡單的 JSON 介面。
許多 Google 和第三方工具與程式庫都支援這項功能。 |
您必須自行建構用戶端。
您必須導入驗證機制。 您必須實作重試機制。 效率較低的 JSON HTTP 要求主體。 這個 API 不支援 REST 串流。 |
gRPC
這項 API 支援 gRPC。請參閱此 API 的 RPC 參考資料，其中提供為 gRPC 程式庫產生的型別、方法和欄位的一般說明。另請參閱「如何呼叫 Google API：RPC 版本」。
| 優點 | 缺點 |
|---|---|
|
支援多種程式設計語言。 效率高的通訊協定緩衝區 HTTP 要求主體。 |
您必須從 Google 提供的通訊協定緩衝區產生自己的用戶端。
您必須導入驗證機制。 您必須實作重試機制。 |
類型、方法和欄位名稱
視您使用用戶端程式庫、REST 或 gRPC 而定，API 的類型、方法和欄位名稱會略有不同：
- REST 會依資源階層及其方法排列。
- 用戶端程式庫和 gRPC 會依服務及其方法排列。
- REST 欄位名稱使用駝峰式大小寫，但 API 服務會接受駝峰式大小寫或蛇形命名法。
- gRPC 欄位名稱使用蛇形命名法。
- 視語言的慣例而定，用戶端程式庫欄位名稱會使用首字大寫、駝峰式大小寫或蛇形命名法。
通訊協定緩衝區
無論您使用用戶端程式庫、REST 或 gRPC，底層服務都是使用通訊協定緩衝區定義。具體來說，這項服務使用 proto3。
呼叫 API 時，部分要求或回應欄位可能需要基本瞭解通訊協定緩衝區的知名型別。
此外，呼叫 REST API 時，通訊協定緩衝區的預設值行為可能會導致 JSON 回應缺少欄位。這些欄位只是設為預設值，因此不會納入回應。
API 版本
可用的 API 版本如下：
- v2 (正式推出) 用於管理 Gemini Enterprise Agent Platform Workbench 執行個體。