Sheets mit Agenten lesen und bearbeiten

Nutze stabile IDs, begrenzte Lesezugriffe und bedingte Änderungen für gemeinsame Sheets.

Diese Schritte gelten für die öffentliche API, verbundene MCP-Clients und den App-Assistenten. Lies vor der Ausführung die aktuellen Deskriptoren; Beispiele verwenden beispielhafte IDs und Versionen.

Erst Struktur, dann Daten lesen

Finde das Sheet über sheets.list oder workspace.search.
Lies sheets.get für Spalten-IDs, Typen, Auswahloptions-IDs und Metadatenversionen.
Frage mit sheets.query nur relevante Zeilen und Spalten ab. Nutze sheets.aggregate für Zählungen und Aggregate, statt das gesamte Sheet herunterzuladen.
Folge den opaken nextCursor-Werten und verwende die zurückgegebene snapshotRevision als expectedRevision auf weiteren Seiten. Halte die Abfrage beim Blättern unverändert.

Eingabe für die erste Seite

json

{  "sheetId": "11111111-1111-4111-8111-111111111111",  "columnIds": null,  "expectedRevision": null,  "query": {    "cursor": null,    "direction": "forward",    "filters": [],    "focusRowId": null,    "history": false,    "pageSize": 100,    "q": null,    "sort": [],    "version": null  }}

{  "sheetId": "11111111-1111-4111-8111-111111111111",  "columnIds": null,  "expectedRevision": null,  "query": {    "cursor": null,    "direction": "forward",    "filters": [],    "focusRowId": null,    "history": false,    "pageSize": 100,    "q": null,    "sort": [],    "version": null  }}

Die Antwort trennt page.rows und dünn besetzte page.cells. Zellen enthalten rowId, columnId, rawValue, projectedValue und entityVersion; die Zeilenposition ist keine Identität. Eine Zelle kann zusätzlich Anreicherungsstatus enthalten. Frage relevante Sheet-Zeilen erneut ab, um den aktuellen Fortschritt zu sehen; prüfe Vorschläge bei Bedarf mit sheets.get_enrichment_proposals.

Bedingte Änderungen durchführen

Nutze sheets.update_cells für typisierte Zelländerungen. Sende die aktuelle entityVersion als expectedVersion; verwende "0" nur für eine nicht vorhandene Zelle. Auswahlwerte verwenden Options-IDs. Strukturelle Änderungen verlangen die Sheet-, Spalten-, Ansichts- oder Reihenfolgeversion ihres Schemas.

Eingabe für eine Zelländerung

json

{  "sheetId": "11111111-1111-4111-8111-111111111111",  "idempotencyKey": "review-cell-example-001",  "patches": [    {      "rowId": "22222222-2222-4222-8222-222222222222",      "columnId": "33333333-3333-4333-8333-333333333333",      "expectedVersion": "12",      "rawValue": "Reviewed"    }  ]}

{  "sheetId": "11111111-1111-4111-8111-111111111111",  "idempotencyKey": "review-cell-example-001",  "patches": [    {      "rowId": "22222222-2222-4222-8222-222222222222",      "columnId": "33333333-3333-4333-8333-333333333333",      "expectedVersion": "12",      "rawValue": "Reviewed"    }  ]}

Das Beispiel setzt eine Textspalte und Version 12 voraus. Ersetze alle IDs und die Version durch aktuelle Leseergebnisse. Ein Update nimmt höchstens 500 Änderungen an. Ein erfolgreicher Batch ist atomar; getrennte Batches können unabhängig gespeichert werden. Lies bei einem Konflikt den aktuellen Stand und gleiche ihn ab; sende die neu beabsichtigte Änderung mit einem neuen Schlüssel. Entferne die Versionsprüfung nicht, um einen alten Wert über eine neuere Änderung eines anderen Mitglieds zu schreiben.

Bewahre Operations-ID, Revision und Changeset-ID auf, soweit vorhanden. Für exakte Wiederaufnahme gelten derselbe Schlüssel und derselbe Body; neue Arbeit braucht einen neuen Schlüssel. Auch Undo ist bedingt: Prüfe den Ausgang, statt anzunehmen, dass spätere Änderungen zurückgesetzt wurden.

Die passende Operation wählen

Aufgabe	Operationsfamilie
Sheets erstellen, umbenennen, verschieben, duplizieren oder archivieren	`sheets.create`, `sheets.rename`, `sheets.move_to_folder`, `sheets.duplicate`, `sheets.archive`
Datensätze einfügen, Zeilen verschieben, Zellen ändern oder Zeilen entfernen	`sheets.insert_records`, `sheets.move_rows`, `sheets.update_cells`, `sheets.delete_rows`
Spalten, Auswahloptionen oder Typumwandlungen konfigurieren	Entdecke die Spaltenoperationen unter `sheets` und ihre aktuellen Deskriptoren.
Gemeinsame Ansichten verwalten	`sheets.create_view`, `sheets.update_view`, `sheets.reorder_views`, `sheets.delete_view`
Zellen recherchieren und Vorschläge prüfen	`sheets.start_enrichment`, `sheets.cancel_enrichment`, `sheets.get_enrichment_proposals`, `sheets.review_enrichment_proposals`
Historie prüfen oder wiederherstellen, Zugriff verwalten	Entdecke die Historien-, Versions- und Freigabeoperationen deiner Rolle.

Das Erstellen einer gespeicherten Ansicht wechselt nicht den aktuellen Tab der Person. Ausgeblendete Spalten sind Darstellungszustand und bleiben zugänglich; Ausblenden ist keine Zugriffskontrolle.

Dateien und größere Auswertungen

sheets.export_csv liefert einen revisionskonsistenten, begrenzten CSV-Snapshot. Setze maxBytes und prüfe das Ergebnis; diese Operation ist auf 1 MiB begrenzt. Eine Änderung an der heruntergeladenen CSV aktualisiert nicht das Live-Sheet. Wende ausgewählte Änderungen über die kanonischen Operationen an.

Der gehostete Assistent bietet zusätzlich ausführungsgebundene Helfer zur rein lesenden Sheet-Auswertung. Externe MCP-Clients können begrenzte Abfrageergebnisse oder Exporte mit eigenen Werkzeugen analysieren. Beide Wege sollten das Live-Sheet nicht durch einen unversionierten Datei-Upload ersetzen.

Bewahre bei kostenpflichtiger Arbeit Lauf- und Anfragekennungen auf, prüfe Endergebnisse und berücksichtige ungeklärte Abrechnung. Leadbase steuert Kapazität und Anbieter. Siehe Anreicherung, API-Wiederaufnahme und den portablen Agenten-Skill.