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. Mer information finns i versionsinformationen.

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 och CDN) graphql-query-best-practices

Beständiga frågor är den metod som rekommenderas 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 konfigurerat 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.

Mer information finns i Aktivera cachelagring av beständiga frågor.

GraphiQL-gränssnitt graphiql-interface

En implementering av standardgränssnittet GraphiQL finns tillgänglig för användning 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 författarmiljöer och Publish-miljö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 till Assets.

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 Assets) 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. Om du vill slutföra de här riktlinjerna måste en klient hämta Schema, som innehåller alla typer som krävs för en fråga.

För innehållsfragment baseras GraphQL-scheman (struktur och typer) på Enabled Content Fragment Models och deras datatyper.

Om en användare till exempel har skapat en innehållsfragmentmodell med namnet Article, genererar AEM en GraphQL-typ ArticleModel. Fälten i den här typen motsvarar fälten och datatyperna som definieras i modellen. Dessutom skapas några 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. Om du till exempel utför en enkel GET-begäran på /content/cq:graphql/global/endpoint.GQLschema resulterar det 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 detta inträffar genererar AEM ett ofullständigt-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älpfält som hjälper till att identifiera ett innehållsfragment eller att tillhandahålla ytterligare information om ett innehållsfragment.

Dessa hjälpfält är markerade med en _ som föregår 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å innehållsfragmentmodellen 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 specifik struktur, implementerades GraphQL-typen TypedMetaData för att visa metadata för ett innehållsfragment. TypedMetaData visar information grupperad efter följande skalärtyper:

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 - Visa en lista över metadata för utdelade med namnet GB.

Variationer variations

Fältet _variations 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 variation, 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.

Där kan du till exempel inkludera fältet adventurePrice i en fråga för alla AdventureModels, baserat på variabeln 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 jämför till exempel fältets innehåll med värdet some text och fungerar 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 utelämna _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 lastName av Provo eller som innehåller sjö, oberoende av fallet:

{
  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, och ett specifikt värde inte har angetts för den valfria variabeln, ignoreras variabeln i filterutvärderingen. Det innebär att frågeresultaten innehåller alla värden, både 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 också sortera på 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 kan du använda offset och limit för att 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 i resultatlistan complete :

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

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

Frågetypen ...Paginated återanvänder de flesta av ...List-frågetypsfunktionerna (filtrering, sortering), men i stället för att använda offset/limit-argument använder den first/after-argumenten som definierats av GraphQL Cursor Connections Specification. En mindre formell introduktion finns i GraphQL-introduktionen.

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

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

GraphQL Persisted 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 konfigurationsfiler:

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 den betrodda webbplatsens ursprung alloworigin eller alloworiginregexp som åtkomst måste beviljas för.

Om du till exempel vill ge åtkomst till slutpunkten och den beständiga frågeslutpunkten för GraphQL för https://my.domain kan du 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 huvudsö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 bevilja åtkomst för begäranden med referenten my.domain kan du:

{
    "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 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? Ta en titt på Komma igång med AEM Headless och GraphQL - en komplett självstudiekurs som visar hur du 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.