Stöd för Content Fragments i AEM Assets HTTP API

Översikt

Lär dig mer om stöd för innehållsfragment i Assets HTTP API, en viktig del AEM headless delivery feature.

The Resurser REST API ger utvecklare av Adobe Experience Manager tillgång till innehåll (som lagras i AEM) direkt via HTTP-API:t via CRUD-åtgärder (Create, Read, Update, Delete).

Med API kan du använda Adobe Experience Manager som headless CMS (Content Management System) genom att tillhandahålla Content Services till ett JavaScript-klientprogram. Eller något annat program som kan köra HTTP-begäranden och hantera JSON-svar.

Enkelsidiga program (SPA), ramverksbaserade eller anpassade, kräver till exempel innehåll som tillhandahålls via HTTP API, ofta i JSON-format.

while AEM kärnkomponenter tillhandahåller ett mycket omfattande, flexibelt och anpassningsbart API som kan tillhandahålla de läsoperationer som krävs för detta, och vars JSON-utdata kan anpassas, kräver de AEM WCM-kunskaper (Web Content Management) för implementering eftersom de måste finnas på sidor som är baserade på dedikerade AEM-mallar. Det är inte varje SPA utvecklingsorganisation som har direkt tillgång till sådan kunskap.

Detta är när REST API:t för resurser kan användas. Med det kan utvecklare komma åt resurser (till exempel bilder och innehållsfragment) direkt, utan att först behöva bädda in dem på en sida, och leverera innehållet i serialiserat JSON-format.

Med Assets REST API kan utvecklare ändra innehåll genom att skapa nya, uppdatera eller ta bort befintliga resurser, innehållsfragment och mappar.

Resursens REST API:

• följer HATEOAS-principen

• implementerar SIREN-format

Förutsättningar

Resursens REST API är tillgängligt för varje körklar installation av en nyligen AEM version.

Viktiga begrepp

Resurser REST API erbjuder REST-liknande åtkomst till resurser som lagras i en AEM.

Den använder /api/assets slutpunkten och kräver att sökvägen till resursen har åtkomst till den (utan radavståndet) /content/dam).

• Det innebär att du kan få tillgång till resursen på
  • /content/dam/path/to/asset
• Du måste begära:
  • /api/assets/path/to/asset

Till exempel för att komma åt /content/dam/wknd/en/adventures/cycling-tuscany, begäran /api/assets/wknd/en/adventures/cycling-tuscany.json

HTTP-metoden avgör vilken åtgärd som ska utföras:

• GET - för att hämta en JSON-representation av en resurs eller en mapp
• POST - för att skapa nya resurser eller mappar
• PUT - för att uppdatera egenskaperna för en resurs eller mapp
• DELETE - ta bort en resurs eller mapp

Det exakta formatet för begäranden som stöds definieras i API-referens dokumentation.

Transaktionsbeteende

Alla förfrågningar är atomiska.

Detta innebär att följande (write) kan inte kombineras till en enda transaktion som kan lyckas eller misslyckas som en enskild enhet.

AEM (Resurser) REST API jämfört med AEM

Dokumentskydd

Om REST API:t för Resurser används i en miljö utan särskilda autentiseringskrav måste AEM CORS-filtret konfigureras korrekt.

I miljöer med specifika autentiseringskrav rekommenderas OAuth.

Tillgängliga funktioner

Innehållsfragment är en specifik typ av resurs, se Arbeta med innehållsfragment.

Mer information om funktioner som är tillgängliga via API finns i:

• The Resurser REST API
• Enhetstyper, där de funktioner som är specifika för varje typ som stöds (som är relevant för innehållsfragment) förklaras

Sidindelning

Resursens REST API stöder sidindelning (för GET-begäranden) via URL-parametrarna:

• offset - numret på den första (underordnade) entiteten som ska hämtas
• limit - det maximala antalet returnerade enheter

Svaret kommer att innehålla sidindelningsinformation som en del av properties i SIREN-utdata. Detta srn:paging egenskapen innehåller det totala antalet (underordnade) entiteter ( total), förskjutningen och gränsen ( offset, limit) enligt begäran.

Exempel: Sidindelning

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

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

Enhetstyper

Mappar

Mappar fungerar som behållare för resurser och andra mappar. De återspeglar strukturen i AEM innehållsdatabas.

Resursens REST API visar åtkomst till egenskaperna för en mapp, till exempel dess namn, titel osv. Resurser visas som underordnade enheter till mappar och undermappar.

Assets

Om en resurs begärs returnerar svaret dess metadata, till exempel titel, namn och annan information som definieras i respektive resursschema.

Den binära informationen för en resurs visas som en SIREN-länk av typen content.

Resurser kan ha flera renderingar. Dessa visas vanligtvis som underordnade enheter, och ett undantag är en miniatyrrendering, som visas som en länk av typen thumbnail ( rel="thumbnail").

Innehållsfragment

A innehållsfragment är en särskild typ av tillgång. De kan användas för att komma åt strukturerade data, t.ex. texter, siffror och datum.

Som det finns flera skillnader mellan standard resurser (t.ex. bilder eller ljud), kan vissa andra regler gälla för att hantera dem.

Representation

Innehållsfragment:

• Visa inga binära data.

• Finns helt i JSON-utdata (i properties egenskap).

• betraktas också som atomiska, dvs. elementen och variationerna exponeras som en del av fragmentets egenskaper jämfört med som länkar eller underordnade enheter. Detta ger effektiv åtkomst till nyttolasten för ett fragment.

Innehållsmodeller och innehållsfragment

För närvarande visas inte modellerna som definierar strukturen för ett innehållsfragment via ett HTTP-API. Därför konsument behöver känna till modellen för ett fragment (minst ett minimum), även om den mesta informationen kan härledas från nyttolasten, som datatyper osv. är en del av definitionen.

Om du vill skapa ett nytt innehållsfragment måste modellens (interna databas) sökväg anges.

Associerat innehåll

Associerat innehåll visas för närvarande inte.

Använda

Användningen kan variera beroende på om du använder en AEM författare eller publiceringsmiljö, tillsammans med ditt specifika användningsexempel.

• Vi rekommenderar starkt att skapandet är bundet till en författarinstans (och det finns för närvarande inget sätt att replikera ett fragment som ska publiceras med detta API).

• Leverans är möjlig från båda, eftersom AEM endast skickar begärt innehåll i JSON-format.

  • Lagring och leverans från en AEM författarinstans bör räcka för program som ligger bakom brandväggen och mediabibliotek.

  • För live-webbleverans rekommenderas en publiceringsinstans AEM.

Läsning/leverans

Användning sker via:

GET /{cfParentPath}/{cfName}.json

Till exempel:

http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json

Svaret är serialiserat JSON med innehållet strukturerat som i innehållsfragmentet. Referenser levereras som referens-URL:er.

Det finns två typer av läsåtgärder:

• När du läser ett visst innehållsfragment efter sökväg, returneras JSON-representationen av innehållsfragmentet.
• Läser en mapp med innehållsfragment efter sökväg: Detta returnerar JSON-representationerna för alla innehållsfragment i mappen.

Skapa

Användning sker via:

POST /{cfParentPath}/{cfName}

Brödtexten måste innehålla en JSON-representation av det innehållsfragment som ska skapas, inklusive allt ursprungligt innehåll som ska anges för elementen i innehållsfragmentet. Det är obligatoriskt att ange cq:model och måste peka på en giltig innehållsfragmentmodell. Om du inte gör det kommer ett fel att uppstå. Du måste också lägga till en rubrik Content-Type som är inställd på application/json.

Uppdatera

Användning sker via

PUT /{cfParentPath}/{cfName}

Brödtexten måste innehålla en JSON-representation av vad som ska uppdateras för det angivna innehållsfragmentet.

Detta kan helt enkelt vara titeln eller beskrivningen av ett innehållsfragment, ett enskilt element eller alla elementvärden och/eller metadata.

Ta bort

Användning sker via:

DELETE /{cfParentPath}/{cfName}

Begränsningar

Det finns några begränsningar:

• Modeller för innehållsfragment stöds för närvarande inte: de kan inte läsas eller skapas. För att kunna skapa ett nytt, eller uppdatera ett befintligt, innehållsfragment, måste utvecklarna veta rätt sökväg till innehållsfragmentmodellen. För närvarande är det enda sättet att få en översikt över dessa genom administrationsgränssnittet.
• Referenser ignoreras. För närvarande finns det inga kontroller för om ett befintligt innehållsfragment refereras. Om du tar bort ett innehållsfragment kan det därför leda till problem på en sida som innehåller en referens till det borttagna innehållsfragmentet.
• JSON-datatyp REST API-utdata för JSON-datatyp är för närvarande strängbaserade utdata.

Statuskoder och felmeddelanden

Följande statuskoder kan ses under de relevanta omständigheterna:

• 200 (OK) Returneras när:

  • begära ett innehållsfragment via GET
  • uppdaterar ett innehållsfragment via PUT

• 201 (Skapat) Returneras när:

  • har skapat ett innehållsfragment via POST

• 404 (Hittades inte) Returneras när:

  • det begärda innehållsfragmentet inte finns

• 500 (Internt serverfel)

  OBSERVERA

  Detta fel returneras:

  • när ett fel som inte kan identifieras med en viss kod har inträffat
  • när den angivna nyttolasten inte var giltig

  I följande exempel visas vanliga scenarier när den här felstatusen returneras, tillsammans med felmeddelandet (monospace) som genereras:

  • Överordnad mapp finns inte (när ett innehållsfragment skapas via POST)

  • Ingen innehållsfragmentmodell har angetts (cq:model saknas), kan inte läsas (på grund av en ogiltig sökväg eller ett behörighetsproblem) eller så finns det ingen giltig fragmentmodell:

    • No content fragment model specified
    • Cannot create a resource of given model '/foo/bar/qux'

  • Det gick inte att skapa innehållsfragmentet (eventuellt ett behörighetsproblem):

    • Could not create content fragment

  • Titeln och/eller beskrivningen kunde inte uppdateras:

    • Could not set value on content fragment

  • Det gick inte att ange metadata:

    • Could not set metadata on content fragment

  • Innehållselementet kunde inte hittas eller kunde inte uppdateras

    • Could not update content element
    • Could not update fragment data of element

  De detaljerade felmeddelandena returneras vanligtvis på följande sätt:

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

Här finns detaljerade API-referenser:

• Adobe Experience Manager Assets API - innehållsfragment

• HTTP API för Assets

  • Tillgängliga funktioner

Ytterligare resurser

Mer information finns i:

• Resurser för HTTP API-dokumentation
• AEM Gem-session: OAuth

Resurser för Business.Adobe.com

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