API de GraphQL de AEM para su uso con fragmentos de contenido graphql-api-for-use-with-content-fragments

Aprenda a utilizar los fragmentos de contenido en Adobe Experience Manager AEM AEM () con la API de GraphQL de la para la entrega de contenido sin encabezado.

AEM La API de GraphQL utilizada con fragmentos de contenido se basa principalmente en la API de GraphQL estándar de código abierto.

El uso de la API de GraphQL en AEM permite la entrega eficiente de fragmentos de contenido a clientes JavaScript en implementaciones de CMS sin encabezado:

Requisitos previos prerequisites

Los clientes que utilizan GraphQL AEM deben instalar el fragmento de contenido de la aplicación con el paquete de índice 1.0.5 de GraphQL. Consulte las Notas de la versión para obtener más información.

La API de GraphQL graphql-api

GraphQL es:

Para obtener más información sobre la API de GraphQL, consulte las siguientes secciones (entre muchos otros recursos):

La implementación de GraphQL AEM para la ™ se basa en la biblioteca Java estándar de GraphQL. Consulte:

Terminología de GraphQL graphql-terminology

GraphQL utiliza lo siguiente:

Consulte la Introducción a GraphQL (GraphQL.org) para obtener información detallada, incluidas las Prácticas recomendadas.

Tipos de consulta de GraphQL graphql-query-types

Con GraphQL puede realizar consultas para devolver lo siguiente:

AEM proporciona capacidades para convertir consultas (ambos tipos) a Consultas persistentes que Dispatcher y CDN almacenan en caché.

Prácticas recomendadas para consultas de GraphQL (Dispatcher y CDN) graphql-query-best-practices

Las consultas persistentes son el método recomendado para usar en instancias de publicación como:

No se recomiendan las consultas GraphQL que utilizan peticiones POST, ya que no se almacenan en caché, por lo que en una instancia predeterminada, Dispatcher está configurado para bloquear dichas consultas.

Aunque GraphQL también admite solicitudes de GET, estas solicitudes pueden alcanzar límites (por ejemplo, la longitud de la dirección URL) que se pueden evitar utilizando consultas persistentes.

Consulte Habilitar el almacenamiento en caché de consultas persistentes para obtener más información.

Interfaz de GraphiQL graphiql-interface

AEM Hay una implementación de la interfaz estándar de GraphiQL disponible para su uso con el GraphQL de la.

Esta interfaz le permite introducir y probar consultas directamente.

Por ejemplo:

Proporciona funciones como resaltado de sintaxis, autocompletado o autosugerencia, junto con un historial y documentación en línea:

Casos de uso para entornos de creación y publicación use-cases-author-publish-environments

AEM Los casos de uso pueden depender del tipo de entorno de:

Permisos permission

Los permisos son necesarios para acceder a Assets.

Las consultas de GraphQL AEM se ejecutan con el permiso del usuario de la solicitud subyacente que se ha creado en la página de la aplicación. Si el usuario no tiene acceso de lectura a algunos fragmentos (almacenados como Assets), no forman parte del conjunto de resultados.

Además, el usuario debe tener acceso a un extremo de GraphQL para poder ejecutar consultas de GraphQL.

Generación de esquemas schema-generation

GraphQL es una API con tipo, lo que significa que los datos deben estar claramente estructurados y organizados por tipo.

La especificación de GraphQL proporciona una serie de directrices sobre cómo crear una API robusta para buscar datos en una instancia determinada. Para completar estas instrucciones, un cliente debe obtener el Esquema, que contiene todos los tipos necesarios para una consulta.

Para los fragmentos de contenido, los esquemas (estructura y tipos) de GraphQL se basan en Modelos de fragmentos de contenido habilitados y sus tipos de datos.

Por ejemplo, si un usuario crea un modelo de fragmento de contenido denominado Article, luego AEM genera un tipo de GraphQL ArticleModel. Los campos dentro de este tipo corresponden a los campos y tipos de datos definidos en el modelo. Además, crea algunos puntos de entrada para las consultas que funcionan en este tipo, como articleByPath o articleList.

En GraphQL para AEM, el esquema es flexible. Esta flexibilidad significa que se genera automáticamente cada vez que se crea, actualiza o elimina un modelo de fragmento de contenido. Las cachés del esquema de datos también se refrescan al actualizar el modelo de fragmento de contenido.

El servicio Sites de GraphQL escucha (en segundo plano) cualquier modificación realizada en un modelo de fragmento de contenido. Cuando se detectan actualizaciones, solo se regenera esa parte del esquema. Esta optimización ahorra tiempo y proporciona estabilidad.

Por ejemplo, si:

El esquema se sirve a través del mismo punto de conexión que las consultas de GraphQL, y el cliente gestiona el hecho de que se llama al esquema con la extensión GQLschema. Por ejemplo, realizar una solicitud GET simple en /content/cq:graphql/global/endpoint.GQLschema da como resultado la salida del esquema con el tipo de contenido: text/x-graphql-schema;charset=iso-8859-1.

Generación de esquemas: modelos no publicados schema-generation-unpublished-models

Cuando los fragmentos de contenido están anidados, puede ocurrir que se publique un modelo de fragmento de contenido principal, pero no un modelo al que se hace referencia.

AEM Cuando esto sucede, el usuario genera un esquema incompleto para el modelo de fragmento de contenido principal, el cual se generará de manera predeterminada Significa que la referencia de fragmento, que depende del modelo no publicado, se elimina del esquema.

Campos fields

Dentro del esquema, hay campos individuales, de dos categorías básicas:

Tipos de datos data-types

GraphQL para AEM admite una lista de tipos. Se representan todos los tipos de datos del modelo de fragmento de contenido compatibles y los tipos de GraphQL correspondientes:

Campos de ayuda helper-fields

Además de los tipos de datos de los campos generados por el usuario, GraphQL AEM para la distribución de contenido también genera varios campos Helper para ayudar a identificar un fragmento de contenido o para proporcionar información adicional acerca de un fragmento de contenido.

Estos campos de ayuda se marcan con un _ que los precede para distinguir entre lo que ha definido el usuario y lo que se ha generado automáticamente.

Ruta path

El campo de ruta se utiliza como identificador en AEM GraphQL. Representa la ruta del recurso de fragmento de contenido dentro del repositorio de AEM. Esta ruta se elige como identificador de un fragmento de contenido, porque:

El siguiente código muestra las rutas de acceso de todos los fragmentos de contenido creados basándose en el modelo de fragmento de contenido Person.

{
  personList {
    items {
      _path
    }
  }
}

Para recuperar un solo fragmento de contenido de un tipo específico, también debe determinar primero su ruta. Por ejemplo:

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

Consulte Consulta de muestra: un solo fragmento de ciudad específico.

Metadatos metadata

A través de GraphQL, AEM también expone los metadatos de un fragmento de contenido. Los metadatos son la información que describe un fragmento de contenido, como, por ejemplo, lo siguiente:

Dado que los metadatos se generan mediante el Editor de esquemas y, como tales, no tienen una estructura específica, el tipo de GraphQL TypedMetaData se ha implementado para exponer los metadatos de un fragmento de contenido. TypedMetaData expone la información agrupada por los siguientes tipos escalares:

Cada tipo escalar representa un único par nombre-valor o una matriz de pares nombre-valor, donde el valor de ese par es del tipo en el que se agrupó.

Por ejemplo, si desea recuperar el título de un fragmento de contenido, esta propiedad es de cadena, por lo que consultaría todos los metadatos de cadena:

Para consultar metadatos:

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

Puede ver todos los tipos de metadatos de GraphQL si ve el esquema de GraphQL generado. Todos los tipos de modelo tienen el mismo TypedMetaData.

Consulte Consulta de muestra para metadatos: enumera los metadatos de los premios titulados GB.

Variaciones variations

El campo _variations se ha implementado para simplificar la consulta de las variaciones que tiene un fragmento de contenido. Por ejemplo:

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

Consulte Consulta de muestra: todas las ciudades con una variación con nombre.

Variables de GraphQL graphql-variables

GraphQL permite colocar variables en la consulta. Para obtener más información, consulte Documentación de GraphQL para variables.

Por ejemplo, para obtener todos los fragmentos de contenido del tipo Article que tienen una variación específica, puede especificar la variable variation en GraphiQL.

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

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

Directivas de GraphQL graphql-directives

En GraphQL, existe la posibilidad de cambiar la consulta en función de variables, denominadas Directivas de GraphQL.

Por ejemplo, puede incluir el campo adventurePrice en una consulta para todos los AdventureModels, en función de una variable includePrice.

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

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

Filtrado filtering

También puede utilizar el filtrado en las consultas de GraphQL para devolver datos específicos.

El filtrado utiliza una sintaxis basada en operadores lógicos y expresiones.

La parte más atómica es una sola expresión que se puede aplicar al contenido de un campo determinado. Compara el contenido del campo con un valor constante determinado.

Por ejemplo, la siguiente expresión compararía el contenido del campo con el valor some text, y tendría éxito si el contenido es igual al valor. De lo contrario, la expresión falla.:

{
  value: "some text"
  _op: EQUALS
}

Los siguientes operadores pueden utilizarse para comparar campos con un determinado valor:

Algunos tipos también permiten especificar opciones adicionales que modifican cómo se evalúa una expresión:

Las expresiones se pueden combinar en un conjunto con la ayuda de un operador lógico (_logOp):

Cada campo se puede filtrar por su propio conjunto de expresiones. Los conjuntos de expresiones de todos los campos mencionados en el argumento de filtro se combinan finalmente con su propio operador lógico.

Una definición de filtro (que se transfiere como el argumento filter a una consulta) contiene lo siguiente:

Puede omitir _logOp si desea combinar elementos con AND y _operator si desea comprobar la igualdad, ya que estos valores son predeterminados.

El siguiente ejemplo muestra una consulta completa que filtra todas las personas que tienen un lastName de Provo o con sjö, independientemente del caso:

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

Cuando se ejecuta una consulta de GraphQL usando variables opcionales, si se proporciona un valor específico no para la variable opcional, entonces la variable se omitirá en la evaluación del filtro. Esto significa que los resultados de la consulta contendrán todos los valores, tanto null como no null, de la propiedad relacionada con la variable de filtro.

Por ejemplo, en la consulta siguiente, donde no se especifica ningún valor para la propiedad lastName:

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

Se devolverán todos los autores:

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

Aunque también puede filtrar por campos anidados, no se recomienda, ya que puede provocar problemas de rendimiento.

Para ver más ejemplos, consulte lo siguiente:

Ordenación sorting

Esta función permite ordenar los resultados de la consulta según un campo especificado.

Los criterios de clasificación son los siguientes:

Por ejemplo:

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

Y también:

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

También puede ordenar un campo dentro de un fragmento anidado, utilizando el formato de nestedFragmentname.fieldname.

Por ejemplo:

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

Paginación paging

Esta función permite realizar paginación en los tipos de consulta que devuelven una lista. Se proporcionan dos métodos:

Consulta de lista: desplazamiento y límite list-offset-limit

En una consulta ...List puede utilizar offset y limit para devolver un subconjunto específico de resultados:

Por ejemplo, para generar la página de resultados que contiene hasta cinco artículos, a partir del quinto artículo de la lista de resultados completa:

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

Consulta paginada: primero y después paginated-first-after

El tipo de consulta ...Paginated reutiliza la mayoría de las funciones de tipo de consulta ...List (filtrado, clasificación), pero en lugar de usar argumentos offset/limit, emplea los argumentos first/after definidos por la especificación de las conexiones del cursor de GraphQL. Puede encontrar una introducción menos formal en la Introducción a GraphQL.

Por ejemplo, mostrar la página de resultados que contiene hasta cinco aventuras, empezando por el elemento de cursor dado en la lista de resultados completa:

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

Consultas persistentes de GraphQL: habilitar el almacenamiento en caché en Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

El almacenamiento en caché de consultas persistentes no está habilitado de forma predeterminada en Dispatcher. La activación predeterminada no es posible, ya que los clientes que utilizan CORS (Intercambio de recursos de origen cruzado) con varios orígenes deben revisar, y posiblemente actualizar, su configuración de Dispatcher.

Habilitar el almacenamiento en caché de consultas persistentes enable-caching-persisted-queries

Para habilitar el almacenamiento en caché de consultas persistentes, se requieren las siguientes actualizaciones de los archivos de configuración de Dispatcher:

Configuración de CORS en Dispatcher cors-configuration-in-dispatcher

Es posible que los clientes que utilizan solicitudes CORS tengan que revisar y actualizar su configuración CORS en Dispatcher.

GraphQL para AEM: resumen de extensiones graphql-extensions

El funcionamiento básico de las consultas con GraphQL para AEM se adhiere a la especificación estándar de GraphQL. Para las consultas de GraphQL AEM con, hay algunas extensiones

Filtro CORS cors-filter

Para acceder al extremo de GraphQL, configure una política CORS en el repositorio Git del cliente. Esta configuración se realiza agregando un archivo de configuración OSGi CORS apropiado para uno o más extremos deseados.

Esta configuración debe especificar un origen de sitio web de confianza alloworigin o alloworiginregexp para el cual se debe conceder acceso.

Por ejemplo, para conceder acceso al extremo de GraphQL y al extremo de consultas persistentes para https://my.domain, puede utilizar:

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

Si ha configurado una ruta de vanidad para el punto de conexión, también puede utilizarla en allowedpaths.

Filtro de referente referrer-filter

Además de la configuración de CORS, debe configurarse un filtro de referente para permitir el acceso desde hosts de terceros.

Este filtro se realiza añadiendo un archivo de configuración del filtro de referente OSGi adecuado que:

Por ejemplo, para conceder acceso a solicitudes con el referente my.domain puede:

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

Limitaciones limitations

Para protegerse de posibles problemas, se han impuesto limitaciones predeterminadas a las consultas:

También debe tener en cuenta lo siguiente:

Autenticación authentication

Consulte Autenticación para consultas de GraphQL de AEM remotas en fragmentos de contenido.

Preguntas frecuentes faqs

Preguntas que han surgido:

Tutorial: Introducción a AEM Headless y GraphQL tutorial

¿Busca un tutorial práctico? Consulte el tutorial completo Introducción a AEM Headless y GraphQL, que ilustra cómo crear y exponer contenido mediante las API de GraphQL de AEM y consumido por una aplicación externa, en un escenario de CMS sin encabezado.