Ondersteuning voor contentfragmenten in HTTP-API van AEM Assets content-fragments-support-in-aem-assets-http-api
Overzicht overview
Leer over steun voor de Fragments van de Inhoud in de API van Activa HTTP, een belangrijk stuk van AEM koploze leveringseigenschap.
- REST-API voor middelen
- inclusief ondersteuning voor inhoudsfragmenten
De REST-API voor middelen Hiermee kunnen ontwikkelaars voor Adobe Experience Manager inhoud (opgeslagen in AEM) direct via de HTTP-API benaderen via CRUD-bewerkingen (Maken, Lezen, Bijwerken, Verwijderen).
Met de API kunt u Adobe Experience Manager gebruiken als een CMS zonder kop (Content Management System) door Content Services aan te bieden voor een JavaScript front-end toepassing. Of elke andere toepassing die HTTP-aanvragen kan uitvoeren en JSON-reacties kan verwerken.
Toepassingen voor één pagina (SPA), die zijn gebaseerd op een framework of die zijn aangepast, vereisen bijvoorbeeld inhoud die via de HTTP-API wordt aangeboden, vaak in de JSON-indeling.
while AEM kerncomponenten Verstrek een zeer uitvoerige, flexibele en klantgerichte API die vereiste Gelezen verrichtingen voor dit doel kan dienen, en de waarvan output JSON kan worden aangepast, vereisen zij AEM WCM (het Beheer van de Inhoud van het Web) knowhow voor implementatie aangezien zij in pagina's moeten worden ontvangen die op specifieke AEM malplaatjes gebaseerd zijn. Niet elke SPA ontwikkelingsorganisatie heeft directe toegang tot deze kennis.
Dit is wanneer de REST API van Activa kan worden gebruikt. Ontwikkelaars hebben direct toegang tot elementen (bijvoorbeeld afbeeldingen en inhoudsfragmenten), zonder dat ze eerst in een pagina moeten worden ingesloten en hun inhoud in geserialiseerde JSON-indeling moeten leveren.
Met de REST API voor middelen kunnen ontwikkelaars ook inhoud wijzigen door nieuwe elementen, inhoudsfragmenten en mappen te maken, bij te werken of te verwijderen.
De REST-API voor middelen:
-
volgt HATEOAS-beginsel
-
implementeert de SIREN-indeling
Vereisten prerequisites
De REST-API voor middelen is beschikbaar voor elke installatie van een recente AEM.
Belangrijke concepten key-concepts
De REST API-aanbiedingen voor middelen REST-style toegang tot elementen die zijn opgeslagen in een AEM instantie.
Het gebruikt de /api/assets
eindpunt en vereist de weg van de activa om tot het toegang te hebben (zonder het leiden /content/dam
).
- Dit betekent dat toegang tot het actief moet worden verkregen tegen:
/content/dam/path/to/asset
- U moet een aanvraag indienen:
/api/assets/path/to/asset
Bijvoorbeeld om /content/dam/wknd/en/adventures/cycling-tuscany
, verzoek /api/assets/wknd/en/adventures/cycling-tuscany.json
/api/assets
niet het gebruik van de.model
kiezer./content/path/to/page
doet het gebruik van de.model
kiezer.
De HTTP-methode bepaalt de uit te voeren bewerking:
- GET - om een JSON-representatie van een middel of een map op te halen
- POST - om nieuwe elementen of mappen te maken
- PUT - om de eigenschappen van een middel of een omslag bij te werken
- DELETE - om een middel of een omslag te schrappen
De exacte indeling van ondersteunde aanvragen wordt gedefinieerd in het dialoogvenster API-naslag documentatie.
Transactioneel gedrag transactional-behavior
Alle verzoeken zijn atomisch.
Dit betekent datwrite
) verzoeken kunnen niet worden gecombineerd tot één enkele transactie die als één enkele entiteit zou kunnen slagen of mislukken.
AEM (Middelen) REST API versus AEM componenten aem-assets-rest-api-versus-aem-components
(componenten die gebruikmaken van modellen voor schuiven)
Geoptimaliseerd voor gebruik in een toepassing voor één pagina (SPA) of in een andere (content consuming) context.
Kan ook lay-outgegevens bevatten.
Maken, lezen, bijwerken, verwijderen.
Met extra bewerkingen afhankelijk van het type entiteit.
Kan rechtstreeks worden benaderd.
Gebruikt de /api/assets
eindpunt, toegewezen aan /content/dam
(in de repository).
Een voorbeeldpad zou er als volgt uitzien: /api/assets/wknd/en/adventures/cycling-tuscany.json
Moet door een AEM component op een AEM pagina worden van verwijzingen voorzien.
Gebruikt de .model
om de JSON-representatie te maken.
Een voorbeeldpad zou er als volgt uitzien:/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
Er zijn meerdere opties mogelijk.
OAuth wordt voorgesteld; kan los van standaardopstelling worden gevormd.
Schrijftoegang richt zich gewoonlijk tot een auteurinstantie.
Lees kan ook naar een publicatie-instantie worden gestuurd.
Beveiliging security
Als de REST API van Middelen binnen een milieu zonder specifieke authentificatievereisten wordt gebruikt, moet AEM filter CORS correct worden gevormd.
In omgevingen met specifieke verificatievereisten wordt OAuth aanbevolen.
Beschikbare functies available-features
Inhoudsfragmenten zijn een specifiek type element, zie Werken met inhoudsfragmenten.
Zie voor meer informatie over functies die beschikbaar zijn via de API:
- De REST-API voor middelen
- Typen entiteiten, waarbij de specifieke kenmerken van elk ondersteund type (voor zover relevant voor inhoudsfragmenten) worden toegelicht
Paginering paging
De REST API voor middelen ondersteunt paginering (voor GET-aanvragen) via de URL-parameters:
offset
- het nummer van de eerste (onderliggende) entiteit die moet worden opgehaaldlimit
- het maximumaantal geretourneerde entiteiten
De reactie zal het pagineren informatie als deel van bevatten properties
van de SIREN-uitvoer. Dit srn:paging
eigenschap bevat het totale aantal (onderliggende) entiteiten ( total
), de verschuiving en de limiet ( offset
, limit
) zoals opgegeven in de aanvraag.
Voorbeeld: Pagelen example-paging
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
Typen entiteiten entity-types
Mappen folders
Mappen fungeren als containers voor elementen en andere mappen. Ze weerspiegelen de structuur van de AEM-inhoudsopslagplaats.
De REST API voor middelen stelt toegang tot de eigenschappen van een map beschikbaar, bijvoorbeeld de naam, titel, enzovoort. Elementen worden weergegeven als onderliggende entiteiten van mappen en submappen.
Assets assets
Als een element wordt aangevraagd, retourneert het antwoord de metagegevens van het element, zoals de titel, de naam en andere informatie, zoals gedefinieerd in het desbetreffende elementschema.
De binaire gegevens van een element worden blootgesteld als een verbinding SIREN van type content
.
Elementen kunnen meerdere uitvoeringen hebben. Deze worden doorgaans weergegeven als onderliggende entiteiten, waarbij één uitzondering een miniatuuruitvoering is die wordt weergegeven als een koppeling van het type thumbnail
( rel="thumbnail"
).
Contentfragmenten content-fragments
A inhoudsfragment is een speciaal soort actief. Ze kunnen worden gebruikt om onder andere toegang te krijgen tot gestructureerde gegevens, zoals tekst, getallen, datums.
Aangezien er verschillende verschillen zijn tussen standaard elementen (zoals afbeeldingen of audio). Voor de afhandeling ervan gelden enkele aanvullende regels.
Vertegenwoordiging representation
Inhoudsfragmenten:
-
Maak geen binaire gegevens beschikbaar.
-
volledig ingesloten in de JSON-uitvoer (binnen de
properties
eigenschap). -
Wordt ook als atomisch beschouwd, dat wil zeggen dat de elementen en variaties worden blootgesteld als onderdeel van de eigenschappen van het fragment in plaats van als koppelingen of onderliggende entiteiten. Op deze manier hebt u efficiënt toegang tot de lading van een fragment.
Inhoudsmodellen en inhoudsfragmenten content-models-and-content-fragments
De modellen die de structuur van een inhoudsfragment definiëren, worden momenteel niet via een HTTP-API weergegeven. Daarom consument moet op de hoogte zijn van het model van een fragment (minimaal), hoewel de meeste informatie kan worden afgeleid van de lading, als gegevenstypen enzovoort. maken deel uit van de definitie.
Als u een inhoudsfragment wilt maken, moet u het pad (interne gegevensopslagruimte) van het model opgeven.
Gekoppelde inhoud associated-content
Gekoppelde inhoud wordt momenteel niet weergegeven.
Gebruiken using
Het gebruik kan verschillen afhankelijk van of u een AEM auteur of publicatieomgeving gebruikt, samen met uw specifieke gebruiksscenario.
-
Het wordt ten zeerste aanbevolen dat het maken is gebonden aan een instantie van de auteur (en er is momenteel geen manier om een fragment te repliceren dat moet worden gepubliceerd met deze API).
-
De levering is mogelijk van beide, aangezien AEM gevraagde inhoud in formaat slechts JSON dient.
-
Opslag en levering vanuit een AEM auteur-instantie zouden voldoende moeten zijn voor toepassingen achter de firewall, in de mediabibliotheek.
-
Voor live webweergave wordt een AEM-publicatie-instantie aanbevolen.
-
/api
.Lezen/Levering read-delivery
Gebruik gebeurt via:
GET /{cfParentPath}/{cfName}.json
Bijvoorbeeld:
http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json
De reactie is geserialiseerd met JSON met de inhoud gestructureerd zoals in het inhoudsfragment. Referenties worden als referentie-URL's geleverd.
Er zijn twee typen leesbewerkingen mogelijk:
- Als u een specifiek inhoudsfragment leest per pad, wordt hiermee de JSON-representatie van het inhoudsfragment geretourneerd.
- Een map met inhoudsfragmenten lezen op pad: hiermee worden de JSON-representaties van alle inhoudsfragmenten in de map geretourneerd.
Maken create
Gebruik gebeurt via:
POST /{cfParentPath}/{cfName}
De hoofdtekst moet een JSON-representatie bevatten van het inhoudsfragment dat moet worden gemaakt, inclusief de initiële inhoud die moet worden ingesteld op de elementen van het inhoudsfragment. Het is verplicht de cq:model
en moet verwijzen naar een geldig inhoudsfragmentmodel. Als u dit niet doet, treedt er een fout op. Er moet ook een koptekst worden toegevoegd Content-Type
die is ingesteld op application/json
.
Bijwerken update
Gebruik is via
PUT /{cfParentPath}/{cfName}
De hoofdtekst moet een JSON-representatie bevatten van wat voor het opgegeven inhoudsfragment moet worden bijgewerkt.
Dit kan gewoon de titel of beschrijving zijn van een inhoudsfragment, of één element, of alle elementwaarden en/of metagegevens.
Verwijderen delete
Gebruik gebeurt via:
DELETE /{cfParentPath}/{cfName}
Beperkingen limitations
Er zijn een paar beperkingen:
- Inhoudsfragmentmodellen worden momenteel niet ondersteund: ze kunnen niet worden gelezen of gemaakt. Ontwikkelaars moeten het juiste pad naar het fragmentmodel van de inhoud kennen om een inhoudsfragment te kunnen maken of een bestaand fragment bij te werken. Momenteel is de enige methode om een overzicht van deze te krijgen door het beleid UI.
- Verwijzingen worden genegeerd. Er wordt momenteel niet gecontroleerd of naar een bestaand inhoudsfragment wordt verwezen. Daarom kan het verwijderen van een inhoudsfragment bijvoorbeeld resulteren in problemen op een pagina die een verwijzing naar het verwijderde inhoudsfragment bevat.
- JSON-gegevenstype De REST API-uitvoer van de JSON-gegevenstype is momenteel op tekenreeks gebaseerde uitvoer.
Statuscodes en foutberichten status-codes-and-error-messages
De volgende statuscodes kunnen in de relevante omstandigheden worden gezien:
-
200 (OK) Geretourneerd wanneer:
- een inhoudsfragment aanvragen via
GET
- het bijwerken van een inhoudsfragment via
PUT
- een inhoudsfragment aanvragen via
-
201 (Gemaakt) Wordt geretourneerd wanneer:
- een inhoudsfragment maken via
POST
- een inhoudsfragment maken via
-
404 (Niet gevonden) Geretourneerd wanneer:
- het gewenste inhoudsfragment bestaat niet
-
500 (Interne serverfout)
note note NOTE Deze fout wordt geretourneerd: - wanneer een fout is opgetreden die niet met een specifieke code kan worden geïdentificeerd
- wanneer de opgegeven lading niet geldig was
In het volgende voorbeeld worden algemene scenario's weergegeven wanneer deze foutstatus wordt geretourneerd, samen met het gegenereerde foutbericht (monospace):
-
Bovenliggende map bestaat niet (wanneer u een inhoudsfragment maakt via
POST
) -
Er is geen inhoudsfragmentmodel opgegeven (cq:model ontbreekt), kan niet worden gelezen (vanwege een ongeldig pad of een machtigingsprobleem) of er is geen geldig fragmentmodel:
No content fragment model specified
Cannot create a resource of given model '/foo/bar/qux'
-
Het inhoudsfragment kan niet worden gemaakt (mogelijk een probleem met de machtigingen):
Could not create content fragment
-
Titel en/of beschrijving kunnen niet worden bijgewerkt:
Could not set value on content fragment
-
Kan metagegevens niet instellen:
Could not set metadata on content fragment
-
Het element Content kan niet worden gevonden of kan niet worden bijgewerkt
Could not update content element
Could not update fragment data of element
De gedetailleerde foutberichten worden meestal als volgt geretourneerd:
code language-xml { "class": "core/response", "properties": { "path": "/api/assets/foo/bar/qux", "location": "/api/assets/foo/bar/qux.json", "parentLocation": "/api/assets/foo/bar.json", "status.code": 500, "status.message": "...{error message}.." } }
API-naslag api-reference
Zie hier voor gedetailleerde API-referenties:
Aanvullende bronnen additional-resources
Zie voor meer informatie: