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 met de AEM GraphQL API voor het leveren van inhoud zonder kop.

AEM 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:

Vereisten prerequisites

Klanten die GraphQL gebruiken, moeten het AEM Content Fragment installeren met GraphQL Index Package 1.0.5. Zie de Nota's van de Versievoor verdere details.

De GraphQL API graphql-api

GraphQL is:

Raadpleeg de volgende secties (onder andere over veel andere bronnen) voor meer informatie over de GraphQL API:

De GraphQL for AEM-implementatie is gebaseerd op de standaard GraphQL Java™-bibliotheek. Zie:

GraphQL Terminologie graphql-terminology

GraphQL gebruikt het volgende:

Zie (GraphQL.org) Inleiding aan GraphQLvoor uitvoerige details, met inbegrip van Beste praktijken.

GraphQL-querytypen graphql-query-types

Met GraphQL kunt u query's uitvoeren die worden geretourneerd:

AEM verstrekt mogelijkheden om vragen (beide types) in Verlengde Vragenom te zetten die door Dispatcher en CDN in het voorgeheugen worden opgeslagen.

Aanbevolen werkwijzen voor GraphQL-query (Dispatcher en CDN) graphql-query-best-practices

Geadviseerde vragenzijn de geadviseerde methode om bij te gebruiken publiceert instanties als:

GraphQL-query's die gebruikmaken van POST-aanvragen 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-aanvragen ondersteunt, kunnen deze aanvragen limieten bereiken (bijvoorbeeld de lengte van de URL) die kunnen worden vermeden door middel van doorlopende query's.

Zie toelaten caching van persisted queryvoor verdere details.

GraphiQL Interface graphiql-interface

Een implementatie van de standaard GraphiQLinterface is beschikbaar voor gebruik met AEM GraphQL.

Met deze interface kunt u query's rechtstreeks invoeren en testen.

Bijvoorbeeld:

De klasse biedt functies zoals syntaxismarkering, automatisch aanvullen en automatisch voorstellen, samen met een geschiedenis en online documentatie:

Kwesties gebruiken voor auteur- en Publish-omgevingen use-cases-author-publish-environments

De gebruiksgevallen kunnen afhankelijk zijn van het type AEM omgeving:

Machtigingen permission

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

Ook, moet de gebruiker toegang tot een eindpunt van GraphQL hebben om de vragen van GraphQL in werking te kunnen stellen.

Schema genereren schema-generation

GraphQL is een getypeerde API, wat betekent dat de gegevens duidelijk gestructureerd en ingedeeld moeten zijn op basis van het 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 deze richtlijnen te voltooien, 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.

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

In GraphQL for AEM is het schema flexibel. Deze flexibiliteit betekent dat deze 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 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:

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 GQLschema wordt geroepen. Als u bijvoorbeeld een eenvoudige GET aanvraag uitvoert op /content/cq:graphql/global/endpoint.GQLschema , levert dit de uitvoer op 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 zulk gebeurt, AEM produceert 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 fields

Binnen het schema zijn er afzonderlijke velden, van twee basiscategorieën:

Gegevenstypen data-types

GraphQL for AEM ondersteunt een lijst met typen. Alle ondersteunde gegevenstypen van het inhoudsfragmentmodel en de bijbehorende GraphQL-typen worden weergegeven:

Helpervelden helper-fields

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 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 pad wordt gekozen als de id van een inhoudsfragment, omdat het:

Met de volgende code worden de paden weergegeven van alle inhoudsfragmenten die zijn gemaakt op basis van het inhoudsfragmentmodel Person .

{
  personList {
    items {
      _path
    }
  }
}

Als u één inhoudsfragment van een bepaald type wilt ophalen, moet u ook eerst het pad ervan bepalen. Bijvoorbeeld:

{
  authorByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      firstName
      name
    }
  }
}

Zie Vraag van de Steekproef - Één enkel Specifiek Fragment van de Stad.

Metagegevens metadata

Via GraphQL worden AEM ook de metagegevens van een inhoudsfragment beschikbaar gemaakt. Metagegevens zijn de informatie die een inhoudsfragment beschrijft, zoals het volgende:

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. De TypedMetaData stelt de informatie bloot die door de volgende scalaire types wordt gegroepeerd:

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, is deze eigenschap een eigenschap String, zodat u een query voor alle metagegevens van tekenreeks kunt uitvoeren:

Ga als volgt te werk om te zoeken naar metagegevens:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

U kunt alle GraphQL-typen voor metagegevens weergeven als u het schema Gegenereerde GraphQL weergeeft. Alle modeltypen hebben dezelfde TypedMetaData .

Zie Vraag van de Steekproef voor Meta-gegevens - maak een lijst van de Meta-gegevens voor Uitreiking genoemd GB.

Variaties variations

Het veld _variations is geïmplementeerd om het opvragen van variaties in een inhoudsfragment te vereenvoudigen. Bijvoorbeeld:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _variations
    }
  }
}

Zie Vraag van de Steekproef - Alle Plaatsen met een Benoemde Variatie.

GraphQL-variabelen graphql-variables

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 Article wilt ophalen die een specifieke variatie hebben, kunt u de variabele variation in GraphiQL opgeven.

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
            _variations
        }
    }
}

### in query variables
{
    "variation": "uk"
}

GraphQL-richtlijnen graphql-directives

In GraphQL is er een 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 .

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}

### in query variables
{
    "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 volgende expressie zou bijvoorbeeld de inhoud van het veld vergelijken met de waarde some text en geslaagd zijn als de inhoud gelijk is aan de waarde. Anders mislukt de expressie:

{
  value: "some text"
  _op: EQUALS
}

De volgende operatoren kunnen worden gebruikt om velden met een bepaalde waarde te vergelijken:

Bij sommige typen kunt u ook aanvullende opties opgeven die wijzigen hoe een expressie wordt geëvalueerd:

De uitdrukkingen kunnen aan een reeks met behulp van een logische exploitant (_logOp) worden gecombineerd:

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:

U kunt _logOp weglaten als u items met AND en _operator wilt combineren als u op gelijkheid wilt controleren, omdat deze waarden standaardinstellingen 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
    }
  }
}

Wanneer het uitvoeren van een vraag van GraphQL gebruikend facultatieve variabelen, als een specifieke waarde niet voor de facultatieve variabele is verstrekt, dan zal de variabele in de filterevaluatie worden genegeerd. Dit betekent dat queryresultaten alle waarden bevatten, zowel null als niet null , voor de eigenschap die betrekking heeft op de filtervariabele.

In de query hieronder ziet u bijvoorbeeld waar geen waarde is opgegeven voor de eigenschap lastName :

query getAuthorsFilteredByLastName($authorLastName: String) {
  authorList(filter:
    {
      lastName: {_expressions: {value: $authorLastName}
      }}) {
    items {
      lastName
    }
  }
}

Alle auteurs worden geretourneerd:

{
  "data": {
    "authorList": {
      "items": [
        {
          "lastName": "Hammer"
        },
        {
          "lastName": "Provo"
        },
        {
          "lastName": "Wester"
        },
        {
          "lastName": null
        },
         ...
      ]
    }
  }
}

U kunt ook filteren op geneste velden, maar dit wordt afgeraden omdat dit tot prestatieproblemen kan leiden.

Zie voor meer voorbeelden:

Sorteren sorting

Met deze functie kunt u de zoekresultaten sorteren op basis van een opgegeven veld.

De sorteercriteria:

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 .

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:

Lijstquery - Verschuiven en beperken list-offset-limit

In a ...List vraag kunt u offset en limit gebruiken om een specifieke ondergroep van resultaten terug te keren:

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
      }
    }
  }
}

Gepagineerde query - eerste en volgende paginated-first-after

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.

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
        }
    }
}

GraphQL Persisted Queries - caching inschakelen in Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

Het in cache plaatsen van doorlopende query's is niet standaard ingeschakeld in de Dispatcher. Standaardactivering is niet mogelijk omdat klanten die gebruikmaken van CORS (Cross-Origin Resource Sharing) met meerdere origines hun Dispatcher-configuratie moeten controleren en mogelijk bijwerken.

Het in cache plaatsen van doorlopende query's inschakelen enable-caching-persisted-queries

Om het in cache plaatsen van persisted query's mogelijk te maken, zijn de volgende updates van de Dispatcher-configuratiebestanden vereist:

CORS-configuratie in de Dispatcher cors-configuration-in-dispatcher

Klanten die CORS-aanvragen gebruiken, moeten mogelijk hun CORS-configuratie in de Dispatcher controleren en bijwerken.

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 aantal extensies:

CORS-filter cors-filter

Om tot het eindpunt van GraphQL toegang te hebben, vorm een beleid CORS in de bewaarplaats van de Kit van de klant. Deze configuratie wordt gedaan door een aangewezen OSGi CORS configuratiedossier voor één of meerdere gewenste eindpunten toe te voegen.

Deze configuratie moet een vertrouwde website-oorsprong alloworigin of alloworiginregexp opgeven waarvoor toegang moet worden verleend.

Als u bijvoorbeeld toegang wilt verlenen tot het GraphQL-eindpunt en het voortgeduurde zoekeindpunt voor https://my.domain , kunt u het volgende gebruiken:

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

Als u een ijkpad voor het eindpunt hebt geconfigureerd, kunt u dit ook gebruiken in allowedpaths .

Refererfilter referrer-filter

Naast de configuratie CORS, moet een filter van de Referateur worden gevormd om toegang van derdegastheren toe te staan.

Dit filter wordt gedaan door een aangewezen OSGi de configuratiedossier van de Filter toe te voegen dat:

Als u bijvoorbeeld toegang wilt verlenen voor aanvragen bij de Referenter my.domain , kunt u:

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}

Beperkingen limitations

Om tegen potentiële problemen te beschermen worden er standaardbeperkingen opgelegd aan uw vragen:

U moet zich ook bewust zijn van:

Verificatie authentication

Zie Authentificatie voor Verre AEM GraphQL Vragen over de Fragmenten van de Inhoud.

Veelgestelde vragen faqs

De gerezen vragen:

Zelfstudie - Aan de slag met AEM Headless en GraphQL tutorial

Op zoek naar een praktische zelfstudie? Controle uit Begonnen het Worden met AEM Zwaartepunt 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 hoofdCMS scenario.