Ondersteuning voor contentfragmenten in HTTP-API van AEM Assets

Overzicht

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

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 als een headless CMS (Content Management System) gebruiken door Content Services aan te bieden aan 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

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

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

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

Beveiliging

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

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 kenmerken die specifiek zijn voor elk ondersteund type (voor zover relevant voor inhoudsfragmenten) worden toegelicht

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.

Voorbeeld: Paginering

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 van Middelen stelt toegang tot de eigenschappen van een omslag bloot; bijvoorbeeld naam, titel, enz. Elementen worden weergegeven als onderliggende entiteiten van mappen en submappen.

Assets

Als een element wordt gevraagd, zal de reactie zijn meta-gegevens terugkeren; zoals titel, 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 teksten, 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, d.w.z. de elementen en variaties worden blootgesteld als onderdeel van de eigenschappen van het fragment ten opzichte 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 (ten minste minimaal), hoewel de meeste informatie kan worden afgeleid uit de lading; als gegevenstypen, enz. maken deel uit van de definitie.

Als u een nieuw 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.

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

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 enkele beperkingen:

• Inhoudsfragmentmodellen worden momenteel niet ondersteund: ze kunnen niet worden gelezen of gemaakt. Ontwikkelaars moeten het juiste pad naar het inhoudsfragmentmodel weten om een nieuw inhoudsfragment te kunnen maken of een bestaand inhoudsfragment 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:

• Adobe Experience Manager Assets API - Inhoudsfragmenten

• HTTP-API voor assets

  • Beschikbare functies

Aanvullende bronnen

Zie voor meer informatie:

• Elementen HTTP API-documentatie
• AEM Gem-sessie: OAuth

Business.Adobe.com-bronnen

Ecommerce Integrations Auto Form Fill Personalized Experiences Customer Communications Asset Collections Web Content Management