google-drive

Google Drive

Google Drive を操作して、ファイルの管理、検索、共有を行います。

インストール

依存関係：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

セットアップの確認

インストール後、スキルが正しく設定されていることを確認します。

$SKILL_DIR/scripts/google-drive.py check

以下を確認します。

• Python の依存関係（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
• 認証設定
• Google Drive API への接続

不足している項目がある場合、確認コマンドにセットアップ手順が表示されます。

認証

Google Drive は認証に OAuth 2.0 を使用します。セットアップの詳しい手順については、以下を参照してください。

1. GCP プロジェクトのセットアップガイド — プロジェクトの作成と Drive API の有効化
2. Google OAuth のセットアップガイド — 認証情報の設定

クイックスタート

1. ~/.config/agent-skills/google.yaml を作成します。

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. $SKILL_DIR/scripts/google-drive.py check を実行して OAuth フローを開始し、セットアップを確認します。

スコープまたは認証のエラーについては、OAuth のトラブルシューティングガイドを参照してください。

スクリプトの使い方

各コマンドの読み取り／書き込みの分類については、permissions.md を参照してください。

# Setup and auth
$SKILL_DIR/scripts/google-drive.py check
$SKILL_DIR/scripts/google-drive.py auth setup --client-id ID --client-secret SECRET
$SKILL_DIR/scripts/google-drive.py auth reset
$SKILL_DIR/scripts/google-drive.py auth status

# Files
$SKILL_DIR/scripts/google-drive.py files list [--query QUERY] [--max-results N] [--order-by FIELD]
$SKILL_DIR/scripts/google-drive.py files search [--name NAME] [--mime-type TYPE] [--folder ID]
$SKILL_DIR/scripts/google-drive.py files get FILE_ID
$SKILL_DIR/scripts/google-drive.py files download FILE_ID --output PATH
$SKILL_DIR/scripts/google-drive.py files export FILE_ID [--format markdown|text|pdf] [--lines N] [--output PATH]
$SKILL_DIR/scripts/google-drive.py files upload PATH [--parent ID] [--name NAME] [--mime-type TYPE] [--convert-to MIME_TYPE]
$SKILL_DIR/scripts/google-drive.py files move FILE_ID --parent FOLDER_ID
$SKILL_DIR/scripts/google-drive.py files delete FILE_ID
$SKILL_DIR/scripts/google-drive.py files rename FILE_ID --name NAME
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID [--name NAME] [--parent ID]

# Folders
$SKILL_DIR/scripts/google-drive.py folders create NAME [--parent ID]
$SKILL_DIR/scripts/google-drive.py folders list FOLDER_ID [--max-results N]

# Sharing and permissions
$SKILL_DIR/scripts/google-drive.py share FILE_ID --email EMAIL [--role ROLE] [--no-notify]
$SKILL_DIR/scripts/google-drive.py permissions list FILE_ID
$SKILL_DIR/scripts/google-drive.py permissions delete FILE_ID PERMISSION_ID

# Comments
$SKILL_DIR/scripts/google-drive.py comments list FILE_ID [--max-results N] [--include-deleted]
$SKILL_DIR/scripts/google-drive.py comments get FILE_ID COMMENT_ID
$SKILL_DIR/scripts/google-drive.py comments create FILE_ID --content TEXT [--quoted-text TEXT]
$SKILL_DIR/scripts/google-drive.py comments update FILE_ID COMMENT_ID --content TEXT
$SKILL_DIR/scripts/google-drive.py comments delete FILE_ID COMMENT_ID

# Replies
$SKILL_DIR/scripts/google-drive.py replies list FILE_ID COMMENT_ID [--max-results N] [--include-deleted]
$SKILL_DIR/scripts/google-drive.py replies get FILE_ID COMMENT_ID REPLY_ID
$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID --content TEXT [--action resolve|reopen]
$SKILL_DIR/scripts/google-drive.py replies update FILE_ID COMMENT_ID REPLY_ID --content TEXT
$SKILL_DIR/scripts/google-drive.py replies delete FILE_ID COMMENT_ID REPLY_ID

引数の詳細と例については、command-reference.md を参照してください。

例

セットアップを確認する

$SKILL_DIR/scripts/google-drive.py check

最近の PDF ファイルを検索する

$SKILL_DIR/scripts/google-drive.py files list --query "mimeType='application/pdf'" --max-results 5

名前でドキュメントを検索する

$SKILL_DIR/scripts/google-drive.py files search --name "project proposal"

ファイルをダウンロードする

# First, find the file ID
$SKILL_DIR/scripts/google-drive.py files search --name "report.pdf"

# Then download it
$SKILL_DIR/scripts/google-drive.py files download FILE_ID -o ./report.pdf

Google ドキュメントをエクスポートする

# Export as markdown (default)
$SKILL_DIR/scripts/google-drive.py files export FILE_ID

# Export as plain text (useful as fallback for large docs)
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format text

# Export first 50 lines only
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format text --lines 50

# Export as PDF
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format pdf --output ./doc.pdf

ファイルをアップロードして共有する

# Upload the file
$SKILL_DIR/scripts/google-drive.py files upload ./presentation.pdf --name "Q4 Presentation"

# Share with a colleague
$SKILL_DIR/scripts/google-drive.py share FILE_ID --email [email protected] --role writer

形式を変換してアップロードする

--convert-to を使用すると、アップロードしたファイルを Google のネイティブ形式に変換できます。

# Upload HTML and convert to Google Docs
$SKILL_DIR/scripts/google-drive.py files upload ./report.html \
  --convert-to "application/vnd.google-apps.document"

# Upload CSV and convert to Google Sheets
$SKILL_DIR/scripts/google-drive.py files upload ./data.csv \
  --convert-to "application/vnd.google-apps.spreadsheet"

注： Markdown ファイルを適切な書式（フロントマターのサポート、行間、箇条書きの処理、読みやすさの確認）で Google ドキュメントとしてインポートするには、代わりに google-docs スキルの documents import コマンドを使用してください。このコマンドは Markdown に特化した変換とインポート後の書式設定に対応しており、--convert-to では対応できない機能を提供します。

ファイルを完全に削除する

$SKILL_DIR/scripts/google-drive.py files delete FILE_ID

ファイル名を変更する

$SKILL_DIR/scripts/google-drive.py files rename FILE_ID --name "New Name"

ファイルをコピーする

# Copy with default name ("Copy of <original>")
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID

# Copy with custom name into a specific folder
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID --name "Backup" --parent FOLDER_ID

ファイルをフォルダーに整理する

# Create a folder
$SKILL_DIR/scripts/google-drive.py folders create "Project Documents"

# Upload files to the folder
$SKILL_DIR/scripts/google-drive.py files upload ./doc1.pdf --parent FOLDER_ID
$SKILL_DIR/scripts/google-drive.py files upload ./doc2.pdf --parent FOLDER_ID

# List folder contents
$SKILL_DIR/scripts/google-drive.py folders list FOLDER_ID

ファイルのコメントを一覧表示する

$SKILL_DIR/scripts/google-drive.py comments list FILE_ID

メンション付きのコメントを追加する

ユーザーにメンションするには、本文に @ を付けたメールアドレスを含めます。

$SKILL_DIR/scripts/google-drive.py comments create FILE_ID \
  --content "Hey @[email protected] please review this section"

コメントに返信して解決する

$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID \
  --content "Fixed in latest revision" --action resolve

解決済みのコメントを再開する

$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID \
  --content "Actually this still needs work" --action reopen

Drive 検索クエリの構文

演算子、検索可能なフィールド、クエリの例については、drive-queries.md を参照してください。

一般的な MIME タイプ

--mime-type と検索クエリで使用する MIME タイプについては、api-reference.md を参照してください。

未対応の操作

未実装の操作と代替手段については、api-reference.md を参照してください。

エラー処理

認証エラーとスコープエラーは再試行できません。 コマンドが認証エラー、スコープ不足エラー、または権限拒否エラー（終了コード 1）で失敗した場合は、停止してユーザーに知らせてください。自動で再試行したり、問題を解決しようとしたりしないでください。これらのエラーには、ユーザーによる操作（ブラウザー上での OAuth 同意）が必要です。OAuth のトラブルシューティングガイドをユーザーに案内してください。

再試行可能なエラー：レート制限（HTTP 429）と一時的なサーバーエラー（HTTP 5xx）は、少し待ってから再試行すると成功する場合があります。それ以外のすべてのエラーは、ユーザーに報告してください。

モデルに関するガイダンス

このスキルは、構造化された入出力を必要とする API 呼び出しを行います。標準的な能力を持つモデルを推奨します。

トラブルシューティング

Google ドキュメントをダウンロードできない

Google ドキュメント、スプレッドシート、スライドはバイナリファイルではないため、files download ではダウンロードできません。代わりに files export を使って、Markdown、プレーンテキスト、または PDF としてエクスポートしてください。大きなドキュメントの出力を制限するには、--lines N を使用してください。