Node-thumbnails
Een datanode (divisie, site, map, twin en de rest van de hiërarchie) kan een thumbnailafbeelding hebben. Deze pagina behandelt het uploaden, vervangen en verwijderen van die thumbnail, en de kosten en levensduur van de ondertekende URL die u terugkrijgt wanneer u erom vraagt.
Een thumbnail uploaden
Section titled “Een thumbnail uploaden”| Methode | Pad | Beschrijving |
|---|---|---|
POST | /v1/nodes/{nodeId}/thumbnail | Initiëren: retourneert een upload-id en een vooraf ondertekende S3-URL |
POST | /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize | Finaliseren: past de geüploade afbeelding toe als de thumbnail van de node |
DELETE | /v1/nodes/{nodeId}/thumbnail | Verwijderen: verwijdert de huidige thumbnail |
Alle drie vereisen write:hierarchy en zijn gemarkeerd als experimenteel. Zie Experimentele endpoints.
Dit is dezelfde initiëren/uploaden/finaliseren-vorm die door meerdere andere upload-endpoints van de RealityConnect API wordt gebruikt. Zie de Referentie: gedeelde multipart-upload voor het volledige mechanisme. Node-thumbnails zijn het eenvoudige, enkelbestandsgeval van dat patroon: initiëren neemt geen request-body en retourneert precies één vooraf ondertekende URL, zonder partNumber en zonder refresh-endpoint. Doe een PUT van de afbeelding naar die URL en roep vervolgens finalize aan om deze toe te passen. Als de URL verloopt voordat u hebt geüpload, initieer dan opnieuw om een nieuwe te krijgen: er is niets om te vernieuwen.
DELETE /v1/nodes/{nodeId}/thumbnail is idempotent: het retourneert 204, ongeacht of de node een thumbnail had of niet.
Geaccepteerde formaten en groottelimieten
Section titled “Geaccepteerde formaten en groottelimieten”Initiëren neemt geen body. Anders dan bij sommige andere upload-flows van de API declareert u vooraf geen bestandsnaam, grootte of content-type. De API zelf documenteert of handhaaft geen toegestane lijst van afbeeldingsformaten of een maximale bestandsgrootte; een bestand dat de downstream afbeeldingsverwerker niet kan decoderen, mislukt bij het finaliseren, niet bij de PUT-stap. Behandel elke niet-204-respons van finalize als “dit bestand werkte niet” en geef dat door aan de aanroeper, in plaats van aan te nemen dat elke afbeelding die u kunt PUT-en wordt geaccepteerd.
Een thumbnail terugkrijgen
Section titled “Een thumbnail terugkrijgen”GET /v1/nodes/{id}/browse en GET /v1/nodes/search accepteren beide includeThumbnail=true (standaard false). Indien ingesteld, krijgt elke node in de respons een veld thumbnailSignedUrl: null wanneer de node geen thumbnail heeft, een ondertekende URL wanneer dat wel zo is. Zie Knooptypen en hiërarchie voor de rest van de DataNode-vorm.
includeThumbnail staat standaard op false omdat het niet gratis is: het genereren en ondertekenen van een URL is extra werk per node, uitgevoerd voor elk item op de pagina, niet alleen voor de items die de aanroeper daadwerkelijk weergeeft. Dit opvragen bij een browse- of search-aanroep die al dicht bij de paginagroottelimiet zit (20 voor browse, 50 voor search) betekent dat u die kosten voor de hele pagina betaalt. Vraag het alleen op bij de weergave die daadwerkelijk afbeeldingen toont, niet bij een bulklijst of een achtergrondsynchronisatie van de boom.
Levensduur van de ondertekende URL
Section titled “Levensduur van de ondertekende URL”thumbnailSignedUrl is een vooraf ondertekende link, en RCAPI publiceert of configureert niet hoe lang deze geldig blijft. Behandel hem daarom als kortstondig en ondoorzichtig, niet als een duurzame identificatie. Cache een thumbnailSignedUrl niet voorbij de respons die hem heeft geretourneerd. Als uw integratie browse- of search-resultaten cachet om ze later opnieuw weer te geven, haal ze dan opnieuw op met includeThumbnail=true om een actuele URL te krijgen in plaats van een opgeslagen URL te hergebruiken: een opgeslagen URL zal uiteindelijk niet meer worden omgezet en levert dan een dode afbeeldingslink op, zonder enige waarschuwing in de rest van de respons.
Thumbnails en zacht verwijderen
Section titled “Thumbnails en zacht verwijderen”Het zacht verwijderen van een node (DELETE /v1/nodes/{nodeId}) verplaatst deze naar de prullenbak zonder de thumbnail aan te raken. GET /v1/trash accepteert dezelfde includeThumbnail=true en retourneert voor een node in de prullenbak dezelfde thumbnailSignedUrl die browse en search vóór de verwijdering zouden hebben geretourneerd. Het herstellen van de node (PATCH /v1/nodes/{nodeId}/restore) maakt deze weer doorzoekbaar en vindbaar met de thumbnail intact; er hoeft niets opnieuw te worden geüpload. Het definitief verwijderen van de node (DELETE /v1/nodes/{nodeId}/hard), of het verstrijken van de bewaartermijn van 30 dagen in de prullenbak, verwijdert de thumbnail samen met al het andere op de node. Zie Wat verwijderen echt doet, per resource voor het volledige model van verwijderen/herstellen/definitief verwijderen.
Wat is de volgende stap?
Section titled “Wat is de volgende stap?”- Referentie: gedeelde multipart-upload voor het volledige initiëren/uploaden/finaliseren-mechanisme.
- Knooptypen en hiërarchie voor de volledige
DataNode-vorm en de veldreferentie van browse/search. - Wat verwijderen echt doet, per resource voor het gedrag van zacht verwijderen, herstellen en definitief verwijderen bij elke resource.