connector-googledrive

Google Drive Connector

注記。 クライアントは Drive v3 Discovery ドキュメントから生成されています。 diagnostics が有効になっているため、デコードの不備があると誤ったデータを 黙って返すのではなく、明確にエラーになります。ネストされたファサードのメソッドは、 各 Drive エンドポイントのすべてのクエリパラメーターを位置引数として受け取ります （Text／Bool 型の引数が多数あります）。呼び出す前に、Client.mo の生成された シグネチャを確認してください。メディアエンドポイントはメタデータのみを扱います （メディアに関する注意事項を参照）。

オーケストレーターのルーティングに関する注意事項

googledrive-client と google-oauth の組み合わせが、Caffeine カニスターから 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.*

このクライアントではサポートされていません： ファイルのバイトデータの転送（コンテンツのアップロード／ダウンロード）。末尾のメディアに関する注意事項を参照してください。メタデータ、整理、共有に使用してください。

バックエンド

このコネクターには、2 つの mops パッケージがあります。

1. googledrive-client — Drive REST API v3 用に生成された Motoko クライアントです。 OAuth には依存せず、すべての呼び出しで Config を介してベアラートークンを受け取ります。
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、オンチェーンでの交換と更新

カニスターは 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 — フルアクセス（タスクで本当に必要な場合を除き、避けてください）。

リフレッシュトークンはローテーションされません。最初に受け取ったリフレッシュトークンを保存してください（ユーザーごとに固定です）。カニスターの安定状態に永続化し、Wasm のグローバルには保存しないでください。

3. is_replicated = ?false は必須です

Drive へのすべての外部呼び出しには、Authorization: Bearer <token> が含まれます。デフォルトのレプリケート実行では、サブネット内の各レプリカが個別にリクエストを発行するため、コストが増加し、書き込みでは副作用が重複します（たとえば、同じファイルが N 個作成されます）。生成された defaultConfig では、すでに is_replicated = ?false が設定されています（クライアントの isReplicated 生成オプションによる設定です）。そのため、defaultConfig を使い始めれば、読み取りと書き込みの両方で正しい値になります。?false のまま維持し、?true に上書きしないでください。（書き込み（PUT／DELETE／PATCH）は、クライアントによって呼び出しごとに非レプリケートに強制されます。）

4. クライアントの使用 — ネストされたファサード

googledrive-client には、Config を一度だけ取得し、Drive のリソース階層をネストされたクラスとして公開する Client.mo ファサード（fluentHierarchical で生成）が含まれています。

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 ホストへのリクエスト）。これは現時点では、このコネクタの対象外です。