Knoten-Thumbnails
Ein Datenknoten (Division, Site, Ordner, Twin und der Rest der Hierarchie) kann ein Thumbnail-Bild tragen. Diese Seite behandelt das Hochladen, Ersetzen und Entfernen dieses Thumbnails sowie die Kosten und die Lebensdauer der signierten URL, die Sie zurückerhalten, wenn Sie danach fragen.
Ein Thumbnail hochladen
Abschnitt betitelt „Ein Thumbnail hochladen“| Methode | Pfad | Beschreibung |
|---|---|---|
POST | /v1/nodes/{nodeId}/thumbnail | Initiieren: liefert eine Upload-ID und eine vorsignierte S3-URL |
POST | /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize | Finalisieren: wendet das hochgeladene Bild als Thumbnail des Knotens an |
DELETE | /v1/nodes/{nodeId}/thumbnail | Entfernen: löscht das aktuelle Thumbnail |
Alle drei erfordern write:hierarchy und sind als experimentell gekennzeichnet. Siehe Experimentelle Endpunkte.
Dies ist dieselbe Initiieren/Hochladen/Finalisieren-Form, die von mehreren anderen Upload-Endpunkten der RealityConnect API verwendet wird. Die vollständige Mechanik finden Sie in der Referenz: Gemeinsamer Multipart-Upload. Knoten-Thumbnails sind der einfache Einzeldatei-Fall dieses Musters: Das Initiieren nimmt keinen Request-Body entgegen und liefert genau eine vorsignierte URL, ohne partNumber und ohne Refresh-Endpunkt. Führen Sie ein PUT des Bilds an diese URL aus und rufen Sie dann finalize auf, um es anzuwenden. Läuft die URL ab, bevor Sie hochgeladen haben, initiieren Sie erneut, um eine neue zu erhalten; es gibt nichts zu aktualisieren.
DELETE /v1/nodes/{nodeId}/thumbnail ist idempotent: Der Aufruf liefert 204, unabhängig davon, ob der Knoten ein Thumbnail hatte oder nicht.
Akzeptierte Formate und Größenbeschränkungen
Abschnitt betitelt „Akzeptierte Formate und Größenbeschränkungen“Das Initiieren nimmt keinen Body entgegen. Anders als bei manchen anderen Upload-Flows der API geben Sie Dateiname, Größe oder Content-Type nicht vorab an. Die API dokumentiert oder erzwingt selbst keine Zulassungsliste für Bildformate oder eine maximale Dateigröße; eine Datei, die der nachgelagerte Bildprozessor nicht dekodieren kann, schlägt bei der Finalisierung fehl, nicht beim PUT-Schritt. Behandeln Sie jede Nicht-204-Antwort von finalize als „diese Datei hat nicht funktioniert“ und geben Sie das an den Aufrufer weiter, statt anzunehmen, dass jedes Bild, das Sie per PUT hochladen können, auch akzeptiert wird.
Ein Thumbnail abrufen
Abschnitt betitelt „Ein Thumbnail abrufen“GET /v1/nodes/{id}/browse und GET /v1/nodes/search akzeptieren beide includeThumbnail=true (Standard false). Ist das gesetzt, erhält jeder Knoten in der Antwort ein Feld thumbnailSignedUrl: null, wenn der Knoten kein Thumbnail hat, eine signierte URL, wenn er eines hat. Den Rest der DataNode-Form finden Sie unter Knotentypen und Hierarchie.
includeThumbnail ist standardmäßig false, weil es nicht kostenlos ist: Das Erzeugen und Signieren einer URL ist zusätzlicher Aufwand pro Knoten, der für jedes Element der Seite anfällt, nicht nur für die, die der Aufrufer tatsächlich darstellt. Wird es bei einem browse- oder search-Aufruf angefordert, der bereits nahe an seinem Seitengrößenlimit liegt (20 bei browse, 50 bei search), bedeutet das, diese Kosten für die gesamte Seite zu zahlen. Fordern Sie es nur bei der Ansicht an, die tatsächlich Bilder darstellt, nicht bei einer Massenauflistung oder einer Hintergrundsynchronisierung des Baums.
Lebensdauer der signierten URL
Abschnitt betitelt „Lebensdauer der signierten URL“thumbnailSignedUrl ist ein vorsignierter Link, und die RCAPI veröffentlicht oder konfiguriert nicht, wie lange er gültig bleibt. Behandeln Sie ihn deshalb als kurzlebig und undurchsichtig, nicht als dauerhaften Bezeichner. Cachen Sie ein thumbnailSignedUrl nicht über die Antwort hinaus, die es geliefert hat. Wenn Ihre Integration browse- oder search-Ergebnisse cacht und später erneut darstellt, holen Sie sie mit includeThumbnail=true erneut ab, um eine aktuelle URL zu erhalten, statt eine gespeicherte URL wiederzuverwenden: Eine gespeicherte URL wird irgendwann nicht mehr aufgelöst und liefert einen toten Bildlink, ohne dass der Rest der Antwort davor warnt.
Thumbnails und Soft-Delete
Abschnitt betitelt „Thumbnails und Soft-Delete“Ein Soft-Delete eines Knotens (DELETE /v1/nodes/{nodeId}) verschiebt ihn in den Papierkorb, ohne sein Thumbnail anzutasten. GET /v1/trash akzeptiert dasselbe includeThumbnail=true und liefert für einen Knoten im Papierkorb dieselbe thumbnailSignedUrl, die browse und search vor der Löschung geliefert hätten. Das Wiederherstellen des Knotens (PATCH /v1/nodes/{nodeId}/restore) macht ihn mit intaktem Thumbnail wieder durchsuchbar und auffindbar; nichts muss erneut hochgeladen werden. Das endgültige Löschen des Knotens (DELETE /v1/nodes/{nodeId}/hard), oder das Ablaufen der 30-tägigen Aufbewahrungsfrist im Papierkorb, entfernt das Thumbnail zusammen mit allem anderen am Knoten. Das vollständige Lösch-/Wiederherstellungs-/Bereinigungsmodell finden Sie unter Was Löschen wirklich bedeutet, je Ressource.
Wie geht es weiter?
Abschnitt betitelt „Wie geht es weiter?“- Referenz: Gemeinsamer Multipart-Upload für die vollständige Initiieren/Hochladen/Finalisieren-Mechanik.
- Knotentypen und Hierarchie für die vollständige
DataNode-Form und die Feldreferenz für browse/search. - Was Löschen wirklich bedeutet, je Ressource für das Verhalten von weichem Löschen, Wiederherstellen und Bereinigen über alle Ressourcen hinweg.