DocumentatieAEM as a Cloud ServiceHandboek

Ondersteuning voor inhoudsfragmenten in de AEM Assets HTTP API content-fragments-support-in-aem-assets-http-api

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Gemaakt voor:

  • Gebruiker
  • Beheerder

Overzicht overview

Versie
Artikelkoppeling
AEM 6,5
klik hier
AEM as a Cloud Service
Dit artikel

Meer informatie over ondersteuning voor Content Fragments in de Assets HTTP API, een belangrijke functie voor het leveren van koploze Adobe Experience Manager (AEM).

NOTE
Het Fragment van de Inhoud en ModelAPIs van het Fragment van de Inhoudzijn ook beschikbaar.
NOTE
HTTP API van Assetsomvat:
  • ASSETS REST API
  • inclusief ondersteuning voor inhoudsfragmenten
De huidige implementatie van Assets HTTP API is gebaseerd op de RESTarchitecturale stijl.
NOTE
Voor de recentste informatie over Experience Manager APIs, gelieve ook Adobe Experience Manager as a Cloud Service APIste bezoeken.

Assets REST APIstaat ontwikkelaars voor Adobe Experience Manager as a Cloud Service toe om tot inhoud (die in AEM wordt opgeslagen) direct over HTTP API, als (Create, Lees, Update, Schrapping) verrichtingen toegang te hebben CRUD.

Met de API kunt u Adobe Experience Manager as a Cloud Service gebruiken als een CMS zonder kop (Content Management System) 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.

Bijvoorbeeld, Enige Toepassingen van de Pagina (SPA), op kader-gebaseerd of douane, vereisen inhoud die over HTTP API wordt verstrekt, vaak in formaat JSON.

Terwijl AEM de Componenten van de Kerneen klantgerichte API verstrekken 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. Dit komt omdat ze moeten worden gehost op pagina's die zijn gebaseerd op speciale AEM sjablonen. Niet elke SPA ontwikkelingsorganisatie heeft directe toegang tot deze kennis.

Dit is wanneer de Assets REST API 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.

NOTE
Het is niet mogelijk JSON-uitvoer van de Assets REST API aan te passen.

Met de Assets REST API kunnen ontwikkelaars ook inhoud wijzigen door nieuwe elementen, inhoudsfragmenten en mappen te maken, bij te werken of te verwijderen.

De Assets REST API:

Vereisten prerequisites

De Assets REST-API is beschikbaar voor elke installatie van een recente Adobe Experience Manager as a Cloud Service-versie die buiten de box valt.

Belangrijke concepten key-concepts

Assets REST API biedt REST- stijltoegang tot activa aan die binnen een AEM instantie worden opgeslagen.

De methode gebruikt het eindpunt /api/assets en vereist het pad van het element om het te openen (zonder de regelafstand /content/dam ).

  • Dit betekent dat toegang tot het actief moet worden verkregen tegen:
    • /content/dam/path/to/asset
  • Verzoek:
    • /api/assets/path/to/asset

Als u bijvoorbeeld toegang wilt krijgen tot /content/dam/wknd/en/adventures/cycling-tuscany , vraagt u om /api/assets/wknd/en/adventures/cycling-tuscany.json

NOTE
Toegang over:
  • /api/assets ​ ​nodig niet het gebruik van .model selecteur.
  • /content/path/to/page ​ ​vereist het gebruik van .model selecteur.

De HTTP-methode bepaalt de uit te voeren bewerking:

  • GET - om een vertegenwoordiging JSON van activa of een omslag terug te winnen
  • POST - om activa of omslagen te creëren
  • PUT - om de eigenschappen van een activa of een omslag bij te werken
  • DELETE - om activa of een omslag te schrappen
NOTE
De verzoeklichaam en/of parameters URL kunnen worden gebruikt om sommige van deze verrichtingen te vormen; bijvoorbeeld, bepaal dat een omslag of een activa door a POST verzoek zou moeten worden gecreeerd.

Het nauwkeurige formaat van gesteunde verzoeken wordt bepaald in de API documentatie van de Verwijzing.

NOTE
Het Fragment van de Inhoud en ModelAPIs van het Fragment van de Inhoudzijn ook beschikbaar.

Transactioneel gedrag transactional-behavior

Alle verzoeken zijn atomisch.

Dit betekent dat de verdere (write) verzoeken niet in één enkele transactie kunnen worden gecombineerd die als één enkele entiteit kon slagen of ontbreken.

AEM (Assets) REST API versus AEM componenten aem-assets-rest-api-versus-aem-components

Verhouding
Assets REST API
AEM Component
(componenten die Sling Models gebruiken)
Ondersteunde gebruiksgevallen
Algemeen doel.

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

Het kan ook lay-outinformatie bevatten.

Ondersteunde bewerkingen

Maken, lezen, bijwerken, verwijderen.

Met extra bewerkingen, afhankelijk van het type entiteit.

Alleen-lezen.
Toegang

Het kan direct worden betreden.

Gebruikt het /api/assets eindpunt, in kaart gebracht aan /content/dam (in de bewaarplaats).

Een voorbeeldpad zou er als volgt uitzien: /api/assets/wknd/en/adventures/cycling-tuscany.json

Er moet naar worden verwezen door een AEM component op een AEM pagina.

Gebruikt de kiezer van .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 de standaardopstelling worden gevormd.

Gebruikt AEM standaard installatie.
Architecten

Schrijftoegang richt zich doorgaans op een instantie Auteur.

Lees kan ook naar een Publish-instantie worden gestuurd.

Omdat deze methode alleen-lezen is, wordt deze doorgaans gebruikt voor Publish-instanties.
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 security

Als de Assets REST API wordt gebruikt binnen een omgeving zonder specifieke verificatievereisten, moet AEM CORS-filter correct zijn geconfigureerd.

NOTE
Zie voor meer informatie:

In omgevingen met specifieke verificatievereisten wordt OAuth aanbevolen.

Beschikbare functies available-features

De Fragmenten van de inhoud zijn een specifiek type van Activa, zie Werkend met de Fragmenten van de Inhoud.

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

NOTE
Het Fragment van de Inhoud en ModelAPIs van het Fragment van de Inhoudzijn ook beschikbaar.

Paginering paging

De Assets REST API ondersteunt paginering (voor GET-aanvragen) via de URL-parameters:

  • offset - het nummer van de eerste (onderliggende) entiteit die moet worden opgehaald
  • limit - het maximale aantal geretourneerde entiteiten

De reactie bevat pagineringsinformatie als onderdeel van de sectie properties van de SIREN-uitvoer. Deze eigenschap srn:paging bevat het totale aantal (onderliggende) entiteiten ( total ), de verschuiving en de limiet ( offset , limit ) zoals opgegeven in de aanvraag.

NOTE
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 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 Assets REST API stelt toegang tot de eigenschappen van een map beschikbaar. Bijvoorbeeld de naam en de titel. Assets wordt weergegeven als onderliggende entiteiten van mappen en submappen.

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

Assets assets

Als een element wordt aangevraagd, retourneert het antwoord de metagegevens van het element, zoals titel, naam en andere informatie, zoals gedefinieerd in het desbetreffende elementschema.

De binaire gegevens van een element worden weergegeven als een SIREN-koppeling van het type content .

Assets kan 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" ).

Inhoudsfragmenten content-fragments

A inhoudsfragmentis een speciaal type van activa. Ze kunnen worden gebruikt om onder andere toegang te krijgen tot gestructureerde gegevens, zoals tekst, getallen, datums.

Aangezien er verscheidene verschillen aan standaard activa (zoals beelden of audio) zijn, zijn sommige extra regels van toepassing op de behandeling van hen.

Vertegenwoordiging representation

Inhoudsfragmenten:

  • Maak geen binaire gegevens beschikbaar.

  • Deze bevinden zich in de JSON-uitvoer (binnen de eigenschap properties ).

  • Ze worden ook als atomisch beschouwd. De elementen en variaties worden dus weergegeven 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 moet de consument over het model van een fragment (minstens een minimum) weten - hoewel de meeste informatie van de nuttige lading kan worden afgeleid; als gegevenstypes, etc., deel van de definitie uitmaken.

Als u een inhoudsfragment wilt maken, moet u het pad (interne gegevensopslagruimte) van het model opgeven.

Gekoppelde inhoud associated-content

Gekoppelde inhoud wordt niet weergegeven.

Gebruiken using

Het gebruik kan verschillen, afhankelijk van het feit of u een AEM-auteur of een Publish-omgeving gebruikt, samen met uw specifieke gebruiksscenario.

CAUTION
De Dispatcher-configuratie op AEM wolkeninstanties kan de toegang tot /api blokkeren.
NOTE
Zie de API Verwijzing. In het bijzonder, Adobe Experience Manager Assets API - de Fragmenten van de Inhoud.
Het Fragment van de Inhoud en ModelAPIs van het Fragment van de Inhoudzijn ook beschikbaar.

Beperkingen limitations

Er zijn een paar beperkingen:

  • de fragmentmodellen van de Inhoud worden momenteel niet gesteund: zij kunnen niet worden gelezen of worden gecreeerd. Ontwikkelaars moeten het juiste pad naar het inhoudsfragmentmodel weten om een bestaand inhoudsfragment te kunnen maken of bijwerken. 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 REST API output van het JSON gegevenstype is op koord-gebaseerde output.

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 als GET
    • het bijwerken van een inhoudsfragment met succes als PUT

  • 201 (Gemaakt)

    Geretourneerd wanneer:

    • een inhoudsfragment maken met POST

  • 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 met de notatie 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 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:

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab