本指南简要介绍如何使用 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 字段名称使用蛇形命名法。
- 客户端库字段名称使用词首字母大写形式、驼峰式大小写或蛇形命名法， 取决于哪种名称对于语言是惯用的。
Protocol Buffers
无论您使用的是 客户端库、REST 还是 gRPC， 底层服务都是使用 Protocol Buffers定义的。 具体而言，该服务使用 proto3。
调用 API 时， 某些请求或响应字段可能需要您对 协议缓冲区的知名类型有基本的了解。
此外，调用 REST API 时， 默认值 Protocol Buffers 的行为可能会导致 JSON 响应中缺少字段。 这些字段只是设置为默认值， 因此不会包含在响应中。
API 版本
API 有以下版本：
- v2（正式版）用于 管理 Gemini Enterprise Agent Platform Workbench 实例。