GraphQL API AEM voor gebruik met inhoudsfragmenten graphql-api-for-use-with-content-fragments
Leer hoe u inhoudsfragmenten in Adobe Experience Manager (AEM) kunt gebruiken die as a Cloud Service zijn 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.
Door de GraphQL API in AEM te gebruiken, 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.
- AEM Commerce gebruikt gegevens van een Commerce-platform 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.
De GraphQL API graphql-api
GraphQL is:
-
"…een querytaal voor API's en een runtime voor het uitvoeren van deze query's met uw bestaande gegevens. GraphQL biedt een volledige en begrijpelijke beschrijving van de gegevens in uw API, geeft clients de mogelijkheid om precies te vragen wat ze nodig hebben en niets meer, maakt het gemakkelijker om API's in de loop der tijd te ontwikkelen en maakt krachtige ontwikkelaarsgereedschappen mogelijk.".
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 GraphQL verkennen.
-
"…een taal en specificatie voor gegevensquery die in 2012 intern door Facebook zijn ontwikkeld, voordat deze in 2015 openbaar is gemaakt. 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 elke omvang…"
Zie GraphQL Foundation.
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-terminology
GraphQL gebruikt het volgende:
-
- Schema's worden gegenereerd door AEM 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 voor AEM implementatie.
-
-
Het pad in AEM dat reageert op GraphQL-query's en toegang biedt tot de GraphQL-schema's.
-
Zie GraphQL Endpoint inschakelen voor nadere bijzonderheden.
-
Zie de (GraphQL.org) Inleiding tot GraphQL voor uitvoerige informatie, waaronder de Aanbevolen procedures.
GraphQL-querytypen graphql-query-types
Met GraphQL kunt u query's uitvoeren die worden geretourneerd:
-
A enkel item
AEM biedt mogelijkheden om query's (beide typen) om te zetten in Blijvende query's, die in cache kunnen worden geplaatst door Dispatcher en de CDN.
Best practices voor GraphQL-query (Dispatcher en CDN) graphql-query-best-practices
De Blijvende query's zijn de aanbevolen methode voor het publiceren van exemplaren als:
- ze zijn in cache geplaatst
- zij worden centraal beheerd door AEM as a Cloud Service
GraphQL-query's die gebruikmaken van POST-aanvragen worden niet aanbevolen omdat ze niet in de cache zijn opgeslagen, zodat in een standaardinstantie de Dispatcher is geconfigureerd om dergelijke query's te blokkeren.
Hoewel GraphQL ook GET-aanvragen ondersteunt, kunnen deze limieten bereiken (bijvoorbeeld de lengte van de URL) die kunnen worden vermeden door middel van permanente query's.
Zie Het in cache plaatsen van doorlopende query's inschakelen voor nadere bijzonderheden.
- Een Omgevingsvariabele Cloud Manager gebeld
ENABLE_GRAPHQL_ENDPOINT
- met de waarde
true
GraphiQL IDE graphiql-ide
U kunt GraphQL-query's testen en fouten opsporen met de opdracht GraphiQL IDE.
Kwesties gebruiken voor auteur, voorvertoning en publicatie use-cases-author-preview-publish
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 permission
De machtigingen zijn vereist voor toegang tot middelen.
GraphQL query's worden uitgevoerd met toestemming van de AEM gebruiker van het onderliggende verzoek. Als de gebruiker geen leestoegang heeft tot bepaalde fragmenten (die als Elementen worden opgeslagen), zullen zij geen deel van de resultaatreeks worden.
Ook, moet de gebruiker toegang tot een eindpunt van GraphQL hebben om de vragen van GraphQL kunnen uitvoeren.
Schema genereren schema-generation
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. Een client moet hiervoor de opdracht Schema, die alle typen bevat die nodig zijn voor een query.
Voor inhoudsfragmenten zijn de GraphQL-schema's (structuur en typen) gebaseerd op Ingeschakeld Modellen van inhoudsfragmenten en hun gegevenstypen.
Als een gebruiker bijvoorbeeld een Content Fragment Model heeft gemaakt, genaamd Article
AEM vervolgens een GraphQL-type genereert ArticleModel
. De velden in dit type komen overeen met de velden en gegevenstypen die in het model zijn gedefinieerd. Bovendien leidt het tot sommige ingangspunten voor de vragen 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
ArticleModel
bevat diverse velden.-
Drie van hen zijn gecontroleerd door de gebruiker:
author
,main
enreferencearticle
. -
De andere velden zijn automatisch AEM toegevoegd en zijn nuttige methoden voor het verschaffen van informatie over een bepaald inhoudsfragment, in dit voorbeeld (de helpervelden)
_path
,_metadata
,_variations
.
-
-
Nadat een gebruiker een inhoudsfragment heeft gemaakt op basis van het artikelmodel, kan het vervolgens worden ondervraagd via GraphQL. Zie voor voorbeelden de Voorbeeldquery's (op basis van een voorbeeldstructuur van inhoudsfragment voor gebruik met GraphQL).
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:
-
Een pakket installeren met
Content-Fragment-Model-1
enContent-Fragment-Model-2
:- GraphQL-typen voor
Model-1
enModel-2
worden gegenereerd.
- GraphQL-typen voor
-
Vervolgens wijzigen
Content-Fragment-Model-2
:-
Alleen de
Model-2
GraphQL-type wordt bijgewerkt. -
Overwegende dat
Model-1
blijft hetzelfde.
-
Het 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 wordt geroepen GQLschema
. U kunt bijvoorbeeld een eenvoudige GET
verzoek op /content/cq:graphql/global/endpoint.GQLschema
resulteert in de uitvoer van het schema met het inhoudstype: text/x-graphql-schema;charset=iso-8859-1
.
Schema genereren - Niet-gepubliceerde modellen schema-generation-unpublished-models
Wanneer Inhoudsfragmenten zijn genest, kan een bovenliggend inhoudsfragmentmodel worden gepubliceerd, maar een model waarnaar wordt verwezen, niet.
Wanneer dit gebeurt, AEM een onvolledig Schema voor het bovenliggende inhoudsfragmentmodel. Dit betekent dat de fragmentverwijzing, die afhankelijk is van het niet-gepubliceerde model, uit het schema wordt verwijderd.
Velden fields
Binnen het schema zijn er afzonderlijke velden, van twee basiscategorieën:
-
Velden die u genereert.
Een selectie van Gegevenstypen worden gebruikt om velden te maken die zijn gebaseerd op de manier waarop u het inhoudsfragmentmodel configureert. De veldnamen zijn afkomstig uit het Eigenschapnaam van het Gegevenstype tab.
- Er is ook Renderen als rekening houden met de instelling, aangezien gebruikers bepaalde gegevenstypen kunnen configureren. U kunt bijvoorbeeld een tekstveld bestaande uit een enkele regel zo configureren dat het meerdere tekstregels bevat door
multifield
in de vervolgkeuzelijst.
- Er is ook Renderen als rekening houden met de instelling, aangezien gebruikers bepaalde gegevenstypen kunnen configureren. U kunt bijvoorbeeld een tekstveld bestaande uit een enkele regel zo configureren dat het meerdere tekstregels bevat door
-
GraphQL for AEM genereert ook een aantal helpervelden.
Gegevenstypen data-types
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]
Boolean
Calendar
onlyDate
, onlyTime
, dateTime
String
[String]
String
, [String]
Enkel veld:
Model
- Modeltype, rechtstreeks verwezenMeerdere velden, met één type waarnaar wordt verwezen:
[Model]
- Array van type Model
, rechtstreeks vanaf een arrayMeerdere velden, met meerdere typen waarnaar wordt verwezen:
[AllFragmentModels]
- Array van alle modeltypen, met verwijzing van array met type unionHelpervelden helper-fields
Naast de gegevenstypen voor door de gebruiker gegenereerde velden, genereert GraphQL for AEM ook verschillende helper velden voor het herkennen van een inhoudsfragment of voor aanvullende informatie over een inhoudsfragment.
Deze helpervelden zijn gemarkeerd met een voorgaande _
om onderscheid te maken tussen wat door de gebruiker is gedefinieerd en wat automatisch is gegenereerd.
Pad path
Het padveld wordt gebruikt als een identifier in AEM GraphQL. Het vertegenwoordigt het pad van het Content Fragment-element in de AEM opslagplaats. Dit is de id van een inhoudsfragment, omdat dit:
- uniek is binnen AEM,
- kan gemakkelijk worden opgehaald.
De volgende code geeft de paden weer van alle inhoudsfragmenten die zijn gemaakt op basis van het model van het inhoudsfragment Author
, zoals verstrekt 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 Voorbeeldquery - één specifiek stedenfragment.
Metagegevens metadata
Via GraphQL worden AEM ook de metagegevens van een inhoudsfragment beschikbaar gemaakt. 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, TypedMetaData
Het GraphQL-type is 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
.
Houd er rekening mee dat
StringMetadata
en StringArrayMetadata
beide verwijzen naar wat in de bewaarplaats wordt opgeslagen, niet hoe u hen terugwint.stringMetadata
veld, ontvangt u een array van alle metagegevens die in de repository zijn opgeslagen als een String
en als u stringArrayMetadata
u ontvangt dan een array met alle metagegevens die in de repository zijn opgeslagen als String[]
.Zie Voorbeeldquery voor metagegevens - Lijst met metagegevens voor onderscheidingen: GB.
Variaties variations
De _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
veld bevat geen master
variatie, als technisch gezien de oorspronkelijke gegevens (als Master in de gebruikersinterface) wordt niet als een expliciete wijziging beschouwd.Zie Voorbeeldquery - Alle steden met een benoemde variatie.
GraphQL-variabelen graphql-variables
GraphQL staat toe dat variabelen in de query worden geplaatst. Zie voor meer informatie GraphQL-documentatie voor variabelen.
Als u bijvoorbeeld alle inhoudsfragmenten van het type wilt ophalen Author
in een specifieke variatie (indien beschikbaar), kunt u het argument specificeren variation
in GraphiQL.
Query:
query($variation: String!) {
authorList(variation: $variation) {
items {
_variation
lastName
firstName
}
}
}
Query-variabelen:
{
"variation": "another"
}
Deze query retourneert de volledige lijst met auteurs. Auteurs zonder de another
de wijziging wordt teruggebracht naar de oorspronkelijke gegevens (_variation
rapporteren master
in dit geval).
Een filter, als u de lijst wilt beperken tot auteurs die de opgegeven variatie leveren (en auteurs overslaan die terugvallen naar de oorspronkelijke gegevens):
query($variation: String!) {
authorList(variation: $variation, filter: {
_variation: {
_expressions: {
value: $variation
}
}
}) {
items {
_variation
lastName
firstName
}
}
}
GraphQL-richtlijnen graphql-directives
In GraphQL bestaat de mogelijkheid om de query te wijzigen op basis van variabelen, de zogenaamde GraphQL-richtlijnen.
Hier kunt u bijvoorbeeld de opdracht adventurePrice
veld in een query voor alle AdventureModels
, gebaseerd op een variabele includePrice
.
Query:
query GetAdventureByType($includePrice: Boolean!) {
adventureList {
items {
title
price @include(if: $includePrice)
}
}
}
Query-variabelen:
{
"includePrice": true
}
Filteren filtering
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
}
zou de inhoud van het veld vergelijken met de waarde some text
en slaagt als de inhoud de waarde evenaart. Anders zal de expressie mislukken.
De volgende operatoren kunnen worden gebruikt om velden met een bepaalde waarde te vergelijken:
EQUALS
String
, ID
, Boolean
EQUALS_NOT
String
, ID
CONTAINS
String
{ value: "mas", _op: CONTAINS }
komt overeen Christmas
, Xmas
, master
, …)CONTAINS_NOT
String
STARTS_WITH
ID
{ value: "/content/dam/", _op: STARTS_WITH
komt overeen /content/dam/path/to/fragment
, maar niet /namespace/content/dam/something
EQUAL
Int
, Float
UNEQUAL
Int
, Float
GREATER
Int
, Float
GREATER_EQUAL
Int
, Float
LOWER
Int
, Float
LOWER_EQUAL
Int
, Float
AT
Calendar
, Date
, Time
NOT_AT
Calendar
, Date
, Time
BEFORE
Calendar
, Date
, Time
AT_OR_BEFORE
Calendar
, Date
, Time
AFTER
Calendar
, Date
, Time
AT_OR_AFTER
Calendar
, Date
, Time
Bij sommige typen kunt u ook aanvullende opties opgeven die wijzigen hoe een expressie wordt geëvalueerd:
_ignoreCase
String
time
overeenkomsten TIME
, time
, tImE
, …_sensitiveness
Float
float
als hetzelfde te beschouwen waarden (om technische beperkingen te omzeilen als gevolg van de interne representatie van float
waarden; moet worden vermeden, aangezien deze optie een negatief effect kan hebben op de prestatiesExpressies kunnen met behulp van een logische operator worden gecombineerd tot een set (_logOp
):
OR
- de reeks expressies zal slagen als ten minste één expressie slaagtAND
- de reeks expressies zal slagen 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 de filter
argument voor een query) bevat:
- Een subdefinitie voor elk gebied (het gebied kan door zijn naam worden betreden, bijvoorbeeld, is er een
lastName
veld in het filter voor delastName
veld in het gegevenstype (veld) - Elke subdefinitie bevat de
_expressions
array, die de expressieset en de_logOp
veld waarin de logische operator wordt gedefinieerd, moeten de expressies worden gecombineerd met - Elke expressie wordt gedefinieerd door de waarde (
value
veld) en de operator (_operator
veld) de inhoud van een veld moet worden vergeleken met
U kunt weglaten _logOp
als je objecten wilt combineren met AND
en _operator
als u op gelijkheid wilt controleren, aangezien dit de standaardwaarden zijn.
Het volgende voorbeeld toont een volledige vraag aan die alle personen filtert die een lastName
van Provo
of die sjö
onafhankelijk van de zaak:
{
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:
-
nadere gegevens over de GraphQL for AEM extensions
-
Voorbeeldquery's met deze voorbeeldinhoud en -structuur
- En de Voorbeeldinhoud en -structuur voorbereid voor gebruik in voorbeeldquery's
Sorteren sorting
Met 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 in de notatie nestedFragmentname.fieldname
.
Bijvoorbeeld:
query {
articleList(sort: "authorFragment.lastName") {
items {
title
authorFragment {
firstName
lastName
birthDay
}
slug
}
}
}
Paginering paging
Met deze functie kunt u pagineren uitvoeren op querytypen die een lijst retourneren. Er zijn twee methoden:
offset
enlimit
in eenList
queryfirst
enafter
in eenPaginated
query
Lijstquery - Verschuiven en beperken list-offset-limit
In een ...List
query die u kunt gebruiken offset
en limit
om een specifieke subset van resultaten te retourneren:
offset
: Geeft de eerste gegevensset aan die moet worden geretourneerdlimit
: Geeft het maximale aantal gegevenssets op dat moet worden geretourneerd
Als u bijvoorbeeld de resultatenpagina wilt weergeven met maximaal vijf artikelen, te beginnen bij het vijfde artikel van het dialoogvenster complete resultatenlijst:
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 resultaatreeksen is de gepagineerde vraag met te gebruiken
first
enafter
methode.
Gepagineerde query - eerste en volgende paginated-first-after
De ...Paginated
het vraagtype gebruikt het grootste deel van ...List
functies voor querytypen (filteren, sorteren), maar in plaats van offset
/limit
argumenten, gebruikt het de first
/after
argumenten zoals gedefinieerd door de GraphQL Cursor Connections Specification. U vindt een minder formele introductie in het dialoogvenster Inleiding GraphQL.
first
: Den
eerste objecten die moeten worden geretourneerd.
De standaardwaarde is50
.
Het maximum is100
.after
: De cursor die het begin van de opgevraagde pagina bepaalt; het item dat door de cursor wordt vertegenwoordigd, wordt niet opgenomen in de resultatenset; de cursor van een item wordt bepaald door decursor
van hetedges
structuur.
Voer bijvoorbeeld de resultatenpagina uit met maximaal vijf avonturen, te beginnen bij het opgegeven cursoritem in het dialoogvenster complete resultatenlijst:
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
sort
wordt 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 web-optimized-image-delivery-in-graphql-queries
Met webgeoptimaliseerde afbeeldingslevering kunt u een grafische query gebruiken:
-
Een URL aanvragen naar een DAM-elementafbeelding (waarnaar wordt verwezen door een Content Reference)
-
Geef parameters door met de query, zodat er automatisch een specifieke uitvoering van de afbeelding wordt gegenereerd en geretourneerd
note note NOTE De 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
U kunt AEM gebruiken om:
- Voldoende Webgeoptimaliseerde afbeeldingslevering in GraphQL-query's.
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
_dynamicUrl
op deImageRef
referentie -
Parameters doorgeven: toevoegen
_assetTransform
aan de lijstkopbal waar uw filters worden bepaald
Structuur van het transformatieverzoek structure-transformation-request
AssetTransform
(_assetTransform
) wordt gebruikt om de URL-transformatieaanvragen in te dienen.
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 kaderheight
: de hoogte van het frame
-
size
: een dimensiesubstructuur, 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 wordt gegeven aan een webpagina (de standaardwaarde is false)
De transformatie URL is beschikbaar voor alle vraagtypes: door weg, lijst of gepagineerd.
Voor het web geoptimaliseerde afbeeldingslevering met volledige parameters web-optimized-image-delivery-full-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 web-optimized-image-delivery-single-query-variable
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 web-optimized-image-delivery-multiple-query-variables
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 web-optimized-image-delivery-request-url
Als u de query opslaat als een doorlopende query (bijvoorbeeld met de naam dynamic-url-x
) kunt u vervolgens De voortgezette query rechtstreeks uitvoeren.
Gebruik bijvoorbeeld de volgende URL's om de vorige voorbeelden (opgeslagen als voortgeduurde query's) rechtstreeks uit te voeren:
-
Enkele parameter; Blijvende query genaamd
dynamic-url-x
-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic-url-x;seoName=xxx
Het antwoord ziet er als volgt uit:
-
-
Meerdere parameters; Blijvende query genaamd
dynamic
-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic;seoName=billiboy;format=GIF;
note caution CAUTION De navolgende ;
is verplicht de lijst met parameters zorgvuldig te beëindigen.
-
Beperkingen voor de levering van webgeoptimaliseerde afbeeldingen web-optimized-image-delivery-limitations
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)
GraphQL for AEM - Overzicht van extensies graphql-extensions
De basisverrichting van vragen met GraphQL voor AEM voldoet 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:
- toevoegen
List
op de modelnaam, bijvoorbeeldcityList
- Zie Voorbeeldquery - Alle informatie over alle steden
U kunt dan:
-
ASC
: oplopendDESC
: aflopend
-
Retourneer een pagina met resultaten met:
- toevoegen
-
Het filter
includeVariations
is opgenomen in deList
enPaginated
querytypen. Als u Variaties in inhoudsfragmenten wilt ophalen in de queryresultaten, voert u de opdrachtincludeVariations
filter moet worden ingesteld optrue
.- Zie Voorbeeldquery voor meerdere inhoudsfragmenten en de bijbehorende variaties van een bepaald model
note caution CAUTION Het filter includeVariations
en het door het systeem gegenereerde veld_variation
kan niet samen in de zelfde vraagdefinitie worden gebruikt. -
Als u logische OR wilt gebruiken:
- gebruiken
_logOp: OR
- Zie Voorbeeldquery - Alle personen met de naam "Jobs" of "Smith"
- 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
: Vragen naar een inhoudsfragmentmodel toestaan (pad en titel) -
_path
: het pad naar het inhoudsfragment in de opslagplaats -
_reference
: om verwijzingen weer te geven; inline-verwijzingen opnemen in de Rich Text Editor -
_variation
: om specifieke variaties in het inhoudsfragment weer te gevennote note NOTE Als de opgegeven variatie niet bestaat voor een inhoudsfragment, wordt de hoofdvariatie geretourneerd als een standaardinstelling (fallback). note caution CAUTION Het systeemgegenereerde veld _variation
kan niet samen met het filter worden gebruiktincludeVariations
.
-
-
Voor levering van de afbeelding:
-
_authorURL
: de volledige URL naar het afbeeldingselement op AEM auteur -
_publishURL
: de volledige URL naar het afbeeldingselement bij AEM Publiceren -
Voor voor het web geoptimaliseerde afbeeldingslevering (van DAM-activa):
-
_dynamicUrl
: de volledige URL naar het voor het web geoptimaliseerde DAM-element op het tabbladImageRef
referentienote note NOTE _dynamicUrl
is de voorkeurs-URL die u wilt gebruiken voor voor het web geoptimaliseerde DAM-middelen en moet het gebruik van_path
,_authorUrl
, en_publishUrl
waar mogelijk. -
_assetTransform
: om parameters door te geven op de lijstkop waar de filters zijn gedefinieerd -
Zie:
-
-
-
_tags
: om de id's weer te geven van inhoudsfragmenten of variaties die tags bevatten; dit is een array vancq:tags
id's.- Zie Voorbeeldquery - Namen van alle steden die zijn getagd als stadseinden
- Zie Voorbeeldquery voor variaties van inhoudsfragmenten van een bepaald model waaraan een specifieke tag is gekoppeld
- Zie Voorbeeldquery met filtering op _tags-id en exclusief variaties
- Zie Voorbeeldquery met filteren op _tags-id en inclusief variaties
note note NOTE Tags kunnen ook worden opgevraagd door de metagegevens van een inhoudsfragment weer te geven. -
En bewerkingen:
-
_operator
: specifieke exploitanten toepassen;EQUALS
,EQUALS_NOT
,GREATER_EQUAL
,LOWER
,CONTAINS
,STARTS_WITH
-
_apply
: specifieke voorwaarden toepassen, bijvoorbeeldAT_LEAST_ONCE
-
_ignoreCase
: om de zaak te negeren bij het vragen
-
-
-
GraphQL-union-typen worden ondersteund:
-
Extra fallback bij het opvragen van geneste fragmenten:
- Als een bepaalde variatie niet bestaat in een genest fragment, wordt de Master variatie wordt geretourneerd.
Het GraphQL-eindpunt van een externe website opvragen query-graphql-endpoint-from-external-website
Om tot het eindpunt van GraphQL van een externe website toegang te hebben moet u vormen:
Verificatie authentication
Zie Verificatie voor externe AEM GraphQL-query's op inhoudsfragmenten.
Beperkingen limitations
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:
-
Dus waar:
- Twee (of meer modellen) worden gebruikt als mogelijke verwijzingen; wanneer zij als toegestaan worden gedefinieerd Modeltype in de Content Fragment reference.
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, bijvoorbeeldFragment1
MultiField/List
-
Deze twee fragmenten met verschillende modellen (
M1
,M2
) hebben velden met dezelfde naam, maar verschillende typen.
Ter illustratie:M1.Title
alsText
M2.Title
alsText/MultiField
-
Dan zal een fout van het gebiedsconflict voorkomen als de vraag van GraphQL bevat
Title
veld.
-
-
Veelgestelde vragen faqs
De gerezen vragen:
-
Q: "Hoe verschilt de GraphQL API voor AEM van de Query Builder-API?"
- A: "De AEM GraphQL API biedt volledige controle op de JSON-uitvoer en is een industriestandaard voor het opvragen van inhoud.
AEM is van plan om in de AEM GraphQL API te investeren."
- A: "De AEM GraphQL API biedt volledige controle op de JSON-uitvoer en is een industriestandaard voor het opvragen van inhoud.
Zelfstudie - Aan de slag met AEM Headless en GraphQL tutorial
Op zoek naar een praktische zelfstudie? Uitchecken Aan de slag met AEM Headless en GraphQL end-to-end zelfstudie waarin wordt geïllustreerd hoe u in een CMS-scenario inhoud kunt ontwikkelen en beschikbaar maken met behulp van AEM GraphQL API's en die door een externe toepassing wordt verbruikt.