AEM GraphQL API voor gebruik met Content Fragments

Leer hoe u Content Fragments 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:

  • 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.
OPMERKING

GraphQL wordt momenteel gebruikt in twee (afzonderlijke) scenario's in Adobe Experience Manager (AEM):

De 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. GrafiekQL op uw bestaande achtergronden plaatsen om producten sneller dan ooit te bouwen…".

    Zie GrafiekQL verkennen.

  • "…een taal en specificatie voor gegevensquery die in 2012 intern door Facebook zijn ontwikkeld, voordat deze in 2015 openbaar is 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 elke grootte…"

    Zie GraphQL Foundation.

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

GraphQL voor AEM implementatie is gebaseerd op de standaard Java Library GraphQL. Zie:

GraphQL-terminologie

GraphQL gebruikt het volgende:

  • Zoekopdrachten

  • Schema's en typen:

    • Schema's worden gegenereerd door AEM op basis van de modellen van inhoudsfragmenten.
    • Gebruikend uw schema's, stelt GraphQL de types en verrichtingen voor toegelaten GraphQL voor AEM implementatie voor.
  • Velden

  • GraphQL-eindpunt

    • De weg in AEM die aan vragen GraphQL antwoordt, en toegang tot de schema's GraphQL verleent.

    • Zie GrafiekQL-eindpunt inschakelen voor nadere bijzonderheden.

Zie de (GraphQL.org) Inleiding tot GraphQL voor uitvoerige informatie, waaronder Aanbevolen werkwijzen.

GraphQL-querytypen

Met GraphQL kunt u vragen uitvoeren om of terug te keren:

U kunt ook het volgende uitvoeren:

OPMERKING

U kunt vragen van GraphQL testen en zuiveren gebruikend GraphiQL IDE.

GraphQL voor AEM Endpoint

Het eindpunt is de weg die wordt gebruikt om tot GraphQL voor AEM toegang te hebben. Met dit pad kunt u (of uw app) het volgende doen:

  • toegang tot het GraphQL-schema;
  • verzend uw vragen GraphQL,
  • ontvangt de reacties (op uw vragen GraphQL).

Er zijn twee soorten eindpunten in AEM:

  • Algemeen
    • Beschikbaar voor gebruik door alle sites.
    • Dit eindpunt kan alle Modellen van het Fragment van de Inhoud van alle configuraties van Plaatsen gebruiken (die in Configuratiebrowser).
    • Als er om het even welke Modellen van het Fragment van de Inhoud zijn die onder de configuraties van Plaatsen zouden moeten worden gedeeld, dan zouden deze onder de globale configuraties van Plaatsen moeten worden gecreeerd.
  • Siteconfiguraties:
    • Komt overeen met een configuratie Sites, zoals gedefinieerd in het dialoogvenster Configuratiebrowser.
    • Specifiek voor een opgegeven site/project.
    • Een configuratie-specifiek eindpunt van Plaatsen zal de Modellen van het Fragment van de Inhoud van die specifieke configuratie van Plaatsen samen met die van de globale configuratie van Plaatsen gebruiken.
LET OP

Met de Inhoudsfragmenteditor kan een inhoudsfragment van een siteconfiguratie verwijzen naar een inhoudsfragment van een andere siteconfiguratie (via beleid).

In een dergelijk geval zal niet alle inhoud kunnen terugwinnen gebruikend een de configuratie van Plaatsen specifiek eindpunt.

De inhoudauteur zou dit scenario moeten controleren; Het kan bijvoorbeeld handig zijn om gedeelde modellen van inhoudsfragmenten onder de configuratie Algemene sites te plaatsen.

De bewaarplaatspad van GraphQL voor AEM globale eindpunt is:

/content/cq:graphql/global/endpoint

Voor welke toepassing uw toepassing het volgende pad in de aanvraag-URL kan gebruiken:

/content/_cq_graphql/global/endpoint.json

Om een eindpunt voor GraphQL voor AEM toe te laten moet u:

GrafiekQL-eindpunt inschakelen

Om een Eindpunt te toelaten GraphQL moet u eerst een aangewezen configuratie hebben. Zie Inhoudsfragmenten - Configuratiebrowser.

LET OP

Als de gebruik van inhoudsfragmentmodellen is niet ingeschakeldde Maken is niet beschikbaar.

Om het overeenkomstige eindpunt toe te laten:

  1. Navigeren naar Gereedschappen, Activa selecteert u vervolgens GraphQL.

  2. Selecteer Maken.

  3. De Nieuw GraphQL-eindpunt maken wordt geopend. Hier kunt u opgeven:

    • Naam: naam van het eindpunt; U kunt elke gewenste tekst invoeren.
    • GrafiekQL-schema gebruiken dat is opgegeven door: Gebruik de vervolgkeuzelijst om de gewenste site of het vereiste project te selecteren.
    OPMERKING

    De volgende waarschuwing wordt weergegeven in het dialoogvenster:

    • De eindpunten van GraphQL kunnen gegevensveiligheid en prestatieskwesties introduceren als niet zorgvuldig beheerd. Gelieve te verzekeren om aangewezen toestemmingen te plaatsen na het creëren van een eindpunt.
  4. Bevestigen met Maken.

  5. De Volgende stappen de dialoog zal een directe verbinding aan de console van de Veiligheid verstrekken zodat u kunt ervoor zorgen dat het onlangs gecreeerde eindpunt geschikte toestemmingen heeft.

    LET OP

    Het eindpunt is toegankelijk voor iedereen. Dit kan - vooral bij publiceer instanties - een veiligheidszorg veroorzaken, aangezien de vragen GraphQL een zware lading op de server kunnen opleggen.

    U kunt opstelling ACLs, aangewezen aan uw gebruiksgeval, op het eindpunt.

Het Eindpunt GraphQL publiceren

Selecteer het nieuwe eindpunt en Publiceren om het volledig beschikbaar te maken in alle milieu's.

LET OP

Het eindpunt is toegankelijk voor iedereen.

Bij het publiceren van instanties kan dit een veiligheidszorg veroorzaken, aangezien de vragen GraphQL een zware lading op de server kunnen opleggen.

U moet opstelling ACLs aangewezen aan uw gebruiksgeval op het eindpunt.

GraphiQL Interface

Tenuitvoerlegging van de norm GraphiQL interface is beschikbaar voor gebruik met AEM GraphQL. Dit kan geïnstalleerd met AEM.

OPMERKING

GraphiQL is gebonden het globale eindpunt (en werkt niet met andere eindpunten voor specifieke configuraties van Plaatsen).

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

Bijvoorbeeld:

  • http://localhost:4502/content/graphiql.html

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

GraphiQL Interface

De interface AEM GraphiQL installeren

De GraphiQL-gebruikersinterface kan worden geïnstalleerd op AEM met een toegewezen pakket: de GraphiQL-inhoudspakket v0.0.6 (2021.3) pakket.

OPMERKING

Het beschikbare pakket is volledig compatibel met AEM 6.5.10.0 en AEM as a Cloud Service.

Kwesties gebruiken voor auteur- en publicatie-omgevingen

De gebruiksgevallen kunnen afhankelijk zijn van het type AEM omgeving:

  • Publicatie-omgeving; gebruikt voor:

    • Query-gegevens voor JS-toepassing (standaardgebruikscenario)
  • Auteursomgeving; gebruikt voor:

    • Query-gegevens voor "inhoudsbeheerdoeleinden":
      • GraphQL in AEM 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 middelen.

Schema genereren

GraphQL is een sterk getypte API, wat betekent dat de gegevens duidelijk gestructureerd en georganiseerd moeten zijn door type.

De specificatie GraphQL verstrekt een reeks richtlijnen op hoe te om tot een robuuste API voor het ondervragen van gegevens over een bepaalde instantie te leiden. Om dit te doen, moet een cliënt halen 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.

LET OP

Alle schema's GraphQL (die uit de Modellen van het Fragment van de Inhoud worden afgeleid die zijn Ingeschakeld) zijn leesbaar door het eindpunt GraphQL.

Dit betekent dat u ervoor moet zorgen dat er geen gevoelige gegevens beschikbaar zijn, aangezien deze op deze manier kunnen worden gelekt; Dit omvat bijvoorbeeld informatie die als veldnamen in de modeldefinitie aanwezig kan zijn.

Als een gebruiker bijvoorbeeld een Content Fragment Model heeft gemaakt, genaamd ArticleAEM het object genereren article van een type ArticleModel. De velden in dit type komen overeen met de velden en gegevenstypen die in het model zijn gedefinieerd.

  1. A Content Fragment Model:

    Inhoudsfragmentmodel voor gebruik met GraphQL
  2. Het corresponderende GraphQL-schema (uitvoer van de automatische documentatie GraphiQL):
    GrafiekQL-schema gebaseerd op inhoudsfragmentmodel

    Dit toont aan dat het geproduceerde type ArticleModel bevat diverse velden.

    • Drie van hen zijn gecontroleerd door de gebruiker: author, main en referencearticle.

    • De andere velden zijn automatisch toegevoegd door AEM en zijn nuttige methoden voor het verschaffen van informatie over een bepaald inhoudsfragment. in dit voorbeeld: _path, _metadata, _variations. Deze helpervelden zijn gemarkeerd met een voorgaande _ om onderscheid te maken tussen wat door de gebruiker is gedefinieerd en wat automatisch is gegenereerd.

  3. Nadat een gebruiker tot een Fragment van de Inhoud leidt dat op het model van het Artikel wordt gebaseerd, kan het dan door GraphQL worden ondervraagd. Zie voor voorbeelden de Voorbeeldquery's (op basis van een structuur van voorbeeldinhoudsfragment voor gebruik met GraphQL).

In GraphQL voor 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 dienst van GrafiekQL van Plaatsen luistert (in de achtergrond) naar om het even welke die wijzigingen aan een Model van het Fragment van de Inhoud worden aangebracht. Wanneer updates worden ontdekt, slechts wordt dat deel van het schema opnieuw geproduceerd. Deze optimalisatie bespaart tijd en zorgt voor stabiliteit.

Als u bijvoorbeeld:

  1. Een pakket installeren met Content-Fragment-Model-1 en Content-Fragment-Model-2:

    1. GraphQL-typen voor Model-1 en Model-2 wordt gegenereerd.
  2. Vervolgens wijzigen Content-Fragment-Model-2:

    1. Alleen de Model-2 Het type GraphQL wordt bijgewerkt.

    2. Overwegende Model-1 blijft hetzelfde.

OPMERKING

Dit is belangrijk om op te merken voor het geval u bulkupdates op de Modellen van het Fragment van de Inhoud door REST api, of anders wilt doen.

Het schema wordt gediend door het zelfde eindpunt zoals de vragen 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

Wanneer Inhoudsfragmenten zijn genest, kan een bovenliggend inhoudsfragmentmodel worden gepubliceerd, maar een model waarnaar wordt verwezen, niet.

OPMERKING

De AEM UI verhindert dit gebeurt, maar als het publiceren programmatically, of met inhoudspakketten wordt gemaakt, kan het voorkomen.

Wanneer dit gebeurt, genereert 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.

Fields

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

  • Velden die u genereert.

    Een selectie van Veldtypen 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.

    • Er is ook Renderen als in aanmerking te nemen eigenschap, omdat gebruikers bepaalde gegevenstypen kunnen configureren; bijvoorbeeld als tekst met één regel of als een tekstveld met meerdere regels.
  • GraphQL voor AEM genereert ook een aantal helpervelden.

    Deze worden gebruikt om een inhoudsfragment te identificeren of om meer informatie over een inhoudsfragment te krijgen.

Veldtypen

GraphQL voor AEM ondersteunt een lijst met typen. Alle ondersteunde gegevenstypen van het Content Fragment Model en de corresponderende typen GraphQL worden weergegeven:

Inhoudsfragmentmodel - Gegevenstype Type GraphQL Beschrijving
Tekst met één regel String, [String] Wordt gebruikt voor eenvoudige tekenreeksen, zoals namen van auteurs, locaties, enzovoort.
Tekst met meerdere regels Tekenreeks Wordt gebruikt voor het uitvoeren van tekst, zoals de hoofdtekst van een artikel
Getal Float [Float] Wordt gebruikt om het zwevende-kommagetal en de reguliere getallen weer te geven
Boolean Boolean Gebruikt om selectievakjes weer te geven → eenvoudige true/false-instructies
Datum en tijd Kalender Wordt gebruikt om datum en tijd weer te geven in de ISO 8086-indeling. Afhankelijk van het geselecteerde type, zijn er drie aroma's beschikbaar voor gebruik in AEM GraphQL: onlyDate, onlyTime, dateTime
Opsomming Tekenreeks Wordt gebruikt om een optie weer te geven uit een lijst met opties die bij het maken van het model zijn gedefinieerd
Tags [Tekenreeks] Wordt gebruikt om een lijst weer te geven met tekenreeksen die tags vertegenwoordigen die in AEM worden gebruikt
Content Reference Tekenreeks Wordt gebruikt om het pad naar een ander element in AEM weer te geven
Fragmentverwijzing Een modeltype Wordt gebruikt om te verwijzen naar een ander inhoudsfragment van een bepaald modeltype, dat is gedefinieerd toen het model werd gemaakt.

Helpervelden

Naast de gegevenstypen voor door de gebruiker gegenereerde velden, genereert GraphQL voor AEM ook een aantal helper velden voor het herkennen van een inhoudsfragment of voor het verschaffen van aanvullende informatie over een inhoudsfragment.

Pad

Het padveld wordt gebruikt als id in 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 Person.

{
  personList {
    items {
      _path
    }
  }
}

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

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

Zie Voorbeeldquery - één specifiek stedenfragment.

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, TypedMetaData Het type GraphQL 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:

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

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

U kunt alle types van meta-gegevensGrafiekQL bekijken als u het Gegenereerde schema GraphQL bekijkt. Alle modeltypen hebben dezelfde TypedMetaData.

OPMERKING

Verschil tussen normale metagegevens en arraymetagegevens
Houd er rekening mee dat StringMetadata en StringArrayMetadata beide verwijzen naar wat in de bewaarplaats wordt opgeslagen, niet hoe u hen terugwint.

Bijvoorbeeld door de 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

De _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 Voorbeeldquery - Alle steden met een benoemde variatie.

OPMERKING

Als de opgegeven variatie niet bestaat voor een inhoudsfragment, wordt de master variatie geretourneerd als standaard (fallback).

GrafiekQL-variabelen

GraphQL laat variabelen toe om in de vraag worden geplaatst. Voor meer informatie kunt u de GraphQL-documentatie voor variabelen.

Als u bijvoorbeeld alle inhoudsfragmenten van het type wilt ophalen Article die een specifieke variatie hebben, kunt u de variabele opgeven variation in GraphiQL.

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

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

GraphQL-richtlijnen

In GraphQL is er een mogelijkheid om de vraag te veranderen die op variabelen wordt gebaseerd, genoemd Richtlijnen GraphQL.

U kunt bijvoorbeeld de opdracht adventurePrice veld in een query voor alle AdventureModels, gebaseerd op een variabele includePrice.

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

### in query variables
{
    "includePrice": true
}

Filteren

U kunt het filtreren in uw vragen gebruiken GraphQL om specifieke gegevens terug te keren.

Bij het filteren wordt een syntaxis gebruikt die is gebaseerd op logische operatoren en expressies.

Met de volgende (basis)query worden bijvoorbeeld alle personen gefilterd die een naam hebben van Jobs of Smith:

query {
  personList(filter: {
    name: {
      _logOp: OR
      _expressions: [
        {
          value: "Jobs"
        },
        {
          value: "Smith"
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

Zie voor meer voorbeelden:

GraphQL voor AEM - Overzicht van extensies

De basisverrichting van vragen met GraphQL voor AEM houdt zich aan de standaardspecificatie GraphQL. Voor vragen GraphQL met AEM zijn er een paar uitbreidingen:

Blijvende query's (cache)

Na het voorbereiden van een vraag met een verzoek van de POST, kan het met een verzoek van de GET worden uitgevoerd dat door de geheime voorgeheugens van HTTP of een CDN kan worden in het voorgeheugen ondergebracht.

Dit wordt vereist aangezien de vragen van de POST gewoonlijk niet in het voorgeheugen ondergebracht zijn, en als het gebruiken van GET met de vraag als parameter er een significant risico is dat de parameter voor de diensten en tussenpersonen van HTTP te groot wordt.

De aanhoudende vragen moeten altijd het eindpunt met betrekking tot geschikte configuratie Sites; zodat ze beide of beide kunnen gebruiken:

  • De globale configuratie en het eindpunt de vraag heeft toegang tot alle Modellen van het Fragment van de Inhoud.
  • De specifieke configuratie(s) van Plaatsen en eindpunt(s) Creërend een persisted vraag voor een specifieke configuratie van Plaatsen vereist een overeenkomstig plaats-configuratie-specifiek eindpunt (om toegang tot de verwante Modellen van het Fragment van de Inhoud te verlenen).
    Bijvoorbeeld, om een voortgeduurde vraag specifiek voor de configuratie van Plaatsen te creëren WKND, moet een overeenkomstige WKND-Specifieke configuratie van Plaatsen, en een WKND-Specifiek eindpunt vooraf worden gecreeerd.
OPMERKING

Zie Functionaliteit van inhoudsfragment inschakelen in configuratievenster voor meer informatie .

De GraphQL-vragen over persistentie moet worden toegelaten, voor de aangewezen configuratie van Plaatsen.

Als er bijvoorbeeld een bepaalde query wordt uitgevoerd, my-query, die een model gebruikt my-model vanuit de configuratie Sites my-conf:

  • U kunt een query maken met de opdracht my-conf specifiek eindpunt, en dan zal de vraag als volgt worden bewaard:
    /conf/my-conf/settings/graphql/persistentQueries/my-query
  • U kunt dezelfde query maken met global eindpunt, maar dan zal de vraag als volgt worden bewaard:
    /conf/global/settings/graphql/persistentQueries/my-query
OPMERKING

Dit zijn twee verschillende query's die zijn opgeslagen onder verschillende paden.

Ze gebruiken gewoon hetzelfde model, maar via verschillende eindpunten.

Hier zijn de stappen die worden vereist om een bepaalde vraag voort te zetten:

  1. Bereid de vraag door PUTing het aan het nieuwe eindpunt URL voor /graphql/persist.json/<config>/<persisted-label>.

    Maak bijvoorbeeld een doorlopende query:

    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
        -d \
    '{
      articleList {
        items{
            _path
            author
            main {
                json
            }
        }
      }
    }'
    
  2. Controleer nu het antwoord.

    Controleer bijvoorbeeld of het programma is gelukt:

    {
      "action": "create",
      "configurationName": "wknd",
      "name": "plain-article-query",
      "shortPath": "/wknd/plain-article-query",
      "path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
    }
    
  3. U kunt de voortgezette vraag dan opnieuw spelen door URL te KRIJGEN /graphql/execute.json/<shortPath>.

    Gebruik bijvoorbeeld de voortgezette query:

    $ curl -X GET \
        http://localhost:4502/graphql/execute.json/wknd/plain-article-query
    
  4. Werk een voortgezette vraag door POSTing aan een reeds bestaand vraagweg bij.

    Gebruik bijvoorbeeld de voortgezette query:

    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
        -d \
    '{
      articleList {
        items{
            _path
            author
            main {
                json
            }
          referencearticle {
            _path
          }
        }
      }
    }'
    
  5. Een onbewerkte query maken.

    Bijvoorbeeld:

    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-wrapped" \
        -d \
    '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }"}'
    
  6. Creeer een verpakte onbewerkte vraag met geheim voorgeheugencontrole.

    Bijvoorbeeld:

    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
        -d \
    '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'
    
  7. Maak een doorlopende query met parameters:

    Bijvoorbeeld:

    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-parameters" \
        -d \
    'query GetAsGraphqlModelTestByPath($apath: String!, $withReference: Boolean = true) {
      articleByPath(_path: $apath) {
        item {
          _path
            author
            main {
            plaintext
            }
            referencearticle @include(if: $withReference) {
            _path
            }
          }
        }
      }'
    
  8. Een query uitvoeren met parameters.

    Bijvoorbeeld:

    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
    $ curl -X GET \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
  9. Als u de query wilt uitvoeren bij publiceren, moet de verwante boomstructuur worden gerepliceerd

    • Een POST voor replicatie gebruiken:

      $curl -X POST   http://localhost:4502/bin/replicate.json \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -F path=/conf/wknd/settings/graphql/persistentQueries/plain-article-query \
        -F cmd=activate
      
    • Een pakket gebruiken:

      1. Maak een nieuwe pakketdefinitie.
      2. De configuratie opnemen (bijvoorbeeld /conf/wknd/settings/graphql/persistentQueries).
      3. Maak het pakket.
      4. Herhaal het pakket.
    • Het replicatie-/distributiehulpmiddel gebruiken.

      1. Ga naar het gereedschap Distributie.
      2. Selecteer boomactivering voor de configuratie (bijvoorbeeld /conf/wknd/settings/graphql/persistentQueries).
    • Een workflow gebruiken (via workflowstartconfiguratie):

      1. Definieer een workflowstartregel voor het uitvoeren van een workflowmodel dat de configuratie van verschillende gebeurtenissen zou repliceren (bijvoorbeeld, maken, wijzigen, enz.).
  10. Zodra de vraagconfiguratie is op publiceren, zijn de zelfde principes van toepassing, enkel gebruikend het publiceereindpunt.

    OPMERKING

    Voor anonieme toegang veronderstelt het systeem dat ACL "iedereen"toestaat om toegang tot de vraagconfiguratie te hebben.

    Als dat niet het geval is, zal het niet kunnen uitvoeren.

    OPMERKING

    Eventuele puntkomma's (";") in de URL's moeten worden gecodeerd.

    Bijvoorbeeld, zoals in het verzoek om een voortgezette vraag uit te voeren:

    curl -X GET \ "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters%3bapath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    

Het vragen van het eindpunt GraphQL van een Externe Website

Om tot het eindpunt GraphQL van een externe website toegang te hebben moet u vormen:

CORS-filter

OPMERKING

Voor een gedetailleerd overzicht van het beleid voor het delen van bronnen in AEM zie Werken met het delen van bronnen tussen verschillende bronnen (CORS).

Om tot het eindpunt toegang te hebben GraphQL, moet een beleid CORS in de bewaarplaats van de Kit van de klant worden gevormd. Dit wordt gedaan door een aangewezen OSGi CORS configuratiedossier voor het gewenste eindpunt (s) toe te voegen.

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

Bijvoorbeeld, om toegang tot het eindpunt te verlenen GraphQL en voortgeduurde vragen eindpunt voor https://my.domain u kunt 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 ijdelingspad voor het eindpunt hebt gevormd, kunt u het binnen ook gebruiken allowedpaths.

Refererfilter

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

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

  • geeft een hostnaam voor een vertrouwde website aan; ofwel allow.hosts of allow.hosts.regexp,
  • verleent toegang voor deze gastheernaam.

Bijvoorbeeld om toegang voor verzoeken met de Referiteur te verlenen my.domain u kunt:

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

Het blijft de verantwoordelijkheid van de klant om:

  • alleen toegang verlenen tot vertrouwde domeinen
  • ervoor zorgen geen gevoelige informatie wordt blootgesteld
  • geen jokerteken gebruiken [*] syntaxis; dit zal allebei voor authentiek verklaarde toegang tot het eindpunt van GraphQL onbruikbaar maken en zal het aan de volledige wereld ook blootstellen.
LET OP

Alle GraphQL schema's (afgeleid van Content Fragment Models die Ingeschakeld) zijn leesbaar door het eindpunt GraphQL.

Dit betekent dat u ervoor moet zorgen dat er geen gevoelige gegevens beschikbaar zijn, aangezien deze op deze manier kunnen worden gelekt; Dit omvat bijvoorbeeld informatie die als veldnamen in de modeldefinitie aanwezig kan zijn.

Verificatie

Zie Verificatie voor externe AEM GraphQL-query's op inhoudsfragmenten.

Veelgestelde vragen

De gerezen vragen:

  1. Q: "Hoe is GraphQL API voor AEM verschillend van de Bouwer API van de Vraag?"

    • A: "De AEM GraphQL API biedt volledige controle op de JSON-uitvoer en is een industriestandaard voor het opvragen van inhoud.
      Als u verder gaat, is AEM van plan te investeren in de AEM GraphQL API.
      "

Zelfstudie - Aan de slag met AEM headless and GraphQL

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 samenstellen en beschikbaar maken met behulp van AEM GraphQL-API's en die door een externe toepassing wordt verbruikt.

Op deze pagina