Fize/workspace-kit

Google Docs (Cloud-Dokument-Fähigkeit)

Greifen Sie mit verwalteter OAuth-Authentifizierung über Maton auf die Google Docs API zu. Erstellen, lesen, aktualisieren, formatieren und bearbeiten Sie Google Docs-Clouddokumente in Stapelverarbeitung.

⚠️ Abgrenzung Cloud vs. Lokale Datei:

• google-docs (Diese Fähigkeit): Ausschließlich für Online-Google-Docs-Clouddokumente (docs.google.com/document/d/{documentId}). Interagiert direkt mit den Cloud-Servern von Google über den Maton OAuth-API-Proxy.
• docx-Fähigkeit: Zum Lesen, Erstellen oder Bearbeiten von lokalen .docx- / .doc-Dateien auf der lokalen Festplatte.

---

Schnellstart

CLI:

# Dokumentenstruktur & Textinhalt abrufen
maton google-docs document get <documentId>

# Ein neues Google Doc erstellen
maton google-docs document create --title 'Projektarchitektur-Spezifikation'

# Text an den Dokumenttext anhängen
maton google-docs document write <documentId> --text 'Besprechungsnotizen: Diskussion über Q3-Roadmap.'

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

---

Basis-URL

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

Maton proxyt Anfragen an docs.googleapis.com und fügt automatisch Ihr OAuth-Token ein.

---

CLI-Installation (optional – Agent entscheidet)

Die Maton-CLI ist optional. Der Agent kann je nach Umgebung entscheiden, ob sie installiert wird.

macOS / Linux

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

Windows

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

npm (plattformübergreifend)

npm install -g @maton/cli

Homebrew (macOS)

brew install maton-ai/cli/maton

Nach der Installation mit folgendem Befehl überprüfen:

maton --version

---

Authentifizierung

CLI:

maton login                          # Öffnet Browser für API-Schlüssel
maton login --interactive            # Browser überspringen, API-Schlüssel direkt einfügen
maton whoami                         # Zeigt aktuellen Authentifizierungsstatus an

Manuell:

1. Melden Sie sich an oder erstellen Sie ein Konto unter maton.ai
2. Gehen Sie zu maton.ai/settings
3. Kopieren Sie Ihren API-Schlüssel
4. Setzen Sie Ihren API-Schlüssel als MATON_API_KEY:

export MATON_API_KEY="IHR_API_SCHLÜSSEL"

---

Verbindungsverwaltung

Verwalten Sie Ihre Google Docs OAuth-Verbindungen unter https://api.maton.ai.

Verbindungen auflisten

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

Verbindung erstellen

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

Antwort:

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

Öffnen Sie die zurückgegebene url in einem Browser, um die OAuth-Autorisierung abzuschließen.

Verbindung abrufen

CLI:

maton connection get {connection_id}                 # Alias: maton connection view

maton api /connections/{connection_id}

Verbindung löschen

CLI:

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

Verbindung angeben

Wenn Sie mehrere Google Docs-Verbindungen haben, geben Sie an, welche verwendet werden soll:

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

Wenn Sie mehrere Verbindungen haben, geben Sie immer die Verbindung an, um sicherzustellen, dass Anfragen zum gewünschten Konto gehen.

---

Sicherheit & Berechtigungen

• Der Zugriff ist auf Google Docs im verbundenen Google-Konto beschränkt.
• Alle Schreib- und Löschvorgänge erfordern eine explizite Benutzerfreigabe. Bestätigen Sie die Zielressourcen-ID und die Inhaltsänderungen mit dem Benutzer, bevor Sie sie ausführen.

---

API-Referenz

1. Dokument abrufen

Ruft das vollständige Dokumentobjekt einschließlich Titel, Strukturelementen, Inline-Objekten und Absatzformatierung ab.

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

Abfrageparameter:

• suggestionsViewMode - DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_APPROVED, PREVIEW_WITHOUT_SUGGESTIONS, SUGGESTIONS_INLINE.

Beispiel CLI:

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

---

2. Leeres Dokument erstellen

Erstellt ein neues leeres Google Doc mit einem angegebenen Titel.

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

{
  "title": "Technisches Quartalsreview"
}

Beispiel CLI:

maton google-docs document create --title 'Technisches Quartalsreview'

---

3. Nur-Text an Dokument anhängen

Hängt über die CLI Nur-Text an das Ende eines Dokumententexts an.

Beispiel CLI:

# Direkter Text
maton google-docs document write <documentId> --text 'Hallo, Welt!'

# Aus einer Datei lesen
maton google-docs document write <documentId> -F notizen.md

# Von stdin pipen
echo 'Zusammengefasste Pipe' | maton google-docs document write <documentId> -F -

---

4. Batch-Update des Dokumentinhalts & der Struktur (Reichhaltige Formatierung)

Führt atomare Änderungen an Dokumenttext, Formatierung, Absatzstilen, Kopf-/Fußzeilen und Inline-Tabellen durch.

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

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Executive Summary\n\nDieses Dokument beschreibt unsere Cloud-Migrationsstrategie."
      }
    }
  ]
}

Beispiel CLI:

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

Häufige Anfragetypen für batchUpdate:

1. insertText: Text an einer bestimmten Indexposition einfügen.
2. deleteContentRange: Inhalt innerhalb eines angegebenen range (startIndex und endIndex) löschen.
3. replaceAllText: Globales Suchen und Ersetzen von Text im gesamten Dokumenttext.

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

4. updateTextStyle: Fett, kursiv, Schriftgröße oder Farbformatierung auf einen Bereich anwenden.
5. updateParagraphStyle: Überschriftenstile (HEADING_1, HEADING_2, NORMAL_TEXT) anwenden.

---

Nur-Text aus Dokumentstruktur extrahieren

Die Google Docs API gibt Inhalt in body.content als Strukturelemente zurück. So lesen Sie den Nur-Text eines Dokuments über 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))

---

Codebeispiele

CLI

# Ein Dokument erstellen
maton google-docs document create --title 'Sprint Planung'

# Erste Notizen in das Dokument schreiben
maton google-docs document write <documentId> --text 'Sprint 42 Ziele:\n- Auth starten\n- Geschwindigkeitstests'

# Dokumentenstruktur in JSON überprüfen
maton google-docs document get <documentId> --json

JavaScript

// Dokumentenmetadaten und -inhalt abrufen
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);

// Ein neues Dokument erstellen
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 Skill Gateway'
    })
  }
);
const newDoc = await createResponse.json();
console.log('Erstellte Dok.-ID:', newDoc.documentId);

Python

import os
import requests

# Dokument abrufen
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'))

# Dokument erstellen
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 Skill Gateway'}
)
print('Erstellt:', create_response.json().get('documentId'))

---

Hinweise

• Dokumenten-IDs sind undurchsichtige Zeichenfolgen (aus der URL extrahiert: https://docs.google.com/document/d/<documentId>/edit).
• maton google-docs document write hängt Nur-Text an das Ende des Dokumententexts an. Zum Einfügen von Text an bestimmten Indizes, Ersetzen von Text oder Anwenden von Überschriften-/Fettformatierungen verwenden Sie batchUpdate.
• WICHTIG: Wenn Sie curl-Befehle verwenden, verwenden Sie curl -g, wenn URLs eckige Klammern enthalten, um die Glob-Parsing zu deaktivieren.
• WICHTIG: Wenn Sie die curl-Ausgabe an jq oder andere Befehle weiterleiten, werden Umgebungsvariablen wie $MATON_API_KEY in manchen Shell-Umgebungen möglicherweise nicht korrekt erweitert. Bei Verwendung von Pipes können „Ungültiger API-Schlüssel“-Fehler auftreten.

---

Fehlerbehandlung

Status	Bedeutung
400	Fehlende Google Docs-Verbindung oder fehlerhafte Anfrage-Payload
401	Ungültiger oder fehlender Maton API-Schlüssel
404	Google Doc-ID nicht gefunden oder Zugriff verweigert
429	Rate-Limit überschritten
5xx	Backend-Fehler der Google Docs API

Fehlerbehebung: Probleme mit dem API-Schlüssel

CLI:

maton whoami
maton connection list google-docs

Manuell:

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

Fehlerbehebung: Ungültiger App-Name

1. Stellen Sie sicher, dass Ihr URL-Pfad mit google-docs beginnt. Zum Beispiel:

• Richtig: https://api.maton.ai/google-docs/v1/documents/<documentId>
• Falsch: https://api.maton.ai/docs/v1/documents/<documentId>

---

Ressourcen

• Google Docs REST API v1 Docs
• Google Docs Batch Update Reference
• Maton CLI Google Docs Manual
• Maton Community
• Maton Support