AEM GraphQL API voor gebruik met inhoudsfragmenten
- Onderwerpen:
- headless
Gemaakt voor:
- Beheerder
- Ontwikkelaar
IMPORTANTLeer hoe u Content Fragments in Adobe Experience Manager (AEM) as a Cloud Service kunt gebruiken met de AEM GraphQL API voor het leveren van inhoud zonder kop.
AEM as a Cloud Service GraphQL API die wordt gebruikt met Content Fragments is sterk gebaseerd op de standaard, open-source GraphQL API.
Met de GraphQL API in AEM kunt u inhoudsfragmenten efficiënt aan JavaScript-clients leveren in CMS-implementaties zonder kop:
- Herhalende API-aanvragen voorkomen, zoals REST,
- ervoor zorgen dat de levering beperkt blijft tot de specifieke eisen;
- Het toestaan voor bulklevering van precies wat voor het teruggeven als antwoord op één enkele API vraag nodig is.
NOTE- AEM Commerce verbruikt gegevens van een platform van Commerce via GraphQL.
- AEM Content Fragments werken samen met de AEM GraphQL API (een aangepaste implementatie op basis van standaard GraphQL) voor gestructureerde inhoud voor gebruik in uw toepassingen.
NOTENOTEDe GraphQL API
GraphQL is:
-
"…een vraagtaal voor APIs en runtime voor het vervullen van die vragen met uw bestaande gegevens. GraphQL verstrekt een volledige en begrijpelijke beschrijving van de gegevens in uw API, geeft cliënten de macht om precies te vragen wat zij en niets meer nodig hebben, maakt het gemakkelijker om APIs in tijd te evolueren, en laat krachtige ontwikkelaarshulpmiddelen toe.".
Zie GraphQL.org
-
"…een open specificatie voor een flexibele API laag. Plaats GraphQL over uw bestaande achtergronden om producten sneller dan ooit te bouwen…".
Zie GraphQLontdekken.
-
"…een taal en specificatie voor gegevensquery's die in 2012 intern door Facebook zijn ontwikkeld voordat deze in 2015 openbaar werd uitbesteed. Het biedt een alternatief voor op REST gebaseerde architecturen met als doel de productiviteit van ontwikkelaars te verhogen en de hoeveelheden overgedragen gegevens te minimaliseren. GraphQL wordt gebruikt in productie door honderden organisaties van alle grootte…"
Raadpleeg de volgende secties (onder andere over veel andere bronnen) voor informatie over de GraphQL API:
De GraphQL for AEM-implementatie is gebaseerd op de standaard GraphQL Java Library. Zie:
GraphQL Terminologie
GraphQL gebruikt het volgende:
-
- Schema's worden door AEM gegenereerd op basis van de modellen van inhoudsfragmenten.
- Met behulp van uw schema's geeft GraphQL de typen en bewerkingen weer die zijn toegestaan voor de GraphQL for AEM-implementatie.
-
-
Het pad in AEM dat reageert op GraphQL-query's en toegang biedt tot de GraphQL-schema's.
-
Zie toelatend uw Eindpunt van GraphQLvoor verdere details.
-
Zie (GraphQL.org) Inleiding aan GraphQLvoor uitvoerige details, met inbegrip van Beste praktijken.
GraphQL-querytypen
Met GraphQL kunt u query's uitvoeren die worden geretourneerd:
-
A enige ingang
AEM verstrekt mogelijkheden om vragen (beide types) in Verlengde Vragen om te zetten, diedoor Dispatcher en CDN kunnen worden in het voorgeheugen ondergebracht.
Aanbevolen werkwijzen voor GraphQL-query (Dispatcher en CDN)
De Verlengde Vragenzijn de geadviseerde methode om bij te gebruiken publiceer instanties als:
- ze zijn in cache geplaatst
- zij worden centraal beheerd door AEM as a Cloud Service
NOTEGraphQL-query's die POST-aanvragen gebruiken, worden niet aanbevolen omdat ze niet in de cache zijn opgeslagen, zodat Dispatcher standaard is geconfigureerd om dergelijke query's te blokkeren.
Hoewel GraphQL ook GET-verzoeken ondersteunt, kunnen deze limieten bereiken (bijvoorbeeld de lengte van de URL) die kunnen worden vermeden met behulp van Persisted Queries.
Zie toelaten caching van persisted queryvoor verdere details.
NOTE- Creeer a het omgevingsvariabele van Cloud Managergeroepen
ENABLE_GRAPHQL_ENDPOINT - met de waarde
true
NOTEGraphiQL IDE
U kunt de vragen van GraphQL testen en zuiveren gebruikend IDE GraphiQL.
Kwesties gebruiken voor auteur, voorvertoning en publicatie
De gebruiksgevallen kunnen afhankelijk zijn van het type AEM as a Cloud Service-omgeving:
-
Publicatie-omgeving; wordt gebruikt voor:
- Query-gegevens voor JS-toepassing (standaardgebruikscenario)
-
Voorvertoningsomgeving; wordt gebruikt voor:
- Vragen voorvertonen voorafgaand aan implementatie in de publicatieomgeving
- Query-gegevens voor JS-toepassing (standaardgebruikscenario)
- Vragen voorvertonen voorafgaand aan implementatie in de publicatieomgeving
-
Auteursomgeving; gebruikt voor:
-
Query-gegevens voor "inhoudsbeheerdoeleinden":
- GraphQL in AEM as a Cloud Service is momenteel een alleen-lezen API.
- De REST-API kan worden gebruikt voor CR(u)D-bewerkingen.
-
Machtigingen
De machtigingen zijn vereist voor toegang tot Assets.
GraphQL-query's worden uitgevoerd met toestemming van de AEM-gebruiker van het onderliggende verzoek. Als de gebruiker geen leestoegang heeft tot bepaalde fragmenten (opgeslagen als Assets), worden deze geen deel van de resultatenset.
Ook, moet de gebruiker toegang tot een eindpunt van GraphQL hebben om de vragen van GraphQL kunnen uitvoeren.
Schema genereren
GraphQL is een sterk getypeerde API, wat betekent dat de gegevens duidelijk gestructureerd en ingedeeld moeten zijn per type.
De GraphQL-specificatie biedt een aantal richtlijnen voor het maken van een robuuste API voor het ondervragen van gegevens over een bepaalde instantie. Om dit te doen, moet een cliënt het Schemahalen, dat alle types noodzakelijk voor een vraag bevat.
Voor Inhoudsfragmenten, zijn de schema's van GraphQL (structuur en types) gebaseerd op Toegelaten Modellen van het Fragment van de Inhouden hun gegevenstypes.
CAUTIONAls een gebruiker bijvoorbeeld een Content Fragment Model met de naam Article heeft gemaakt, genereert AEM een GraphQL-type ArticleModel . De velden in dit type komen overeen met de velden en gegevenstypen die in het model zijn gedefinieerd. Bovendien worden er enkele ingangspunten gemaakt voor de query's die op dit type werken, zoals articleByPath of articleList .
-
A Content Fragment Model:
-
Het corresponderende GraphQL-schema (uitvoer van de automatische documentatie GraphiQL):
Dit toont aan dat het geproduceerde type
ArticleModelverscheidene gebiedenbevat.-
Drie ervan zijn door de gebruiker beheerd:
author,mainenreferencearticle. -
De andere gebieden werden automatisch toegevoegd door AEM, en vertegenwoordigen nuttige methodes om informatie over een bepaald Fragment van de Inhoud te verstrekken; in dit voorbeeld, (de helpergebieden)
_path,_metadata,_variations.
-
-
Nadat een gebruiker een inhoudsfragment heeft gemaakt op basis van het artikelmodel, kan het vervolgens worden ondervraagd via GraphQL. Voor voorbeelden, zie de Vragen van de Steekproef(die op de structuur van het Fragment van de a steekproefInhoud voor gebruik met GraphQLworden gebaseerd).
In GraphQL for AEM is het schema flexibel. Dit betekent dat deze telkens automatisch wordt gegenereerd wanneer een inhoudsfragmentmodel wordt gemaakt, bijgewerkt of verwijderd. De caches voor het gegevensschema worden ook vernieuwd wanneer u een model van het inhoudsfragment bijwerkt.
De caches voor het gegevensschema worden ook vernieuwd wanneer u een model van het inhoudsfragment bijwerkt.
De service Sites GraphQL luistert (op de achtergrond) naar eventuele wijzigingen die zijn aangebracht in een inhoudsfragmentmodel. Wanneer updates worden ontdekt, slechts wordt dat deel van het schema opnieuw geproduceerd. Deze optimalisatie bespaart tijd en zorgt voor stabiliteit.
Als u bijvoorbeeld:
-
Installeer een pakket met
Content-Fragment-Model-1enContent-Fragment-Model-2:- Er worden GraphQL-typen voor
Model-1enModel-2gegenereerd.
- Er worden GraphQL-typen voor
-
Wijzig vervolgens
Content-Fragment-Model-2:-
Alleen het GraphQL-type
Model-2wordt bijgewerkt. -
Terwijl
Model-1hetzelfde blijft.
-
NOTEHet schema wordt gediend door het zelfde eindpunt zoals de vragen van GraphQL, met de cliënt die het feit behandelt dat het schema met de uitbreiding GQLschema wordt geroepen. Als u bijvoorbeeld een eenvoudige GET aanvraag uitvoert op /content/cq:graphql/global/endpoint.GQLschema , wordt het schema uitgevoerd met het inhoudstype: text/x-graphql-schema;charset=iso-8859-1 .
Schema genereren - Niet-gepubliceerde modellen
Wanneer Inhoudsfragmenten zijn genest, kan een bovenliggend inhoudsfragmentmodel worden gepubliceerd, maar een model waarnaar wordt verwezen, niet.
NOTEWanneer dit gebeurt, produceert AEM een onvolledig Schema voor het Model van het Fragment van de ouderInhoud. Dit betekent dat de fragmentverwijzing, die afhankelijk is van het niet-gepubliceerde model, uit het schema wordt verwijderd.
Velden
Binnen het schema zijn er afzonderlijke velden, van twee basiscategorieën:
-
Velden die u genereert.
Een selectie van Types van Gegevenswordt gebruikt om gebieden tot stand te brengen die op worden gebaseerd hoe u uw Model van het Fragment van de Inhoud vormt. De gebiedsnamen worden genomen van het gebied van de Naam van het Bezit van het Type van Gegevens tabel.
- Er is ook teruggeeft als plaatsen om in overweging te nemen, aangezien de gebruikers bepaalde gegevenstypes kunnen vormen. Een tekstveld met één regel kan bijvoorbeeld worden geconfigureerd voor meerdere tekstregels door
multifieldte kiezen in de vervolgkeuzelijst.
- Er is ook teruggeeft als plaatsen om in overweging te nemen, aangezien de gebruikers bepaalde gegevenstypes kunnen vormen. Een tekstveld met één regel kan bijvoorbeeld worden geconfigureerd voor meerdere tekstregels door
-
GraphQL voor AEM produceert ook verscheidene helpergebieden.
Gegevenstypen
GraphQL for AEM ondersteunt een lijst met typen. Alle ondersteunde gegevenstypen van het inhoudsfragmentmodel en de bijbehorende GraphQL-typen worden weergegeven:
String, [String]String, [String]Float, [Float]BooleanCalendaronlyDate, onlyTime, dateTimeString[String]String, [String]String, [String]Enig gebied:
Model - Model type, direct van verwijzingen voorzienMultifield, met één referenced type:
[Model] - Serie van type Model, die direct van serieMultifield, met veelvoudige referenced types wordt voorzien:
[AllFragmentModels] - Serie van alle modeltypes, van serie met verenigingstype van verwijzingen voorzien typeEnig gebied:
Model - Model type, direct van verwijzingen voorzienMultifield, met één referenced type:
[Model] - Serie van type Model, die direct van serieMultifield, met veelvoudige referenced types wordt voorzien:
[AllFragmentModels] - Serie van alle modeltypes, van serie met verenigingstype van verwijzingen voorzien typeHelpervelden
Naast de gegevenstypes voor gebruiker geproduceerde gebieden, produceert GraphQL voor AEM ook verscheidene helper gebieden helpen een Fragment van de Inhoud identificeren, of om extra informatie over een Fragment van de Inhoud te verstrekken.
Deze helpergebiedenzijn duidelijk met een voorafgaande _ om tussen te onderscheiden wat door de gebruiker is bepaald en wat auto-geproduceerd is.
Pad
Het padveld wordt gebruikt als een identifier in AEM GraphQL. Het geeft het pad aan van het Content Fragment-element in de AEM-opslagplaats. Dit is de id van een inhoudsfragment, omdat dit:
- uniek is in AEM,
- kan gemakkelijk worden opgehaald.
In de volgende code worden de paden weergegeven van alle inhoudsfragmenten die zijn gemaakt op basis van het inhoudsfragmentmodel Author , zoals wordt verschaft door de WKND-zelfstudie.
{
authorList {
items {
_path
}
}
}
Als u één inhoudsfragment van een bepaald type wilt ophalen, moet u ook eerst het pad bepalen. Bijvoorbeeld:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_path
firstName
lastName
}
}
}
Zie Vraag van de Steekproef - Één enkel Specifiek Fragment van de Stad.
ID (UUID)
Het veld Id wordt ook gebruikt als een id in AEM GraphQL. Het geeft het pad aan van het Content Fragment-element in de AEM-opslagplaats, maar in plaats van het feitelijke pad vast te houden, bevat het een UUID die de bron vertegenwoordigt. Dit is de id van een inhoudsfragment, omdat dit:
- uniek is in AEM,
- gemakkelijk kan worden opgehaald,
- verandert niet wanneer de bron wordt verplaatst.
De UUID voor een inhoudsfragment en voor een inhoudsfragment waarnaar wordt verwezen, of element, kan worden geretourneerd via de JSON-eigenschap _id .
{
articleList {
items {
_id
_path
}
}
}
Metagegevens
Via GraphQL stelt AEM ook de metagegevens van een inhoudsfragment beschikbaar. Metagegevens zijn de informatie die een inhoudsfragment beschrijft, zoals de titel van een inhoudsfragment, het miniatuurpad, de beschrijving van een inhoudsfragment en de datum waarop het is gemaakt.
Omdat metagegevens worden gegenereerd via de Schema-editor en als zodanig geen specifieke structuur hebben, is het GraphQL-type van TypedMetaData geïmplementeerd om de metagegevens van een inhoudsfragment beschikbaar te maken. TypedMetaData stelt de informatie bloot die door de volgende scalaire types wordt gegroepeerd:
stringMetadata:[StringMetadata]!stringArrayMetadata:[StringArrayMetadata]!intMetadata:[IntMetadata]!intArrayMetadata:[IntArrayMetadata]!floatMetadata:[FloatMetadata]!floatArrayMetadata:[FloatArrayMetadata]!booleanMetadata:[BooleanMetadata]!booleanArrayMetadata:[booleanArrayMetadata]!calendarMetadata:[CalendarMetadata]!calendarArrayMetadata:[CalendarArrayMetadata]!Elk scalair type vertegenwoordigt of één enkel naam-waarde paar of een serie van naam-waarde paren, waar de waarde van dat paar van het type is het werd gegroepeerd.
Als u bijvoorbeeld de titel van een inhoudsfragment wilt ophalen, weten we dat deze eigenschap een String-eigenschap is, zodat we een query voor alle String-metagegevens uitvoeren:
Ga als volgt te werk om te zoeken naar metagegevens:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_metadata {
stringMetadata {
name
value
}
}
}
}
}
U kunt alle GraphQL-typen voor metagegevens weergeven als u het schema Gegenereerde GraphQL weergeeft. Alle modeltypen hebben dezelfde TypedMetaData .
NOTEHoud er rekening mee dat
StringMetadata en StringArrayMetadata beide verwijzen naar wat in de opslagplaats is opgeslagen, en niet naar de manier waarop u ze ophaalt.stringMetadata aanroept, ontvangt u een array van alle metagegevens die als String in de opslagplaats zijn opgeslagen. Als u stringArrayMetadata aanroept, ontvangt u een array van alle metagegevens die als String[] in de opslagplaats zijn opgeslagen.Variaties
Het veld _variations is geïmplementeerd om het opvragen van variaties in een inhoudsfragment te vereenvoudigen. Bijvoorbeeld:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/ian-provo") {
item {
_variations
}
}
}
_variations gebied bevat geen a master variatie, aangezien technisch de originele gegevens (die als Hoofd in UI worden van verwijzingen voorzien) niet als expliciete variatie wordt beschouwd.NOTEGraphQL-variabelen
GraphQL staat toe dat variabelen in de query worden geplaatst. Voor meer informatie, zie documentatie van GraphQL voor Variabelen.
Als u bijvoorbeeld alle inhoudsfragmenten van het type Author in een specifieke variatie wilt ophalen (indien beschikbaar), kunt u het argument variation in GraphiQL opgeven.
Vraag:
query($variation: String!) {
authorList(variation: $variation) {
items {
_variation
lastName
firstName
}
}
}
de Variabelen van de Vraag:
{
"variation": "another"
}
Deze query retourneert de volledige lijst met auteurs. Auteurs zonder de another variatie worden teruggeplaatst naar de oorspronkelijke gegevens (_variation rapporteert master in dit geval).
Pas a filtertoe, als u de lijst tot auteurs wilt beperken die de gespecificeerde variatie (en overslaan auteurs verstrekken die terug naar de originele gegevens zouden vallen):
query($variation: String!) {
authorList(variation: $variation, filter: {
_variation: {
_expressions: {
value: $variation
}
}
}) {
items {
_variation
lastName
firstName
}
}
}
GraphQL-richtlijnen
In GraphQL bestaat de mogelijkheid om de query te wijzigen op basis van variabelen, de zogenaamde GraphQL-richtlijnen.
Hier kunt u bijvoorbeeld het veld adventurePrice opnemen in een query voor alle AdventureModels , op basis van een variabele includePrice .
Vraag:
query GetAdventureByType($includePrice: Boolean!) {
adventureList {
items {
title
price @include(if: $includePrice)
}
}
}
de Variabelen van de Vraag:
{
"includePrice": true
}
Filteren
U kunt filteren ook gebruiken in uw GraphQL-query's om specifieke gegevens te retourneren.
Bij het filteren wordt een syntaxis gebruikt die is gebaseerd op logische operatoren en expressies.
Het meest atomische deel bestaat uit één expressie die kan worden toegepast op de inhoud van een bepaald veld. De inhoud van het veld wordt vergeleken met een bepaalde constante waarde.
De expressie
{
value: "some text"
_op: EQUALS
}
Vergelijk de inhoud van het veld met de waarde some text en slaagt als de inhoud gelijk is aan de waarde. Anders zal de expressie mislukken.
De volgende operatoren kunnen worden gebruikt om velden met een bepaalde waarde te vergelijken:
EQUALSString, ID, BooleanEQUALS_NOTString, IDCONTAINSString{ value: "mas", _op: CONTAINS } komt overeen met Christmas , Xmas , master , …)CONTAINS_NOTStringSTARTS_WITHID{ value: "/content/dam/", _op: STARTS_WITH komt overeen met /content/dam/path/to/fragment , maar niet met /namespace/content/dam/something )EQUALInt, FloatUNEQUALInt, FloatGREATERInt, FloatGREATER_EQUALInt, FloatLOWERInt, FloatLOWER_EQUALInt, FloatATCalendar, Date, TimeNOT_ATCalendar, Date, TimeBEFORECalendar, Date, TimeAT_OR_BEFORECalendar, Date, TimeAFTERCalendar, Date, TimeAT_OR_AFTERCalendar, Date, TimeBij sommige typen kunt u ook aanvullende opties opgeven die wijzigen hoe een expressie wordt geëvalueerd:
_ignoreCaseStringtime overeenkomsten TIME , time , tImE , …_sensitivenessFloatfloat -waarden als hetzelfde worden beschouwd (om technische beperkingen te omzeilen vanwege de interne representatie van float -waarden; dit moet worden vermeden, omdat deze optie een negatief effect kan hebben op de prestatiesDe uitdrukkingen kunnen aan een reeks met behulp van een logische exploitant (_logOp) worden gecombineerd:
OR- de reeks expressies zal slagen als ten minste één expressie slaagtAND- de reeks expressies slaagt als alle expressies slagen (standaardwaarde)
Elk veld kan met een eigen set expressies worden gefilterd. De expressiesets van alle velden die in het filterargument worden vermeld, worden uiteindelijk gecombineerd door de eigen logische operator.
Een filterdefinitie (doorgegeven als het argument filter aan een query) bevat:
- Een subdefinitie voor elk veld (het veld is toegankelijk via de naam ervan, er is bijvoorbeeld een veld
lastNamein het filter voor het veldlastNamein het gegevenstype Data (veld)) - Elke subdefinitie bevat de array
_expressions, met daarin de set expressies en het veld_logOpwaarin de logische operator wordt gedefinieerd waarmee de expressies moeten worden gecombineerd - Elke expressie wordt gedefinieerd door de waarde (
valueveld) en de operator (_operatorveld) waarmee de inhoud van een veld moet worden vergeleken
U kunt _logOp weglaten als u items met AND en _operator wilt combineren als u op gelijkheid wilt controleren, aangezien dit de standaardwaarden zijn.
In het volgende voorbeeld wordt een volledige query getoond die alle personen filtert die een lastName van Provo hebben of sjö bevatten, onafhankelijk van het hoofdlettergebruik:
{
authorList(filter: {
lastname: {
_logOp: OR
_expressions: [
{
value: "sjö",
_operator: CONTAINS,
_ignoreCase: true
},
{
value: "Provo"
}
]
}
}) {
items {
lastName
firstName
}
}
}
U kunt ook filteren op geneste velden, maar dit wordt afgeraden omdat dit tot prestatieproblemen kan leiden.
Zie voor meer voorbeelden:
-
details van GraphQL voor de uitbreidingen van AEM
-
Voorbeeldquery's met deze voorbeeldinhoud en -structuur
- En de Inhoud en de Structuur van de Steekproefvoorbereid voor gebruik in steekproefvragen
Sorteren
NOTEMet deze functie kunt u de zoekresultaten sorteren op basis van een opgegeven veld.
De sorteercriteria:
-
is een door komma's gescheiden lijst met waarden die het veldpad aangeven
- het eerste veld in de lijst definieert de primaire sorteervolgorde, het tweede veld wordt gebruikt als twee waarden van het primaire sorteercriterium gelijk zijn, het derde als de eerste twee criteria gelijk zijn, enzovoort.
- puntnotatie, dat wil zeggen veld1.subfield.subfield enzovoort…
-
met een optionele bestelrichting
- ASC (oplopend) of DESC (aflopend); als standaard ASC wordt toegepast
- De richting kan per veld worden opgegeven. Dit betekent dat u één veld in oplopende volgorde kunt sorteren, een ander veld in aflopende volgorde (naam, voornaam DESC)
Bijvoorbeeld:
query {
authorList(sort: "lastName, firstName") {
items {
firstName
lastName
}
}
}
En ook:
{
authorList(sort: "lastName DESC, firstName DESC") {
items {
lastName
firstName
}
}
}
U kunt ook sorteren op een veld in een genest fragment met de indeling nestedFragmentname.fieldname .
NOTEBijvoorbeeld:
query {
articleList(sort: "authorFragment.lastName") {
items {
title
authorFragment {
firstName
lastName
birthDay
}
slug
}
}
}
Paginering
NOTEMet deze functie kunt u pagineren uitvoeren op querytypen die een lijst retourneren. Er zijn twee methoden:
offsetenlimitin een queryListfirstenafterin een queryPaginated
Lijstquery - Verschuiven en beperken
In a ...List vraag kunt u offset en limit gebruiken om een specifieke ondergroep van resultaten terug te keren:
offset: geeft de eerste gegevensset op die moet worden geretourneerdlimit: geeft het maximumaantal gegevenssets op dat moet worden geretourneerd
Bijvoorbeeld, om de pagina van resultaten uit te voeren die tot vijf artikelen bevatten, die van het vijfde artikel van de volledige resultatenlijst beginnen:
query {
articleList(offset: 5, limit: 5) {
items {
authorFragment {
lastName
firstName
}
}
}
}
-
De paginering vereist een stabiele soortorde om correct over veelvoudige vragen te werken die verschillende pagina's van de zelfde resultaatreeks vragen. Standaard wordt het pad naar de opslagplaats van elk item van de resultaatset gebruikt om ervoor te zorgen dat de volgorde altijd gelijk is. Als een verschillende sorteervolgorde wordt gebruikt en als die sortering niet kan worden uitgevoerd op JCR-queryniveau, heeft dit een negatief effect op de prestaties omdat de volledige resultaatset in het geheugen moet worden geladen voordat de pagina's kunnen worden bepaald.
-
Hoe hoger de verschuiving, des te meer tijd neemt het om de items van de volledige set JCR-queryresultaten over te slaan. Een alternatieve oplossing voor grote resultaatsets is de gepagineerde query met
firstenafterte gebruiken.
Gepagineerde query - eerste en volgende
Het ...Paginated vraagtype gebruikt de meeste ...List vraagtype eigenschappen (het filtreren, het sorteren) opnieuw, maar in plaats van het gebruiken van offset/ limit argumenten, gebruikt het first/ after argumenten zoals die door worden bepaald de Specificatie van de Verbindingen van de Curseur van GraphQL. U kunt een minder formele inleiding in de inleiding van GraphQLvinden.
first: Deneerste items die moeten worden geretourneerd.
De standaardwaarde is50.
Het maximum is100.after: De cursor die het begin van de opgevraagde pagina bepaalt. Het item dat de cursor vertegenwoordigt, wordt niet opgenomen in de resultatenset. De cursor van een item wordt bepaald door hetcursorveld van deedgesstructuur.
Bijvoorbeeld, output de pagina van resultaten die tot vijf avonturen bevatten, die van het bepaalde curseurpunt in de volledige resultatenlijst beginnen:
query {
adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
edges {
cursor
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
-
Standaard wordt bij paginering de UUID gebruikt van het opslagplaats-knooppunt dat het fragment vertegenwoordigt voor de volgorde van de resultaten, zodat altijd dezelfde volgorde wordt gebruikt. Wanneer
sortwordt gebruikt, wordt UUID impliciet gebruikt om een unieke soort te verzekeren; zelfs voor twee punten met identieke soortsleutels. -
Vanwege interne technische beperkingen zullen de prestaties afnemen als sorteren en filteren wordt toegepast op geneste velden. Daarom wordt aangeraden filter-/sorteervelden te gebruiken die op hoofdniveau zijn opgeslagen. Dit is ook de geadviseerde manier als u grote gepagineerde resultaatreeksen wilt vragen.
Webgeoptimaliseerde afbeeldingslevering in GraphQL-query's
Met webgeoptimaliseerde afbeeldingslevering kunt u een grafische query gebruiken:
-
Vraag een URL aan een element DAM beeld (die door de Verwijzing van de Inhoud van a wordt van verwijzingen voorzien)
-
Geef parameters door met de query, zodat er automatisch een specifieke uitvoering van de afbeelding wordt gegenereerd en geretourneerd
NOTEDe opgegeven vertoning wordt niet opgeslagen in AEM Assets. De vertoning wordt geproduceerd en in geheim voorgeheugen voor een korte periode gehouden. -
De URL retourneren als onderdeel van de JSON-levering
Met AEM kunt u:
- Geef Web-Geoptimaliseerde Levering van het Beeldin de vragen van GraphQL door.
Dit betekent dat de opdrachten worden toegepast tijdens de uitvoering van de query, op dezelfde manier als URL-parameters bij GET-aanvragen voor die afbeeldingen.
Hierdoor kunt u dynamisch afbeeldingsuitvoeringen maken voor JSON-levering, zodat u deze uitvoeringen niet handmatig hoeft te maken en op te slaan in de opslagplaats.
Met de oplossing in GraphQL kunt u:
-
Een URL aanvragen: gebruik
_dynamicUrlop deImageRef-verwijzing -
Parameters doorgeven: voeg
_assetTransformtoe aan de lijstkop waar de filters zijn gedefinieerd
NOTE_dynamicUrl: een DAM-element_dmS7Url: een dynamisch media-element
_dmS7Url null . Zie Dynamische levering van Media door URL in GraphQL vragen.Structuur van het transformatieverzoek
AssetTransform (_assetTransform) wordt gebruikt om de omzettingsverzoeken te maken URL.
De structuur en syntaxis zijn:
-
format: een opsomming met alle ondersteunde indelingen, zoals GIF, PNG, PNG8, JPG, PJPG, BJPG, WEBP, WEBPLL of WEBPLY -
seoName: een tekenreeks die wordt gebruikt als bestandsnaam in plaats van de knooppuntnaam -
crop: een substructuur van het frame, als breedte of hoogte wordt weggelaten, wordt de hoogte of breedte gebruikt als dezelfde waardexOrigin: de x-oorsprong van het frame en is verplichtyOrigin: de y-oorsprong van het frame en is verplichtwidth: de breedte van het frameheight: de hoogte van het frame
-
size: een substructuur voor afmetingen, als breedte of hoogte wordt weggelaten, wordt de hoogte of breedte gebruikt als dezelfde waardewidth: de breedte van de dimensieheight: de hoogte van de dimensie
-
rotation: een opsomming van alle ondersteunde rotaties: R90, R180, R270 -
flip: een opsomming van HORIZONTAL, VERTICAL, HORIZONTAL_AND_VERTICAL -
quality: een geheel getal van 1-100 dat het percentage van de afbeeldingskwaliteit aangeeft -
width: een geheel getal dat de breedte van de uitvoerafbeelding definieert, maar door de afbeeldingsgenerator wordt genegeerd -
preferWebp: een Booleaanse waarde die aangeeft of de voorkeur voor een webp wordt gegeven (standaardwaarde is false)
De transformatie URL is beschikbaar voor alle vraagtypes: door weg, lijst of gepagineerd.
Voor het web geoptimaliseerde afbeeldingslevering met volledige parameters
Hier volgt een voorbeeldquery met een volledige set parameters:
{
articleList(
_assetTransform: {
format:GIF
seoName:"test"
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
Web-geoptimaliseerde beeldlevering met één enkele vraagvariabele
In het volgende voorbeeld wordt het gebruik van één queryvariabele getoond:
query ($seoName: String!) {
articleList(
_assetTransform: {
format:GIF
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
Webgeoptimaliseerde afbeeldingslevering met meerdere queryvariabelen
In het volgende voorbeeld wordt het gebruik van meerdere queryvariabelen getoond:
query ($seoName: String!, $format: AssetTransformFormat!) {
articleList(
_assetTransform: {
format:$format
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
Voor het web geoptimaliseerde aanvraag voor het leveren van afbeeldingen via URL
Als u uw vraag als voortgeduurde vraag (bijvoorbeeld, met de naam dynamic-url-x) opslaat kunt u de voortgeduurde vraag directdan uitvoeren.
Gebruik bijvoorbeeld de volgende URL's om de vorige voorbeelden (opgeslagen als voortgeduurde query's) rechtstreeks uit te voeren:
-
Enige Parameter; Verblijfsde Vraag genoemd
dynamic-url-x-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic-url-x;seoName=xxxHet antwoord ziet er als volgt uit:
-
-
Veelvoudige Parameters; Verlengde Vraag genoemd
dynamic-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic;seoName=billiboy;format=GIF;CAUTIONNavolgende;is verplicht om de lijst van parameters schoon te eindigen.
-
Beperkingen voor de levering van webgeoptimaliseerde afbeeldingen
De volgende beperkingen bestaan:
-
Modifiers die worden toegepast op alle afbeeldingen die deel uitmaken van de query (globale parameters)
-
Koppen in cache plaatsen
- Geen caching op auteur
- Caching bij publicatie - maximale leeftijd van 10 minuten (kan niet worden gewijzigd door client)
Dynamische levering van media-elementen via URL in GraphQL-query's
GraphQL voor de Fragmenten van de Inhoud van AEM staat u toe om een URL aan een activa van AEM te verzoeken Dynamische Media (Scene7) (die door de Verwijzing van de Inhoud van a worden van verwijzingen voorzien).
Met de oplossing in GraphQL kunt u:
-
gebruik
_dmS7Urlop deImageRef-referentie -
gebruik
_dmS7Urlop meerdere referenties;ImageRef,MultimediaRefenDocumentRef -
gebruik van
_dmS7Urlmet de functie Slim uitsnijden-
De eigenschap
_smartCropsstelt de configuraties voor slim uitsnijden beschikbaar voor een specifiek element -
zie vraag van de Steekproef voor Dynamische de activalevering van Media door URL - met Slim Gewas
-
NOTEdam:scene7File en dam:scene7Domain toe aan de metagegevens van het element wanneer het wordt gemaakt.NOTE_dmS7Url: een dynamisch media-element_dynamicUrl: een DAM-element
_dynamicURL null . Zie Web-geoptimaliseerde beeldlevering in de vragen van GraphQL.Voorbeeldquery voor dynamische levering van media-elementen via URL - Afbeeldingsverwijzing
Hier volgt een voorbeeldquery:
- voor meerdere Content Fragments van het type
teamenperson, met een resultaatImageRef
query allTeams {
teamList {
items {
_path
title
teamMembers {
fullName
profilePicture {
__typename
... on ImageRef{
_dmS7Url
height
width
}
}
}
}
}
}
Voorbeeldquery voor dynamische levering van media-elementen via URL - Meerdere verwijzingen
Hier volgt een voorbeeldquery:
- voor meerdere Content Fragments van het type
teamenperson, bij het retourneren van eenImageRef,MultimediaRefenDocumentRef:
query allTeams {
teamList {
items {
_path
title
teamMembers {
fullName
profilePicture {
__typename
... on ImageRef{
_dmS7Url
height
width
}
}
featureVideo {
__typename
... on MultimediaRef{
_dmS7Url
size
}
}
about-me {
__typename
... on DocumentRef{
_dmS7Url
_path
}
}
}
}
}
}
Voorbeeldquery voor dynamische levering van media-elementen via URL - met Smart Crop
Hier volgt een voorbeeldquery:
- om de slimme configuraties van het Gewas beschikbaar voor de gevraagde activa bloot te stellen
query allTeams {
teamList {
items {
title
teamMembers {
profilePicture {
... on ImageRef {
height
width
_dmS7Url
_smartCrops {
width
height
name
}
}
}
}
}
}
}
Dynamische media voor ondersteuning voor OpenAPI-middelen (Remote Assets)
Verre activaintegratie staat u toe om Assets van verwijzingen te voorzien, die niet lokaal aan de huidige instantie van AEM, van de Redacteur van het Fragment van de Inhoud zijn. Dynamic Media for OpenAPI biedt ondersteuning voor elementen in de Content Fragment Editor en GraphQL JSON.
Voorbeeldquery voor Dynamic Media voor ondersteuning van OpenAPI-elementen (Remote Assets)
Hier volgt een voorbeeldverzoek:
-
om het concept van het verwijzen van verre activa te illustreren
{ testModelList { items { remoteasset { ... on RemoteRef { repositoryId assetId } } multiplecontent { ... on ImageRef { _path _authorUrl _publishUrl } ... on RemoteRef { repositoryId assetId } } } _references { ... on ImageRef { _path _authorUrl _publishUrl } ... on RemoteRef { repositoryId assetId } } } } -
het antwoord
{ "data": { "testModelList": { "items": [ { "remoteasset": { "repositoryId": "delivery-p123456-e123456.adobeaemcloud.com", "assetId": "urn:aaid:aem:1fb05fe4-c12b-4f85-b1ca-aa92cdbd6a62" }, "multiplecontent": [ { "repositoryId": "delivery-p123456-e123456.adobeaemcloud.com", "assetId": "urn:aaid:aem:1fb05fe4-c12b-4f85-b1ca-aa92cdbd6a62" }, { "_path": "/content/dam/test-folder/test.jpg", "_authorUrl": "http://localhost:4502/content/dam/test-folder/test.jpg", "_publishUrl": "http://localhost:4503/content/dam/test-folder/test.jpg" } ] } ], "_references": [ { "repositoryId": "delivery-p123456-e123456.adobeaemcloud.com", "assetId": "urn:aaid:aem:1fb05fe4-c12b-4f85-b1ca-aa92cdbd6a62" }, { "_path": "/content/dam/test-folder/test.jpg", "_authorUrl": "http://localhost:4502/content/dam/test-folder/test.jpg", "_publishUrl": "http://localhost:4503/content/dam/test-folder/test.jpg" } ] } } }
Beperkingen
De huidige beperkingen zijn:
-
GraphQL-levering ondersteunt alleen
repositoryIdenassetId(metagegevens van andere elementen worden niet geretourneerd)NOTEVolledige URL moet dan op de cliëntkant worden geconstrueerd, die op de levering API van Activawordt gebaseerd. -
Slechts goedgekeurde activa zullen voor verwijzing van de verre bewaarplaatsen beschikbaar zijn
-
Als een element waarnaar wordt verwezen, wordt verwijderd uit de externe opslagplaats, resulteert dit in een verbroken verwijzing naar Content Fragment Asset.
-
Alle opslagplaatsen voor leveringsmiddelen waartoe de gebruiker toegang heeft, zijn beschikbaar voor selectie. De beschikbare lijst kan niet worden beperkt.
-
Zowel de AEM-instantie als de Remote Asset Repository-instanties moeten dezelfde versie hebben.
-
Geen Metagegevens van Activa worden blootgesteld via Beheer APIen Levering API. U moet de API voor metagegevens van middelen gebruiken om de metagegevens van de elementen op te halen.
GraphQL for AEM - Overzicht van extensies
De basisverrichting van vragen met GraphQL voor AEM houdt zich aan de standaardspecificatie van GraphQL. Voor GraphQL-query's met AEM zijn er een paar extensies:
-
Als u één resultaat nodig hebt:
- gebruik de modelnaam; bijvoorbeeld stad
-
Als u een lijst met resultaten verwacht:
Listtoevoegen aan de modelnaam, bijvoorbeeldcityList- Zie Vraag van de Steekproef - Al Informatie over Alle Plaatsen
U kunt dan:
-
ASC: oplopendDESC: aflopend
-
Retourneer een pagina met resultaten met:
-
Zie Vraag van de Steekproef - Al Informatie over Alle Plaatsen
-
Het filter
includeVariationswordt opgenomen in de querytypenListenPaginated. Als u Variaties in inhoudsfragmenten in de queryresultaten wilt ophalen, moet het filterincludeVariationszijn ingesteld optrue.CAUTIONHet filterincludeVariationsen het door het systeem gegenereerde veld_variationkunnen niet samen in dezelfde querydefinitie worden gebruikt. -
Als u logische OR wilt gebruiken:
-
Logische AND bestaat ook, maar is (vaak) impliciet
-
U kunt zoeken naar veldnamen die overeenkomen met de velden in het model van het inhoudsfragment
-
Naast de velden van uw model zijn er velden die door het systeem worden gegenereerd (voorafgegaan door een onderstrepingsteken):
-
Voor inhoud:
-
_locale: om de taal te onthullen; gebaseerd op Taalbeheer -
_metadata: om metagegevens voor het fragment weer te geven -
_model: zoeken naar een inhoudsfragmentmodel toestaan (pad en titel) -
_path: het pad naar het inhoudsfragment in de opslagplaats -
_id: de UUID voor het inhoudsfragment in de opslagplaats -
_reference: om verwijzingen weer te geven; inclusief inline-verwijzingen in de Rich Text Editor -
_variation: specifieke variaties in het inhoudsfragment weergevenNOTEAls de opgegeven variatie niet bestaat voor een inhoudsfragment, wordt de hoofdvariatie geretourneerd als een standaardinstelling (fallback).CAUTIONHet door het systeem gegenereerde veld_variationkan niet samen met het filterincludeVariationsworden gebruikt.
-
-
Voor levering van de afbeelding:
-
_authorURL: de volledige URL naar het afbeeldingselement op AEM Author -
_publishURL: de volledige URL naar het afbeeldingselement in AEM Publish -
Voor Web-geoptimaliseerde beeldlevering(van activa DAM):
-
_dynamicUrl: de volledige URL naar het voor het web geoptimaliseerde DAM-element op deImageRef-referentieNOTE_dynamicUrlis de voorkeurs-URL die u wilt gebruiken voor voor het web geoptimaliseerde DAM-elementen en moet waar mogelijk het gebruik van_path,_authorUrlen_publishUrlvervangen. -
_assetTransform: parameters doorgeven in de lijstkop waar de filters zijn gedefinieerd -
Zie:
-
-
_dmS7Url: op deImageRefverwijzing voor de levering van URL aan a Dynamische activa van Media
-
-
_tags: om de id's weer te geven van inhoudsfragmenten of variaties die tags bevatten. Dit is een array vancq:tags-id's.- Zie Vraag van de Steekproef - Namen van Alle Plaatsen die als de Breuken van de Stadworden geëtiketteerd
- Zie Vraag van de Steekproef voor de Variaties van het Fragment van Inhoud van een bepaald Model dat een specifieke markering in bijlageheeft
- Zie Vraag van de Steekproef met het filtreren door _tags identiteitskaart en exclusief variaties
- Zie Vraag van de Steekproef met het filtreren door _tags identiteitskaart en met inbegrip van variaties
NOTETags kunnen ook worden opgevraagd door de metagegevens van een inhoudsfragment weer te geven. -
En bewerkingen:
-
_operator: specifieke operatoren toepassen;EQUALS,EQUALS_NOT,GREATER_EQUAL,LOWER,CONTAINS,STARTS_WITH -
_apply: specifieke voorwaarden toepassen, bijvoorbeeldAT_LEAST_ONCE -
_ignoreCase: de kwestie negeren bij het opvragen
-
-
-
GraphQL-union-typen worden ondersteund:
-
Extra fallback bij het opvragen van geneste fragmenten:
- Als een bepaalde variatie niet in een genest fragment bestaat, dan zou de Hoofd variatie zijn teruggekeerd.
Het GraphQL-eindpunt van een externe website opvragen
Om tot het eindpunt van GraphQL van een externe website toegang te hebben moet u vormen:
Verificatie
Zie Authentificatie voor de Verre Vraag van AEM GraphQL op de Fragmenten van de Inhoud.
Automatisch testen
Wanneer het runnen van een plaatsingspijpleiding in AEM Cloud Manager, worden de geautomatiseerde tests in werking gesteld tijdens pijpleidingsuitvoering.
Om nauwkeurige resultaten te verstrekken, zou uw milieu van het Stadium van AEM as a Cloud Service uw milieu van de Productie zo dicht mogelijk moeten spiegelen. Dit is vooral belangrijk voor de inhoud.
U kunt dit bereiken door het Hulpmiddel van het Exemplaar van de Inhoud van AEM as a Cloud Service te gebruikenom uw inhoud van de Productie aan het milieu van het Stadium te kopiëren.
Beperkingen
Om tegen potentiële problemen te beschermen worden er standaardbeperkingen opgelegd aan uw vragen:
- De query mag niet meer dan 1M (1024 * 1024) tekens bevatten
- De query mag niet meer dan 15000 tokens bevatten
- De query mag niet meer dan 200000 whitespace-tokens bevatten
U moet zich ook bewust zijn van:
-
Er wordt een fout in een veldconflict geretourneerd wanneer uw GraphQL-query velden met dezelfde naam bevat in twee (of meer) modellen en aan de volgende voorwaarden wordt voldaan:
-
Dus waar:
- Twee (of meer modellen) worden gebruikt als mogelijke verwijzingen; wanneer zij als toegestaan ModelType in de verwijzing van het Fragment van de Inhoud worden bepaald.
en:
- Deze twee modellen hebben gebieden met een gemeenschappelijke naam; dat betekent de zelfde naam voorkomt in beide modellen.
en
- Deze velden zijn van verschillende gegevenstypen.
-
Bijvoorbeeld:
-
Wanneer twee (of meer) fragmenten met verschillende modellen (bijvoorbeeld
M1,M2) worden gebruikt als mogelijke verwijzingen (Content Reference of Fragment Reference) uit een ander fragment, bijvoorbeeldFragment1MultiField/List -
Deze twee fragmenten met verschillende modellen (
M1,M2) hebben velden met dezelfde naam, maar verschillende typen.
Ter illustratie:M1.TitleasTextM2.TitleasText/MultiField
-
Er treedt dan een fout in het veldconflict op als de GraphQL-query het veld
Titlebevat.
-
-
Veelgestelde vragen
De gerezen vragen:
-
Q: "hoe is GraphQL API voor AEM verschillend van de Bouwer van de Vraag API?"
- A:
"GraphQL API van AEM biedt volledige controle op de output JSON aan, en is een industriestandaard voor het vragen van inhoud.
AEM is van plan om in de AEM GraphQL API te investeren."
- A:
Zelfstudie - Aan de slag met AEM Headless en GraphQL
Op zoek naar een praktische zelfstudie? Controle uit Begonnen het Worden met de Zwaartepunt van AEM en GraphQLleerprogramma van begin tot eind illustrerend hoe te om inhoud op te bouwen en bloot te stellen gebruikend AEM GraphQL APIs en verbruikt door een externe app, in een headless scenario van CMS.