Werkzeuge bauen

Dateien, Mail und Personen

Dateien in Buckets ablegen, Mail senden, Personen nachschlagen und die eigenen Rechte lesen.

Neben den Collections bietet die Schnittstelle vier weitere Dinge: Buckets für Dateien, den Mailversand, das Personenverzeichnis und die Auskunft über die angemeldete Person. Für alle gelten dieselben Regeln wie für Daten: Sitzungscookie, Content-Type: application/json bei einem JSON-Rumpf, dieselbe Form der Fehlerantwort (Daten lesen und schreiben).

Trage in tool.json unter uses ein, was dein Werkzeug davon braucht: den Bucket unter buckets, mail.send und people.read unter capabilities.

Dateien in einem Bucket

Ein Bucket hält Dateien. Er steht neben den Collections, nie in einer. Der Agent legt ihn mit ensure_bucket an. Rechte hängen wie bei Daten an einer Rolle, mit den Stufen none, own und all für Lesen und Schreiben. own meint die Dateien, die die Person selbst hochgeladen hat.

Dateien liegen je Datenraum, wie Datensätze: Der Bucket ist in beiden Räumen derselbe, sein Bestand nicht. Ein Werkzeug sieht im Übungsraum nur die Dateien, die dort hochgeladen wurden, siehe Produktion und Übungsraum.

Eine Datei hochladen

Die Bytes stehen im Rumpf, der Name im Kopf X-File-Name, prozentkodiert. Multipart nimmt die Instanz nicht an.

fetch("/api/buckets/belege/files", {
  method: "POST",
  credentials: "same-origin",
  headers: {
    "Content-Type": file.type,
    "X-File-Name": encodeURIComponent(file.name)
  },
  body: file                       // das File-Objekt aus einem <input type="file">
});

Die Antwort ist 201 mit id, name, mediaType, bytes und checksum.

Grenzen

• Die Vorgabe ist 25 MB je Datei und 1 GB je Bucket. Das Kontingent zählt je Datenraum.
• Die Instanz nimmt nur bestimmte Dateiarten an. Die Vorgabe: PDF, PNG, JPEG, GIF, WebP, Text, CSV, ZIP, JSON, Word (.docx) und Excel (.xlsx).
• Die Instanz prüft den genannten Inhaltstyp an den ersten Bytes. Eine Datei, die .png heisst und keines ist, weist sie ab.
• Jeder Download kommt als Anhang. Ein abgelegtes Bild lässt sich deshalb nicht mit <img src> anzeigen.
• Ein Bucket lässt sich nicht löschen, seine Dateien schon.

Mail senden

POST /api/mail sendet eine Nachricht. Die Person braucht dafür die Fähigkeit mail.send über eine ihrer Rollen.

{
  "to": ["vera@example.com"],
  "subject": "Neue Aufgabe für dich",
  "text": "Du hast eine neue Aufgabe: Angebot prüfen.",
  "replyTo": "empfang@example.com"
}

• Pflicht sind mindestens ein Empfänger, ein Betreff und ein Inhalt: text, html oder beides. cc und bcc sind Listen wie to.
• Der Betreff ist eine Zeile mit höchstens 200 Zeichen.
• Der Absender ist je Instanz fest. Ein Werkzeug wählt ihn nicht. replyTo kannst du setzen.
• Die Vorgabe ist höchstens 50 Empfänger je Nachricht und 200 Nachrichten je Stunde für die ganze Instanz.
• Der Versand läuft sofort: 202 mit {"sent": true} heisst, die Nachricht ist draussen. Bei einem Fehler ging nichts hinaus.
• Die Instanz protokolliert jede Nachricht.

Personen nachschlagen

Lass niemanden einen Namen tippen. Suche im Verzeichnis und speichere die Kennung in einem Feld vom Typ person. Die Person braucht die Fähigkeit people.read. Auch sie ist kein Teil der Adminrechte.

{"term": "ver", "limit": 50}

POST /api/people/query antwortet:

{"people": [{"id": "…", "name": "Vera Beispiel", "email": "vera@example.com"}],
 "total": 1, "hasMore": false}

GET /api/people/<id> macht aus einer gespeicherten Kennung wieder einen Namen. Im Verzeichnis steht, wer sich mindestens einmal angemeldet hat und nicht deaktiviert ist.

Wer angemeldet ist

GET /api/me nennt die angemeldete Person und ihre wirksamen Rechte:

{
  "userId": "4b40b106-…",
  "name": "Alex Admin",
  "admin": true,
  "roles": ["admin", "demo"],
  "collections": [{"collection": "aufgaben", "read": "all", "write": "all"}],
  "buckets": [{"bucket": "task_files", "read": "all", "write": "all"}],
  "capabilities": ["people.read", "mail.send"],
  "tools": ["tasklist"],
  "contexts": []
}

Nutze die Antwort für „meine Aufgaben“ (created_by gleich userId) und um Knöpfe auszublenden, die die Person nicht benutzen darf. Das Ausblenden ist Komfort: Die Instanz prüft jedes Recht bei jeder Anfrage selbst.