AEM GraphQL API för användning med innehållsfragment

Lär dig hur du använder innehållsfragment i Adobe Experience Manager (AEM) as a Cloud Service med AEM GraphQL API för leverans av headless-innehåll.

AEM as a Cloud Service GraphQL API som används med innehållsfragment är till stor del baserat på standard-API:t GraphQL med öppen källkod.

Genom att använda GraphQL API i AEM kan du effektivt leverera innehållsfragment till JavaScript-klienter i headless CMS-implementeringar:

  • Undvika iterativa API-begäranden som REST,
  • se till att leveransen begränsas till de specifika kraven,
  • Det går att skicka exakt det som behövs för återgivningen som svar på en enda API-fråga.
OBSERVERA

GraphQL används för närvarande i två (separata) scenarier i Adobe Experience Manager (AEM) as a Cloud Service:

GraphQL API

GraphQL är:

  • "…ett frågespråk för API:er och en körningsmiljö för att utföra dessa frågor med dina befintliga data. GraphQL ger en fullständig och begriplig beskrivning av data i API:t, ger kunderna möjlighet att fråga efter exakt vad de behöver och inget mer, gör det enklare att utveckla API:er över tid och möjliggör kraftfulla utvecklingsverktyg.".

    Se GraphQL.org

  • "…en öppen specifikation för ett flexibelt API-lager. Flytta GraphQL över dina befintliga bakgrunder för att skapa produkter snabbare än någonsin…".

    Se Utforska GraphQL.

  • "…ett datameddelande och en specifikation som utvecklats internt av Facebook 2012 innan de blev offentligt tillgängliga 2015. Det är ett alternativ till REST-baserade arkitekturer i syfte att öka utvecklarnas produktivitet och minimera mängden data som överförs. GraphQL används i produktion av hundratals organisationer av alla storlekar…"

    Se GraphQL Foundation.

Mer information om GraphQL API finns i följande avsnitt (bland många andra resurser):

GraphQL för AEM är baserad på standardbiblioteket GraphQL Java Library. Se:

GraphQL Terminologi

GraphQL använder följande:

  • Frågor

  • Scheman och typer:

    • Scheman genereras av AEM baserat på modeller för innehållsfragment.
    • GraphQL visar de typer och åtgärder som tillåts för GraphQL för AEM implementering med dina scheman.
  • Fält

  • GraphQL-slutpunkt

    • Den sökväg i AEM som svarar på GraphQL-frågor och ger åtkomst till GraphQL-scheman.

    • Se Aktivera GraphQL-slutpunkten för mer information.

Se (GraphQL.org) Introduktion till GraphQL för utförlig information, inklusive Bästa praxis.

GraphQL-frågetyper

Med GraphQL kan du utföra frågor för att returnera:

Du kan också utföra:

GraphQL Query Best Practices (Dispatcher)

The Beständiga frågor är den rekommenderade metoden som:

  • de cachelagras
  • de hanteras centralt av AEM as a Cloud Service

Frågorna direct, och/eller POST, rekommenderas inte eftersom de inte cachas, så i en standardinstans är Dispatcher konfigurerad att blockera sådana frågor.

OBSERVERA

Om du vill tillåta direkta och/eller POST frågor i Dispatcher kan du be systemadministratören att:

  • Skapa en Cloud Manager-miljövariabel med namnet ENABLE_GRAPHQL_ENDPOINT
  • med värdet true
OBSERVERA

Möjligheten att utföra direkta frågor kan vara föråldrad vid något tillfälle i framtiden.

GraphiQL IDE

Du kan testa och felsöka GraphQL-frågor med GraphiQL IDE.

Användningsexempel för skribent- och publiceringsmiljöer

Användningsexemplen kan bero på vilken typ av AEM as a Cloud Service miljö det är:

  • Publiceringsmiljö. används för att:

    • Frågedata för JS-program (standardfall)
  • Författarmiljö; används för att:

    • Fråga efter data för"innehållshanteringssyften":
      • GraphQL i AEM as a Cloud Service är för närvarande ett skrivskyddat API.
      • REST API kan användas för CR(u)D-åtgärder.

Behörigheter

Behörigheterna är de som krävs för åtkomst av resurser.

Schemagenerering

GraphQL är ett starkt typbestämt API, vilket innebär att data måste vara tydligt strukturerade och ordnade efter typ.

GraphQL-specifikationen innehåller en serie riktlinjer för hur du skapar ett robust API för att förhöra data i en viss instans. För att göra detta måste en kund hämta Schema, som innehåller alla typer som behövs för en fråga.

För innehållsfragment baseras GraphQL-scheman (struktur och typer) på Aktiverad Modeller för innehållsfragment och deras datatyper.

FÖRSIKTIGHET

Alla GraphQL-scheman (härledda från Content Fragment Models som har Aktiverad) går att läsa via GraphQL-slutpunkten.

Detta innebär att ni måste se till att inga känsliga uppgifter finns tillgängliga, eftersom de skulle kunna läckas på detta sätt. Detta inkluderar till exempel information som kan finnas som fältnamn i modelldefinitionen.

Om en användare till exempel har skapat en innehållsfragmentmodell som kallas ArticleAEM genererar objektet article som är av en typ ArticleModel. Fälten i den här typen motsvarar fälten och datatyperna som definieras i modellen.

  1. En innehållsfragmentmodell:

    Content Fragment Model for use with GraphQL
  2. Motsvarande GraphQL-schema (utdata från automatisk GraphiQL-dokumentation):
    GraphQL-schema baserat på innehållsfragmentmodell

    Detta visar att den genererade typen ArticleModel innehåller flera fält.

    • Tre av dem har kontrollerats av användaren: author, main och referencearticle.

    • De andra fälten lades till automatiskt av AEM och representerar användbara metoder för att tillhandahålla information om ett visst innehållsfragment. i det här exemplet _path, _metadata, _variations. Dessa hjälpfält markeras med föregående _ för att skilja mellan vad som har definierats av användaren och vad som har genererats automatiskt.

  3. När en användare har skapat ett innehållsfragment baserat på artikelmodellen kan det sedan förfrågas via GraphQL. Mer information finns i Exempelfrågor (baserat på sampla innehållsfragmentstruktur för användning med GraphQL).

Schemat är flexibelt i GraphQL för AEM. Det innebär att den genereras automatiskt varje gång en innehållsfragmentmodell skapas, uppdateras eller tas bort. Cacheminnen för dataschemat uppdateras också när du uppdaterar en innehållsfragmentmodell.

Tjänsten Sites GraphQL lyssnar (i bakgrunden) efter ändringar som gjorts i en innehållsfragmentmodell. När uppdateringar upptäcks återskapas endast den delen av schemat. Denna optimering sparar tid och ger stabilitet.

Om du till exempel:

  1. Installera ett paket som innehåller Content-Fragment-Model-1 och Content-Fragment-Model-2:

    1. GraphQL-typer för Model-1 och Model-2 kommer att genereras.
  2. Ändra sedan Content-Fragment-Model-2:

    1. Endast Model-2 GraphQL-typen uppdateras.

    2. med beaktande av följande: Model-1 kommer att förbli desamma.

OBSERVERA

Detta är viktigt att observera om du vill göra satsvisa uppdateringar på modeller för innehållsfragment via REST-API:t, eller på annat sätt.

Schemat hanteras via samma slutpunkt som GraphQL-frågorna, där klienthanteraren anger att schemat anropas med tillägget GQLschema. Du kan till exempel utföra en enkel GET begäran på /content/cq:graphql/global/endpoint.GQLschema resulterar i utdata från schemat med innehållstypen: text/x-graphql-schema;charset=iso-8859-1.

Schemagenerering - opublicerade modeller

När innehållsfragment är kapslade kan det hända att en överordnad Content Fragment Model publiceras, men ingen refererad modell gör det.

OBSERVERA

Gränssnittet AEM förhindrar detta, men om publiceringen görs programmatiskt eller med innehållspaket kan det ske.

När detta inträffar genererar AEM en ofullständig Schema för den överordnade innehållsfragmentmodellen. Det innebär att fragmentreferensen, som är beroende av den opublicerade modellen, tas bort från schemat.

fält

Inom schemat finns det enskilda fält av två baskategorier:

  • Fält som du genererar.

    Ett urval av Fälttyper används för att skapa fält baserat på hur du konfigurerar innehållsfragmentmodellen. Fältnamnen hämtas från Egenskapsnamn fält för Datatyp.

    • Det finns också Återge som Egenskaper som ska beaktas, eftersom användare kan konfigurera vissa datatyper. t.ex. som en enda rad eller som ett multifält.
  • GraphQL för AEM genererar även ett antal hjälpfält.

    Dessa används för att identifiera ett innehållsfragment eller för att få mer information om ett innehållsfragment.

Fälttyper

GraphQL för AEM stöder en lista med typer. Alla Content Fragment Model-datatyper som stöds och motsvarande GraphQL-typer visas:

Content Fragment Model - datatyp GraphQL-typ Beskrivning
Enkelradig text String, [Sträng] Används för enkla strängar som författarnamn, platsnamn osv.
Flerradstext Sträng Används för att skriva ut text, t.ex. brödtexten i en artikel
Siffra Float, [Float] Används för att visa flyttal och reguljära tal
Boolesk Boolesk Används för att visa kryssrutor → enkla sant/falskt-satser
Datum och tid Kalender Används för att visa datum och tid i ett ISO 8086-format. Beroende på vilken typ som valts finns det tre olika varianter att använda i AEM GraphQL: onlyDate, onlyTime, dateTime
Uppräkning Sträng Används för att visa ett alternativ från en lista med alternativ som definieras när modellen skapas
Taggar [Sträng] Används för att visa en lista över strängar som representerar taggar som används i AEM
Innehållsreferens Sträng Används för att visa sökvägen till en annan resurs i AEM
Fragmentreferens En modelltyp Används för att referera till ett annat innehållsfragment av en viss modelltyp, som definieras när modellen skapades

Hjälpfält

Förutom datatyperna för användargenererade fält genererar GraphQL för AEM även ett antal hjälpare fält för att hjälpa till att identifiera ett innehållsfragment eller för att ge ytterligare information om ett innehållsfragment.

Bana

Sökvägsfältet används som en identifierare i GraphQL. Den representerar sökvägen till Content Fragment-resursen i AEM. Vi har valt detta som identifierare för ett innehållsfragment eftersom det:

  • är unikt inom AEM,
  • kan enkelt hämtas.

I följande kod visas sökvägarna för alla innehållsfragment som har skapats baserat på modellen för innehållsfragment Person.

{
  personList {
    items {
      _path
    }
  }
}

Om du vill hämta ett enstaka innehållsfragment av en viss typ måste du också bestämma sökvägen först. till exempel:

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

Se Exempelfråga - Ett enskilt specifikt stadsfragment.

Metadata

Via GraphQL visar AEM även metadata för ett innehållsfragment. Metadata är den information som beskriver ett innehållsfragment, till exempel titeln på ett innehållsfragment, miniatyrsökvägen, beskrivningen av ett innehållsfragment och datumet då det skapades, bland annat.

Eftersom metadata genereras via Schemaredigeraren och därför inte har någon särskild struktur, har TypedMetaData GraphQL-typen implementerades för att visa metadata för ett innehållsfragment. TypedMetaData visar informationen som grupperats med följande skalära typer:

Fält
stringMetadata:[StringMetadata]!
stringArrayMetadata:[StringArrayMetadata]!
intMetadata:[IntMetadata]!
intArrayMetadata:[IntArrayMetadata]!
floatMetadata:[FloatMetadata]!
floatArrayMetadata:[FloatArrayMetadata]!
booleanMetadata:[BooleanMetadata]!
booleanArrayMetadata:[booleanArrayMetadata]!
calendarMetadata:[CalendarMetadata]!
calendarArrayMetadata:[CalendarArrayMetadata]!

Varje skalär typ representerar antingen ett namn/värde-par eller en array med namn/värde-par, där värdet för det paret är av den typ som det grupperades i.

Om du till exempel vill hämta titeln för ett innehållsfragment vet vi att den här egenskapen är en String-egenskap, så vi frågar efter alla strängmetadata:

Så här frågar du efter metadata:

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

Du kan visa alla metadata för GraphQL-typer om du visar det genererade GraphQL-schemat. Alla modelltyper har samma TypedMetaData.

OBSERVERA

Skillnad mellan normala metadata och arraymetadata
Kom ihåg att StringMetadata och StringArrayMetadata båda hänvisar till vad som lagras i databasen, inte till hur du hämtar dem.

Genom att anropa stringMetadata får du en array med alla metadata som lagras i databasen som String och om du ringer stringArrayMetadata får du en array med alla metadata som lagras i databasen som String[].

Se Exempelfråga för metadata - Ange metadata för utmärkelserna med namnet GB.

Variationer

The _variations -fältet har implementerats för att förenkla frågor om variationer som ett innehållsfragment har. Till exempel:

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

Se Exempelfråga - Alla städer med en namngiven variant.

OBSERVERA

Om den angivna varianten inte finns för ett innehållsfragment returneras den överordnad varianten som ett (fallback) standardvärde.

GraphQL-variabler

GraphQL tillåter att variabler placeras i frågan. Mer information finns i GraphQL-dokumentation för variabler.

Om du till exempel vill hämta alla innehållsfragment av typen Article som har en viss variant kan du ange variabeln variation i GraphiQL.

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

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

GraphQL-direktiv

I GraphQL finns det en möjlighet att ändra frågan baserat på variabler, så kallade GraphQL-direktiv.

Du kan till exempel inkludera adventurePrice fält i en fråga för alla AdventureModels, baserat på en variabel includePrice.

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

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

Filtrering

Du kan också använda filtrering i GraphQL-frågor för att returnera specifika data.

Vid filtrering används en syntax som baseras på logiska operatorer och uttryck.

Följande (grundläggande) fråga filtrerar till exempel alla personer som har namnet Jobs eller Smith:

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

Ytterligare exempel finns i:

GraphQL för AEM - Sammanfattning av tillägg

Den grundläggande åtgärden för frågor med GraphQL för AEM följer standarden GraphQL-specifikation. För GraphQL-frågor med AEM finns det några tillägg:

Fråga GraphQL-slutpunkten från en extern webbplats

Om du vill komma åt GraphQL-slutpunkten från en extern webbplats måste du konfigurera:

Autentisering

Se Autentisering för AEM GraphQL-frågor om innehållsfragment.

Vanliga frågor

Frågor som har uppstått:

  1. Q: "Hur skiljer sig GraphQL API för AEM från Query Builder API?"

    • A: "AEM GraphQL API ger total kontroll över JSON-utdata och är en branschstandard för att fråga efter innehåll.
      AEM planerar att investera i det AEM GraphQL-API:t.
      "

Självstudiekurs - Komma igång med AEM Headless och GraphQL

Söker du en praktisk självstudiekurs? Checka ut Komma igång med AEM Headless och GraphQL en komplett självstudiekurs som visar hur du bygger upp och exponerar innehåll med AEM GraphQL API:er och som används av en extern app i ett headless CMS-scenario.

På denna sida