AEM GraphQL API för användning med innehållsfragment graphql-api-for-use-with-content-fragments

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

AEM GraphQL API som används med innehållsfragment är till stor del baserat på GraphQL-API:t 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:

Förutsättningar prerequisites

Kunder som använder GraphQL bör installera AEM Content Fragment med GraphQL Index Package 1.0.5. Se Versionsinformation för mer information.

GRAPHQL API graphql-api

GraphQL är:

Mer information om GraphQL API finns i följande avsnitt (bland annat):

Implementeringen av GraphQL för AEM baseras på GraphQL Java™-standardbibliotek. Se:

GraphQL Terminologi graphql-terminology

GraphQL använder följande:

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

GraphQL Query Types graphql-query-types

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

AEM innehåller funktioner för att konvertera frågor (båda typerna) till Beständiga frågor som cachas av Dispatcher och CDN.

GraphQL Query Best Practices (Dispatcher and CDN) graphql-query-best-practices

Beständiga frågor är den rekommenderade metod som ska användas för publiceringsinstanser som:

GraphQL-frågor som använder förfrågningar om POST rekommenderas inte eftersom de inte cachelagras, så i en standardinstans är Dispatcher konfigurerad att blockera sådana frågor.

Även om GraphQL har stöd för GET-förfrågningar kan dessa förfrågningar få en träffgräns (till exempel längden på URL:en) som kan undvikas med beständiga frågor.

Se Aktivera cachelagring av beständiga frågor för mer information.

GraphiQL-gränssnitt graphiql-interface

En implementering av standarden GraphiQL -gränssnittet kan användas med AEM GraphQL.

Med det här gränssnittet kan du direkt mata in och testa frågor.

Till exempel:

Den innehåller funktioner som syntaxmarkering, automatisk komplettering, autoföreslå, samt historik och onlinedokumentation:

Användningsexempel för skribent- och publiceringsmiljöer use-cases-author-publish-environments

Användningsexemplen kan bero på vilken typ av AEM som används:

Behörigheter permission

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

GraphQL-frågor körs med tillstånd från den AEM användaren av den underliggande begäran. Om användaren inte har läsåtkomst till vissa fragment (som lagras som resurser) blir de inte en del av resultatuppsättningen.

Användaren måste också ha tillgång till en GraphQL-slutpunkt för att kunna köra GraphQL-frågor.

Schemagenerering schema-generation

GraphQL är ett 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. Kunden måste 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.

Om en användare till exempel har skapat en innehållsfragmentmodell som kallas ArticleAEM sedan generera en GraphQL-typ ArticleModel. Fälten i den här typen motsvarar fälten och datatyperna som definieras i modellen. Dessutom skapas vissa startpunkter för frågor som arbetar med den här typen, till exempel articleByPath eller articleList.

I GraphQL for AEM är schemat flexibelt. Denna flexibilitet 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 avlyssnar (i bakgrunden) alla ändringar som görs 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:

Schemat hanteras via samma slutpunkt som GraphQL-frågorna, där klienthanteraren hanterar det faktum 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 schema-generation-unpublished-models

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

När det 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 fields

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

Datatyper data-types

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

Hjälpfält helper-fields

Förutom datatyperna för användargenererade fält genererar GraphQL för AEM även flera hjälpare fält som hjälper dig att identifiera ett innehållsfragment eller att ge mer information om ett innehållsfragment.

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.

Bana path

Sökvägsfältet används som en identifierare i AEM GraphQL. Den representerar sökvägen till Content Fragment-resursen i AEM. Den här sökvägen väljs som identifierare för ett innehållsfragment eftersom den:

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:

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

Se Exempelfråga - Ett enskilt specifikt stadsfragment.

Metadata metadata

Via GraphQL visar AEM också metadata för ett innehållsfragment. Metadata är den information som beskriver ett innehållsfragment, till exempel följande:

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

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 är den här egenskapen en String-egenskap, så du vill fråga 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.

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

Variationer variations

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.

GraphQL Variables graphql-variables

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.

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

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

GraphQL Direktiv graphql-directives

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

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

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

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

Filtrering filtering

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

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

Den mest atomiska delen är ett enstaka uttryck som kan tillämpas på innehållet i ett visst fält. Innehållet i fältet jämförs med ett givet konstantvärde.

Följande uttryck skulle till exempel jämföra innehållet i fältet med värdet some textoch lyckas om innehållet är lika med värdet. Annars misslyckas uttrycket:

{
  value: "some text"
  _op: EQUALS
}

Följande operatorer kan användas för att jämföra fält med ett visst värde:

I vissa typer kan du även ange ytterligare alternativ som ändrar hur ett uttryck utvärderas:

Uttryck kan kombineras till en uppsättning med hjälp av en logisk operator (_logOp):

Varje fält kan filtreras med en egen uppsättning uttryck. Uttrycksuppsättningarna för alla fält som omnämns i filterargumentet kombineras till slut av den egna logiska operatorn.

En filterdefinition (skickas som filter argument till en fråga) innehåller:

Du kan utesluta _logOp om du vill kombinera objekt med AND och _operator om du vill kontrollera om de är lika, eftersom dessa värden är standardvärden.

I följande exempel visas en fullständig fråga som filtrerar alla personer som har en lastName av Provo eller innehåller sjö, oberoende av omständigheterna:

{
  authorList(filter: {
    lastname: {
      _logOp: OR
      _expressions: [
        {
          value: "sjö",
          _operator: CONTAINS,
          _ignoreCase: true
        },
        {
          value: "Provo"
        }
      ]
    }
  }) {
    items {
      lastName
      firstName
    }
  }
}

När en GraphQL-fråga körs med valfria variabler, om ett specifikt värde är not som anges för den valfria variabeln ignoreras variabeln i filterutvärderingen. Det innebär att frågeresultaten innehåller alla värden, båda null och inte null, för egenskapen som är relaterad till filtervariabeln.

I frågan nedan, där inget värde har angetts för egenskapen lastName:

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

Alla författare returneras:

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

Du kan även filtrera efter kapslade fält, men det rekommenderas inte eftersom det kan leda till prestandaproblem.

Ytterligare exempel finns i:

Sortering sorting

Med den här funktionen kan du sortera frågeresultaten enligt ett angivet fält.

Sorteringskriterierna:

Till exempel:

query {
  authorList(sort: "lastName, firstName") {
    items {
      firstName
      lastName
    }
  }
}

Och dessutom:

{
  authorList(sort: "lastName DESC, firstName DESC") {
    items {
        lastName
        firstName
    }
  }
}

Du kan även sortera ett fält i ett kapslat fragment med formatet nestedFragmentname.fieldname.

Till exempel:

query {
  articleList(sort: "authorFragment.lastName")  {
    items {
      title
      authorFragment {
        firstName
        lastName
        birthDay
      }
      slug
    }
  }
}

Sidindelning paging

Med den här funktionen kan du utföra sidindelning på frågetyper som returnerar en lista. Det finns två metoder:

Listfråga - förskjutning och begränsning list-offset-limit

I en ...Listfråga som du kan använda offset och limit om du vill returnera en viss delmängd av resultaten:

Om du till exempel vill visa en resultatsida som innehåller upp till fem artiklar, med början från den femte artikeln från complete resultatlista:

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}

Sidnumrerad fråga - första och efter paginated-first-after

The ...Paginated frågetypen återanvänder de flesta ...List frågetypsfunktioner (filtrering, sortering), men i stället för att använda offset/limit argument, använder first/after argument som definieras av GraphQL Cursor Connections Specification. Du hittar en mindre formell introduktion i GraphQL introduktion.

Du kan till exempel skriva ut en resultatsida som innehåller upp till fem äventyr, med början från markörobjektet i complete resultatlista:

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}

GraphQL Persistent Queries - aktivera cachelagring i Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

Cachelagring av beständiga frågor är inte aktiverat som standard i Dispatcher. Standardaktivering är inte möjlig eftersom kunder som använder CORS (Cross-Origin Resource Sharing) med flera ursprung måste granska och eventuellt uppdatera sin Dispatcher-konfiguration.

Aktivera cachelagring av beständiga frågor enable-caching-persisted-queries

För att aktivera cachelagring av beständiga frågor krävs följande uppdateringar av Dispatcher-konfigurationsfilerna:

CORS-konfiguration i Dispatcher cors-configuration-in-dispatcher

Kunder som använder CORS-begäranden kan behöva granska och uppdatera sin CORS-konfiguration i Dispatcher.

GraphQL for AEM - i korthet graphql-extensions

Den grundläggande funktionen för frågor med GraphQL för AEM följer GraphQL standardspecifikation. Det finns några tillägg för GraphQL-frågor med AEM:

CORS-filter cors-filter

Konfigurera en CORS-princip i kundens Git-databas för att få åtkomst till GraphQL-slutpunkten. Den här konfigurationen görs genom att en lämplig OSGi CORS-konfigurationsfil läggs till för en eller flera önskade slutpunkter.

Den här konfigurationen måste ange en betrodd webbplatsens ursprung alloworigin eller alloworiginregexp för vilka tillträde måste beviljas.

Om du till exempel vill ge åtkomst till GraphQL slutpunkt och beständiga frågeslutpunkter för https://my.domain du kan använda:

{
  "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/.*"
  ]
}

Om du har konfigurerat en hjälpsökväg för slutpunkten kan du även använda den i allowedpaths.

Referensfilter referrer-filter

Förutom CORS-konfigurationen måste ett referensfilter konfigureras så att åtkomst från tredjepartsvärdar tillåts.

Det här filtret görs genom att en lämplig konfigurationsfil för OSGi-referensfiltret läggs till:

Om du till exempel vill ge åtkomst för begäranden med referenten my.domain du kan:

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

Begränsningar limitations

För att skydda dig mot potentiella problem finns det standardbegränsningar för dina frågor:

Du måste också vara medveten om:

Autentisering authentication

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

Vanliga frågor faqs

Frågor som har uppstått:

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

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