Ondersteuning voor contentfragmenten in HTTP-API van AEM Assets

Laatste update: 2023-11-08
  • Gemaakt voor:
  • Developer
Versie Artikelkoppeling
AEM as a Cloud Service Klik hier
AEM 6,5 Dit artikel

Overzicht

Leer over steun voor de Fragments van de Inhoud in de API van Activa HTTP, een belangrijk stuk van AEM koploze leveringseigenschap.

OPMERKING

De Elementen HTTP-API omvat:

  • REST-API voor middelen
  • inclusief ondersteuning voor inhoudsfragmenten

De huidige implementatie van de HTTP-API voor middelen is gebaseerd op de REST architectonische stijl.

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.

OPMERKING

Het is niet mogelijk JSON-uitvoer van de REST API voor middelen aan te passen.

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:

Vereisten

De REST-API voor middelen is beschikbaar voor elke installatie van een recente AEM.

Belangrijke concepten

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

OPMERKING

Toegang over:

  • /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
OPMERKING

De parameters request body en/of URL kunnen worden gebruikt om sommige van deze bewerkingen te configureren; definieer bijvoorbeeld dat een map of een element moet worden gemaakt door een POST verzoek.

De exacte indeling van ondersteunde aanvragen wordt gedefinieerd in het dialoogvenster API-naslag documentatie.

Transactioneel gedrag

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

Verhouding REST-API voor middelen
AEM
(componenten die gebruikmaken van modellen voor schuiven)
Ondersteunde gebruikscase(s) Algemeen doel.

Geoptimaliseerd voor gebruik in een toepassing voor één pagina (SPA) of in een andere (content consuming) context.

Kan ook lay-outgegevens bevatten.

Ondersteunde bewerkingen

Maken, lezen, bijwerken, verwijderen.

Met extra bewerkingen afhankelijk van het type entiteit.

Alleen-lezen.
Toegang

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

Beveiliging

Er zijn meerdere opties mogelijk.

OAuth wordt voorgesteld; kan los van standaardopstelling worden gevormd.

Gebruikt AEM standaardinstallatie.
Architecten

Schrijftoegang richt zich gewoonlijk tot een auteurinstantie.

Lees kan ook naar een publicatie-instantie worden gestuurd.

Aangezien deze benadering read-only is, zal het typisch voor publiceer instanties worden gebruikt.
Uitvoer SIREN-uitvoer gebaseerd op JSON: uitgebreid, maar krachtig. Hiermee kunt u navigeren binnen de inhoud. Op JSON gebaseerde eigen uitvoer; configureerbaar via Sling Models. Navigeren door de inhoudsstructuur is moeilijk te implementeren (maar niet noodzakelijkerwijs onmogelijk).

Beveiliging

Als de REST API van Middelen binnen een milieu zonder specifieke authentificatievereisten wordt gebruikt, moet AEM filter CORS correct worden gevormd.

OPMERKING

In omgevingen met specifieke verificatievereisten wordt OAuth aanbevolen.

Beschikbare functies

Inhoudsfragmenten zijn een specifiek type element, zie Werken met inhoudsfragmenten.

Zie voor meer informatie over functies die beschikbaar zijn via de API:

Paginering

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 opgehaald
  • limit - 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.

OPMERKING

Pagina's worden doorgaans toegepast op containerentiteiten (dat wil zeggen mappen of elementen met uitvoeringen), omdat ze betrekking hebben op de onderliggende elementen van de aangezochte entiteit.

Voorbeeld: Pagelen

GET /api/assets.json?offset=2&limit=3

...
"properties": {
    ...
    "srn:paging": {
        "total": 7,
        "offset": 2,
        "limit": 3
    }
    ...
}
...

Typen entiteiten

Mappen

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.

OPMERKING

Afhankelijk van het type element van de onderliggende elementen en mappen bevat de lijst met onderliggende entiteiten mogelijk al de volledige set eigenschappen die de onderliggende entiteit definieert. Alternatief, slechts kan een beperkte reeks eigenschappen voor een entiteit in deze lijst van kindentiteiten worden blootgesteld.

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

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

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

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

Gekoppelde inhoud wordt momenteel niet weergegeven.

Gebruiken

Het gebruik kan verschillen afhankelijk van of u een AEM auteur of publicatieomgeving gebruikt, samen met uw specifieke gebruiksscenario.

LET OP

De dispatcherconfiguratie op AEM instanties zou toegang tot kunnen blokkeren /api.

OPMERKING

Lezen/Levering

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

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

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

Gebruik gebeurt via:

DELETE /{cfParentPath}/{cfName}

Beperkingen

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

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
  • 201 (Gemaakt) Wordt geretourneerd wanneer:

    • een inhoudsfragment maken via POST
  • 404 (Niet gevonden) Geretourneerd wanneer:

    • het gewenste inhoudsfragment bestaat niet
  • 500 (Interne serverfout)

    OPMERKING

    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:

    {
      "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

Zie hier voor gedetailleerde API-referenties:

Aanvullende bronnen

Zie voor meer informatie:

Op deze pagina