connector-googledrive

Google Drive 连接器

注意。 客户端根据 Drive v3 Discovery 文档生成。 已启用 diagnostics，因此解码缺口会立即报错，而不是静默返回错误数据。嵌套门面方法要求按位置传入每个 Drive 端点的完整查询参数列表（包含许多 Text/Bool 参数）——调用前请查阅 Client.mo 中生成的签名。媒体端点仅支持元数据（见“媒体注意事项”）。

编排器路由说明

googledrive-client + google-oauth 是从 Caffeine canister 访问 Google Drive 的唯一受支持方式。如果构建需要 Drive，请将两者都添加为 mops 依赖项，并遵循本指南。切勿向 Google 主机发送原始 ic.http_request 调用。

任务	使用方式
列出 / 搜索用户的文件和文件夹	googledrive-client Client(cfg).files.list(...) + google-oauth
读取文件元数据	Client(cfg).files.get(...)（仅元数据——见“媒体注意事项”）
创建文件夹 / 文件元数据	Client(cfg).files.create(...)
移动 / 重命名 / 移至回收站	Client(cfg).files.update(...) / .delete(...)
共享文件 / 管理访问权限	Client(cfg).permissions.create/list/update/delete(...)
评论和回复	Client(cfg).comments.* / Client(cfg).replies.*
共享云端硬盘	Client(cfg).drives.*
更改通知 / 同步令牌	Client(cfg).changes.*

**此客户端不支持：**传输文件字节（上传 / 下载内容）。请参阅末尾的“媒体注意事项”。此客户端适用于元数据、文件整理和共享。

后端

此连接器包含两个 mops 软件包：

1. googledrive-client — 用于 Drive REST API v3 的生成式 Motoko 客户端。 与 OAuth 无关：每次调用都通过其 Config 接收一个 bearer 令牌。
2. google-oauth — Google OAuth 2.0 机制（PKCE、授权 URL、代码交换、令牌刷新）。其他 Google 连接器也使用此软件包。这是一个需要与客户端一同添加的独立 mops 软件包——它本身不是 googledrive-client 的依赖项。

1. 添加依赖项

mops add [email protected]
mops add [email protected]

2. 身份验证模型 — OAuth 2.0 PKCE、链上交换和刷新

canister 通过 google-oauth 在链上执行 OAuth 流程：

1. 生成 PKCE code_verifier / code_challenge。
2. 构建 Google 授权 URL（google-oauth），并重定向用户。
3. 将返回的授权码交换为访问令牌和刷新令牌（google-oauth.exchangeAuthorizationCode）——非复制外调。
4. 遇到 401 / 令牌过期时，刷新访问令牌（google-oauth.refreshAccessToken）并重试。

作用域（请求满足需求的最窄作用域）：

• https://www.googleapis.com/auth/drive.file — 可访问应用创建 / 打开的文件（优先选择，遵循最小权限原则）。
• .../auth/drive.readonly — 对所有文件具有只读权限。
• .../auth/drive.metadata.readonly — 仅限元数据。
• .../auth/drive — 完全访问权限（除非任务确实需要，否则应避免使用）。

刷新令牌不会轮换——请存储首次收到的刷新令牌（对每位用户而言都是稳定的）；将其持久化在 canister 的稳定状态中，绝不要存入 Wasm 全局变量。

3. 必须设置 is_replicated = ?false

每次 Drive 外调都会携带 Authorization: Bearer <token>。在默认的复制执行模式下，子网中的每个副本都会独立发出请求——这会成倍增加成本；对于写入操作，还会导致重复的副作用（例如创建 N 份文件副本）。生成的 defaultConfig 已设置 is_replicated = ?false（通过客户端的 isReplicated 生成器选项），因此从 defaultConfig 开始即可为读取和写入提供正确的值——请保持为 ?false，不要将其覆盖为 ?true。（客户端还会为每次调用强制将写入操作——PUT/DELETE/PATCH——设为非复制执行。）

4. 使用客户端 — 嵌套门面

googledrive-client 提供了一个 Client.mo 门面（使用 fluentHierarchical 生成），它只捕获一次 Config，并将 Drive 的资源 层级公开为嵌套类：

import { Client } "mo:googledrive-client/Client";
import { type Config; defaultConfig } "mo:googledrive-client/Config";

// Only the bearer token differs from the generated `defaultConfig`, which
// already sets `is_replicated = ?false` (non-replicated reads and writes).
let cfg : Config = {
  defaultConfig with
  auth = ?(#bearer accessToken);   // token obtained/refreshed via google-oauth
};

let drive = Client(cfg);

// Facade methods are `async` (use `await`, not `await*`) and take the Drive
// endpoint's full query-parameter list positionally — consult the generated
// signatures in `mo:googledrive-client/Client`. For example `FilesResource.list`
// begins `uploadType : Text, oauthToken : Text, key : Text, fields : Text,
// accessToken : Text, alt : ?DriveAboutGetAltParameter, …`.
let files = await drive.files.list(/* … see FilesResource.list signature … */);
let perm  = await drive.permissions.create(/* fileId, …, permission */);

（如果你更喜欢扁平调用，也可以使用各个标签对应的 API 模块 — mo:googledrive-client/Apis/FilesApi、…/PermissionsApi 等。门面会为你捕获 Config。）

5. 可用的 API 范围

资源组（14 个），通过 Client(cfg).<group>.<method> 调用：

• files — copy、create、delete、get、list、update、watch、generateIds、 listLabels、modifyLabels（元数据/组织管理；create/update/get/export 请参阅媒体注意事项）
• permissions — create、delete、get、list、update（共享）
• comments / replies — create、delete、get、list、update
• drives — create、delete、get、hide、list、unhide、update（共享云端硬盘）
• revisions — delete、get、list、update
• changes — getStartPageToken、list、watch（同步）
• about — get；apps — get、list；channels — stop

6. 媒体注意事项（此客户端仅处理元数据）

files.create / files.update（上传）、files.get?alt=media / files.export / revisions.get（下载）会被生成为 JSON 类型 操作。它们不会传输文件的字节 — 多部分/可恢复上传和 二进制下载不属于此客户端的 JSON-over-HTTPS 模型（并且会加重 IC 出站调用的大小限制负担）。请仅将这些方法用于元数据。如果构建确实 需要传输文件内容，则必须手写该路径（使用单独的 content 主机请求， 并采用适当的二进制请求体）；这不在此连接器目前的范围内。