Fize/workspace-kit

Google Docs（クラウドドキュメントスキル）

Matonが管理するOAuth認証を介してGoogle Docs APIにアクセスします。Googleドキュメントの作成、読み取り、更新、書式設定、バッチ編集を行います。

⚠️ クラウド vs ローカルファイルの明確な区別:

• google-docs（このスキル）: オンラインのGoogleドキュメント（docs.google.com/document/d/{documentId}）専用です。Maton OAuth APIプロキシを介してGoogleのクラウドサーバーと直接やり取りします。
• docx スキル: ローカルディスク上の .docx / .doc ファイルの読み取り、作成、編集を行います。

---

クイックスタート

CLI:

# ドキュメント構造とテキスト内容を取得
maton google-docs document get <documentId>

# 新しいGoogleドキュメントを作成
maton google-docs document create --title 'プロジェクトアーキテクチャ仕様書'

# ドキュメント本文にテキストを追加
maton google-docs document write <documentId> --text 'ミーティングノート: Q3ロードマップに関する議論。'

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

---

ベースURL

https://api.maton.ai/google-docs/{native-api-path}

Matonはリクエストを docs.googleapis.com にプロキシし、OAuthトークンを自動的に注入します。

---

CLIインストール（任意 — エージェントが判断）

Maton CLIはオプションです。エージェントは環境に基づいてインストールするかどうかを判断できます。

macOS / Linux

curl -fsSL https://maton.ai/install.sh | bash

Windows

irm https://maton.ai/install.ps1 | iex

npm（クロスプラットフォーム）

npm install -g @maton/cli

Homebrew（macOS）

brew install maton-ai/cli/maton

インストール後、以下で確認:

maton --version

---

認証

CLI:

maton login                          # ブラウザを開いてAPIキーを取得
maton login --interactive            # ブラウザをスキップし、APIキーを直接貼り付け
maton whoami                         # 現在の認証状態を表示

手動:

1. maton.ai にサインインまたはアカウント作成
2. maton.ai/settings に移動
3. APIキーをコピー
4. APIキーを MATON_API_KEY として設定:

export MATON_API_KEY="YOUR_API_KEY"

---

接続管理

Google DocsのOAuth接続を https://api.maton.ai で管理します。

接続一覧

CLI:

maton connection list google-docs --status ACTIVE

maton api -X GET /connections -f app=google-docs -f status=ACTIVE

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-docs&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

接続作成

CLI:

maton connection create google-docs

maton api /connections -f app=google-docs

Python:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-docs"
  }
}

返された url をブラウザで開き、OAuth認証を完了します。

接続取得

CLI:

maton connection get {connection_id}                 # エイリアス: maton connection view

maton api /connections/{connection_id}

接続削除

CLI:

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

接続の指定

複数のGoogle Docs接続がある場合、使用する接続を指定します:

CLI:

maton google-docs document get <documentId> --connection {connection_id}

maton api /google-docs/v1/documents/<documentId> --connection {connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

複数の接続がある場合は、常に接続を指定して、リクエストが目的のアカウントに送信されるようにします。

---

セキュリティと権限

• アクセスは、接続されたGoogleアカウント内のGoogle Docsに限定されます。
• すべての書き込みおよび削除操作には、明示的なユーザー承認が必要です。 対象リソースIDとコンテンツ変更について、実行前にユーザーに確認してください。

---

APIリファレンス

1. ドキュメント取得

タイトル、構造要素、インラインオブジェクト、段落スタイルを含む、完全なドキュメントオブジェクトを取得します。

GET /google-docs/v1/documents/{documentId}

クエリパラメータ:

• suggestionsViewMode - DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_APPROVED, PREVIEW_WITHOUT_SUGGESTIONS, SUGGESTIONS_INLINE

CLI例:

maton google-docs document get <documentId>
maton google-docs document get <documentId> --json

---

2. 空白ドキュメント作成

指定されたタイトルで新しい空のGoogleドキュメントを作成します。

POST /google-docs/v1/documents
Content-Type: application/json

{
  "title": "四半期テクニカルレビュー"
}

CLI例:

maton google-docs document create --title '四半期テクニカルレビュー'

---

3. ドキュメントへのプレーンテキスト追加

CLI経由でドキュメント本文の末尾にプレーンテキストを追加します。

CLI例:

# 直接テキスト入力
maton google-docs document write <documentId> --text 'Hello, world!'

# ファイルから読み込み
maton google-docs document write <documentId> -F notes.md

# 標準入力からパイプ
echo 'パイプされた概要' | maton google-docs document write <documentId> -F -

---

4. ドキュメント内容と構造のバッチ更新（リッチフォーマット）

ドキュメントのテキスト、書式、段落スタイル、ヘッダー/フッター、インラインテーブルに対してアトミックな変更を実行します。

POST /google-docs/v1/documents/{documentId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "エグゼクティブサマリー\n\nこのドキュメントは、クラウド移行戦略の概要を示します。"
      }
    }
  ]
}

CLI例:

maton api -X POST /google-docs/v1/documents/<documentId>:batchUpdate \
  -d '{"requests":[{"insertText":{"location":{"index":1},"text":"Hello World\n"}}]}'

batchUpdate の一般的なリクエストタイプ:

1. insertText: 指定されたインデックス位置にテキストを挿入します。
2. deleteContentRange: 指定された range（startIndex と endIndex）内のコンテンツを削除します。
3. replaceAllText: ドキュメント全体でテキストをグローバルに検索して置換します。

   {
     "replaceAllText": {
       "containsText": {
         "text": "{{PROJECT_NAME}}",
         "matchCase": true
       },
       "replaceText": "SoloQueue v2.0"
     }
   }
   

4. updateTextStyle: 範囲に太字、斜体、フォントサイズ、または色の書式を適用します。
5. updateParagraphStyle: 見出しスタイル（HEADING_1、HEADING_2、NORMAL_TEXT）を適用します。

---

ドキュメント構造からプレーンテキストを抽出

Google Docs APIは、body.content 内のコンテンツを構造要素として返します。Pythonでドキュメントのプレーンテキストを読み取るには:

import os, json, urllib.request

req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
doc = json.load(urllib.request.urlopen(req))

text_chunks = []
for element in doc.get('body', {}).get('content', []):
    if 'paragraph' in element:
        for elem in element['paragraph'].get('elements', []):
            if 'textRun' in elem:
                text_chunks.append(elem['textRun'].get('content', ''))

print("".join(text_chunks))

---

コード例

CLI

# ドキュメントを作成
maton google-docs document create --title 'スプリントプランニング'

# ドキュメントに初期メモを書き込み
maton google-docs document write <documentId> --text 'スプリント42の目標:\n- 認証をローンチ\n- 速度テスト'

# ドキュメント構造をJSONで確認
maton google-docs document get <documentId> --json

JavaScript

// ドキュメントメタデータとコンテンツを取得
const response = await fetch(
  'https://api.maton.ai/google-docs/v1/documents/<documentId>',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const doc = await response.json();
console.log(doc.title);

// 新しいドキュメントを作成
const createResponse = await fetch(
  'https://api.maton.ai/google-docs/v1/documents',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'RFC: AIスキルゲートウェイ'
    })
  }
);
const newDoc = await createResponse.json();
console.log('作成されたドキュメントID:', newDoc.documentId);

Python

import os
import requests

# ドキュメント取得
response = requests.get(
    'https://api.maton.ai/google-docs/v1/documents/<documentId>',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
doc = response.json()
print(doc.get('title'))

# ドキュメント作成
create_response = requests.post(
    'https://api.maton.ai/google-docs/v1/documents',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'title': 'RFC: AIスキルゲートウェイ'}
)
print('作成完了:', create_response.json().get('documentId'))

---

注意事項

• ドキュメントIDは不透明な文字列です（URL https://docs.google.com/document/d/<documentId>/edit から抽出します）。
• maton google-docs document write はドキュメント本文の末尾にプレーンテキストを追加します。特定のインデックスにテキストを挿入したり、テキストを置換したり、見出し/太字スタイルを適用したりするには、batchUpdate を使用してください。
• 重要: curlコマンドを使用する場合、URLに括弧が含まれているときは curl -g を使用してグロブ解析を無効にしてください。
• 重要: curlの出力を jq やその他のコマンドにパイプする場合、一部のシェル環境では $MATON_API_KEY のような環境変数が正しく展開されないことがあります。パイプ処理時に「無効なAPIキー」エラーが発生する可能性があります。

---

エラーハンドリング

ステータス	意味
400	Google Docs接続がない、またはリクエストペイロードの形式が不正です
401	Maton APIキーが無効または見つかりません
404	Google Doc IDが見つからないか、アクセスが拒否されました
429	レート制限を超えました
5xx	Google Docs APIバックエンドエラー

トラブルシューティング: APIキーの問題

CLI:

maton whoami
maton connection list google-docs

手動:

echo $MATON_API_KEY
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

トラブルシューティング: 無効なアプリ名

1. URLパスが google-docs で始まっていることを確認してください。例:

• 正しい: https://api.maton.ai/google-docs/v1/documents/<documentId>
• 間違い: https://api.maton.ai/docs/v1/documents/<documentId>

---

リソース

• Google Docs REST API v1 ドキュメント
• Google Docs バッチ更新リファレンス
• Maton CLI Google Docs マニュアル
• Maton コミュニティ
• Maton サポート