Fize/workspace-kit

Google Docs (Compétence Document Cloud)

Accédez à l'API Google Docs avec une authentification OAuth gérée via Maton. Créez, lisez, mettez à jour, formatez et modifiez par lots des documents cloud Google Docs.

⚠️ Distinction entre le cloud et le champ d'application des fichiers locaux :

• google-docs (Cette compétence) : Exclusivement pour les documents cloud Google Docs en ligne (docs.google.com/document/d/{documentId}). Interagit directement avec les serveurs cloud de Google via le proxy d'API OAuth Maton.
• Compétence docx : Pour la lecture, la création ou la modification de fichiers .docx / .doc locaux stockés sur le disque local.

---

Démarrage rapide

CLI :

# Obtenir la structure du document et le contenu textuel
maton google-docs document get <documentId>

# Créer un nouveau Google Doc
maton google-docs document create --title 'Spécification d'architecture du projet'

# Ajouter du texte au corps d'un document
maton google-docs document write <documentId> --text 'Notes de réunion : discussion sur la feuille de route du 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 de base

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

Maton transmet les requêtes à docs.googleapis.com et injecte automatiquement votre jeton OAuth.

---

Installation de la CLI (facultative — l'agent décide)

La CLI Maton est facultative. L'agent peut décider de l'installer en fonction de l'environnement.

macOS / Linux

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

Windows

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

npm (multi-plateforme)

npm install -g @maton/cli

Homebrew (macOS)

brew install maton-ai/cli/maton

Après l'installation, vérifiez avec :

maton --version

---

Authentification

CLI :

maton login                          # Ouvre le navigateur pour la clé API
maton login --interactive            # Ignore le navigateur, collez la clé API directement
maton whoami                         # Affiche l'état actuel de l'authentification

Manuelle :

1. Connectez-vous ou créez un compte sur maton.ai
2. Allez sur maton.ai/settings
3. Copiez votre clé API
4. Définissez votre clé API comme MATON_API_KEY :

export MATON_API_KEY="VOTRE_CLÉ_API"

---

Gestion des connexions

Gérez vos connexions OAuth Google Docs sur https://api.maton.ai.

Lister les connexions

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

Créer une connexion

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

Réponse :

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

Ouvrez l'url retournée dans un navigateur pour terminer l'autorisation OAuth.

Obtenir une connexion

CLI :

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

maton api /connections/{connection_id}

Supprimer une connexion

CLI :

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

Spécifier une connexion

Si vous avez plusieurs connexions Google Docs, spécifiez laquelle utiliser :

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

Si vous avez plusieurs connexions, spécifiez toujours la connexion pour garantir que les requêtes sont envoyées au compte souhaité.

---

Sécurité et autorisations

• L'accès est limité aux Google Docs du compte Google connecté.
• Toutes les opérations d'écriture et de suppression nécessitent une approbation explicite de l'utilisateur. Confirmez l'ID de la ressource cible et les modifications de contenu avec l'utilisateur avant d'exécuter.

---

Référence de l'API

1. Obtenir le document

Récupérez l'objet document complet, y compris le titre, les éléments structurels, les objets en ligne et le style des paragraphes.

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

Paramètres de requête :

• suggestionsViewMode - DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_APPROVED, PREVIEW_WITHOUT_SUGGESTIONS, SUGGESTIONS_INLINE.

Exemple CLI :

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

---

2. Créer un document vierge

Créez un nouveau Google Doc vide avec un titre spécifié.

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

{
  "title": "Revue technique trimestrielle"
}

Exemple CLI :

maton google-docs document create --title 'Revue technique trimestrielle'

---

3. Ajouter du texte brut à un document

Ajoutez du texte brut à la fin du corps d'un document via la CLI.

Exemple CLI :

# Texte direct
maton google-docs document write <documentId> --text 'Bonjour tout le monde !'

# Lire à partir d'un fichier
maton google-docs document write <documentId> -F notes.md

# Canaliser depuis stdin
echo 'Résumé canalisé' | maton google-docs document write <documentId> -F -

---

4. Mise à jour par lots du contenu et de la structure du document (formatage riche)

Effectuez des mutations atomiques sur le texte du document, le formatage, les styles de paragraphe, les en-têtes/pieds de page et les tableaux en ligne.

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

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Résumé exécutif\n\nCe document décrit notre stratégie de migration vers le cloud."
      }
    }
  ]
}

Exemple CLI :

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

Types de requêtes courants pour batchUpdate :

1. insertText : Insérez du texte à un emplacement d'index spécifique.
2. deleteContentRange : Supprimez le contenu dans une range spécifiée (startIndex et endIndex).
3. replaceAllText : Recherche et remplacement global de texte dans le corps du document.

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

4. updateTextStyle : Appliquez un formatage gras, italique, taille de police ou couleur à une plage.
5. updateParagraphStyle : Appliquez des styles de titre (HEADING_1, HEADING_2, NORMAL_TEXT).

---

Extraction du texte brut à partir de la structure du document

L'API Google Docs renvoie le contenu dans body.content sous forme d'éléments structurels. Pour lire le texte brut d'un document via 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))

---

Exemples de code

CLI

# Créer un document
maton google-docs document create --title 'Planification du Sprint'

# Écrire les notes initiales dans le document
maton google-docs document write <documentId> --text 'Objectifs du Sprint 42 :\n- Lancer Auth\n- Tests de performance'

# Inspecter la structure du document en JSON
maton google-docs document get <documentId> --json

JavaScript

// Obtenir les métadonnées et le contenu du document
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);

// Créer un nouveau document
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 : Passerelle de compétences IA'
    })
  }
);
const newDoc = await createResponse.json();
console.log('ID du doc créé :', newDoc.documentId);

Python

import os
import requests

# Obtenir le document
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'))

# Créer un document
create_response = requests.post(
    'https://api.maton.ai/google-docs/v1/documents',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'title': 'RFC : Passerelle de compétences IA'}
)
print('Créé :', create_response.json().get('documentId'))

---

Remarques

• Les ID de document sont des chaînes opaques (extraites de l'URL https://docs.google.com/document/d/<documentId>/edit).
• maton google-docs document write ajoute du texte brut à la fin du corps du document. Pour insérer du texte à des index spécifiques, remplacer du texte ou appliquer des styles de titre/gras, utilisez batchUpdate.
• IMPORTANT : Lorsque vous utilisez des commandes curl, utilisez curl -g lorsque les URL contiennent des crochets pour désactiver l'analyse des globs.
• IMPORTANT : Lorsque vous canalisez la sortie de curl vers jq ou d'autres commandes, les variables d'environnement comme $MATON_API_KEY peuvent ne pas se développer correctement dans certains environnements de shell. Vous pouvez obtenir des erreurs "Clé API invalide" lors de la canalisation.

---

Gestion des erreurs

Statut	Signification
400	Connexion Google Docs manquante ou charge utile de requête mal formée
401	Clé API Maton invalide ou manquante
404	ID Google Doc introuvable ou accès refusé
429	Limite de débit dépassée
5xx	Erreur du backend de l'API Google Docs

Dépannage : Problèmes de clé API

CLI :

maton whoami
maton connection list google-docs

Manuel :

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

Dépannage : Nom d'application invalide

1. Assurez-vous que votre chemin d'URL commence par google-docs. Par exemple :

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

---

Ressources

• Documentation de l'API REST Google Docs v1
• Référence de mise à jour par lots de Google Docs
• Manuel de la CLI Maton pour Google Docs
• Communauté Maton
• Support Maton