google-drive

Google Drive ファイル

ID は検索で取得し、推測しないでください

すべてのツールには Drive ファイル ID が必要です。ID は search（既知のフォルダーには list_folder、「直前に作業していたファイル」には list_recent_files）から取得するか、 ユーザーが貼り付けた URL 内の ID を使ってください。既知のファイル名には query より exact_name を優先し、結果を絞り込むには mime_type_filter を追加してください。ID を 作り出したり、古い会話で使った ID を再利用したりしてはいけません。まず再検索してください。

フォルダーの指定

• create_folder には parent_folder_id が必要です。指定しない場合、フォルダーは My Drive のルートに作成されます。ユーザーが保存先のフォルダーを指定した場合は、 その ID を解決して渡してください。フォルダーが指定されているのにルートに作成された ファイルは、内容が完璧でも誤った結果です。
• create_file にも parent_folder_id を指定できます。作成後に移動するのではなく、 ファイルを本来の場所に直接作成してください。
• Docs／Sheets／Slides プロバイダー独自の作成ツールではフォルダーを指定できません （これらの API に親フォルダーのパラメーターがありません）。保存場所が重要な場合は、 create_file でその場所にファイルを作成する（Markdown から Doc、CSV から Sheet）か、 作成後に move_or_rename を destination_folder_id とともに使ってください。
• move_or_rename は、1 回の呼び出しで移動、名前変更、またはその両方を行います。名前を 変更しても ID は変わりません。
• update_file は、ホストされた Drive ツールの引数名（fileId。title は名前を変更し、 parentId は現在の親フォルダーを置き換えて移動します）を使って、同じ名前変更／移動を 行います。これは翻訳用とホスト用の両方のサーフェスにあるため、どちらでも使える案内では こちらを優先してください。
• 権限の制限：このアプリの権限付与は drive.file です。そのため、このアプリが作成して おらず、ユーザーも選択していないファイルやフォルダーへの移動や書き込みは、403 エラーに なることがあります。この 403 は権限によるもので、一時的なエラーではありません。再試行 しないでください。

Markdown と CSV の変換

create_file に target_mime_type: application/vnd.google-apps.document を指定すると、Markdown（見出し、リスト、 表）が 1 回の呼び出しで実際の Google ドキュメントに変換されます。...spreadsheet を 指定すると、CSV がスプレッドシートに変換されます。書式付きの Doc を作成する最速で確実な 方法です。内容が事前にわかっている場合は、作成後に挿入する方法よりこちらを優先してください。 update_file_content も同じ方法でその場で変換します。

コピー、メタデータ、共有

• copy_file はファイルを複製します（フォルダーへの保存も任意で指定可能です）。 元のファイルに触れずにテンプレートを使うには、この方法が適切です。
• get_file_metadata は完全なレコード（MIME タイプ、親フォルダー、サイズ、所有者、 更新日時）を返します。移動が完了したことの確認に使ってください。
• get_file_permissions はアクセス権を持つユーザーを一覧表示し、share_file は メールアドレスにロールを付与します。共有するのはユーザーから依頼された場合だけにして ください。推測でアクセス範囲を広げず、リンクを報告してください。
• download_file は、Google 形式以外のファイル（画像、PDF、プレーンテキスト）の生バイトを Base64 エンコードして返します。

読み取りとエクスポート

• read_file はテキストを返します。Docs は Markdown、Sheets はタブごとの CSV、 Slides はプレーンテキストとして返します。書き込み後の内容確認に使ってください。
• export_file はレンダリングされたバイトを Base64 エンコードして返します。Docs／Sheets／ Slides には pdf（Sheets の PDF にはグラフを含むすべてのタブが描画されます）、 Drawings には png／svg のほか、Office 形式（docx／xlsx／pptx）も指定できます。 最終的な見た目を確認したい場合は PDF を使ってください。エクスポートの上限は 10 MB です。
• 1 枚のスライドを PNG にするには、Drive のエクスポートではなく、google-slides の get_slide_thumbnail ツールを使ってください。

コメント

コメントは Drive ファイルに保存されるため、Docs、Sheets、Slides のいずれにも同じツール セットを使えます。

• list_comments は、各コメントのテキスト、引用されたドキュメントのテキスト、解決済みの 状態、返信を返します。ページ分割されるため、スレッドが存在しないと判断する前に nextPageToken を確認してください。
• add_comment はファイル単位のコメントを追加します（テキストのアンカーはありません）。
• reply_to_comment はコメント ID を指定して返信します。action: "resolve" は （コンテンツは任意で）スレッドを解決する唯一の方法です。コメント付近のドキュメント テキストを編集しても、スレッドは解決されません。すでに解決済みのスレッドはそのままに してください。

削除

trash_file で削除したファイルやフォルダーは約30日間復元可能です。フォルダーをゴミ箱に移動すると、その中身も一緒に移動します。完全削除は意図的に利用できないため、決して可能だと約束しないでください。

作業を確認する

作成や移動の後は、移動先で list_folder を実行するか、get_file_metadata で parents を確認して、配置を確認してください。 コンテンツを書き込んだ後は、テキストについては read_file、レンダリング結果については export_file（pdf）を正として確認してください。