API de GraphQL de AEM para su uso con fragmentos de contenido

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

La API de GraphQL de AEM as a Cloud Service que se utiliza con fragmentos de contenido se basa principalmente en la API estándar de código abierto de GraphQL.

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:

  • Evita solicitudes de API iterativas como con REST,
  • Garantiza que la entrega se limite a los requisitos específicos,
  • Permite la entrega masiva de exactamente lo que se necesita para procesar como respuesta a una sola consulta de API.
NOTA

GraphQL se utiliza actualmente en dos escenarios (independientes) en Adobe Experience Manager (AEM) as a Cloud Service:

La API de GraphQL

GraphQL es:

  • …un idioma de consulta para API y un tiempo de ejecución para cumplir esas consultas con los datos existentes. GraphQL proporciona una descripción completa y comprensible de los datos de su API, ofrece a los clientes la posibilidad de preguntar exactamente lo que necesitan y nada más, facilita la evolución de las API con el paso del tiempo y habilita potentes herramientas para desarrolladores”.

    Consulte GraphQL.org

  • …una especificación abierta para una capa de API flexible. Coloque GraphQL sobre los back-ends existentes para crear productos más rápido que nunca…”.

    Consulte Exploración de GraphQL.

  • “…una especificación y lenguaje de consulta de datos desarrollado internamente por Facebook en 2012, antes de pasar a ser de código abierto público en 2015. Proporciona una alternativa a las arquitecturas basadas en REST con el propósito de aumentar la productividad del desarrollador y minimizar las cantidades de datos transferidos. Cientos de organizaciones de todos los tamaños utilizan GraphQL en producción…”

    Consulte Fundamentos de GraphQL.

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

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

Terminología de GraphQL

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

Con GraphQL puede realizar consultas para devolver lo siguiente:

También puede realizar:

Prácticas recomendadas para consultas de GraphQL (Dispatcher)

La variable Consultas persistentes son el método recomendado como:

  • se almacenan en caché
  • se administran centralmente mediante AEM as a Cloud Service

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

NOTA

Para permitir consultas directas o POST en Dispatcher, puede pedir al administrador del sistema que:

  • Cree una variable de entorno de Cloud Manager llamada ENABLE_GRAPHQL_ENDPOINT
  • con el valor true
NOTA

La capacidad de realizar consultas directas puede quedar obsoleta en algún momento futuro.

IDE de GraphiQL

Puede probar y depurar consultas de GraphQL usando el IDE de GraphiQL.

Casos de uso para entornos de creación y publicación

Los casos de uso pueden depender del tipo de entorno de AEM as a Cloud Service:

  • Entorno de publicación; se usa para:

    • Datos de consulta para la aplicación JS (caso de uso estándar)
  • Entorno de creación; se usa para:

    • Datos de consulta para “fines de administración de contenido”:
      • GraphQL en AEM as a Cloud Service es actualmente una API de solo lectura.
      • La API de REST se puede utilizar para operaciones CR(u)D.

Permisos

Los permisos son los necesarios para acceder a Assets.

Generación de esquemas

GraphQL es una API muy tipificada, 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 ello, un cliente debe recuperar 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.

PRECAUCIÓN

Todos los esquemas de GraphQL (derivados de los modelos de fragmentos de contenido que se han habilitado) se pueden leer a través del punto de conexión de GraphQL.

Esto significa que debe asegurarse de que no hay datos confidenciales disponibles, ya que podrían filtrarse de esta manera; por ejemplo, esto incluye información que podría estar presente como nombres de campo en la definición del modelo.

Por ejemplo, si un usuario crea un modelo de fragmentos de contenido denominado Article, luego AEM genera el objeto article, que es de un tipo ArticleModel. Los campos dentro de este tipo corresponden a los campos y tipos de datos definidos en el modelo.

  1. Un modelo de fragmento de contenido:

    Modelo de fragmento de contenido para usar con GraphQL

  2. El esquema correspondiente de GraphQL (salida de la documentación automática de GraphiQL):
    Esquema de GraphQL basado en el modelo de fragmento de contenido

    Esto muestra que el tipo generado ArticleModel contiene varios campos.

    • Tres de ellos han sido controlados por el usuario: author, main y referencearticle.

    • Los demás campos los añadió automáticamente AEM y representan métodos útiles para proporcionar información acerca de un determinado fragmento de contenido; en este ejemplo, _path, _metadata, _variations. 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.

  3. Después de que un usuario cree un fragmento de contenido basado en el modelo de artículo, se puede buscar a través de GraphQL. Para ver ejemplos, consulte las Consultas de muestra (basadas en una estructura de fragmentos de contenido de muestra para usar con GraphQL).

En GraphQL para AEM, el esquema es flexible. Esto 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:

  1. Instala un paquete que contenga Content-Fragment-Model-1 y Content-Fragment-Model-2:

    1. Se generarán tipos de GraphQL para Model-1 y Model-2.
  2. A continuación, modifique Content-Fragment-Model-2:

    1. Solo el tipo de GraphQL Model-2 se actualizará.

    2. Mientras que Model-1 seguirá siendo el mismo.

NOTA

Esto es importante tenerlo en cuenta en caso de que desee realizar actualizaciones masivas en los modelos de fragmento de contenido a través de la API de REST o de otro modo.

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 resultará en la salida del esquema con el tipo contenido: text/x-graphql-schema;charset=iso-8859-1.

Generación de esquemas: modelos no publicados

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.

NOTA

La IU de AEM evita que esto ocurra, pero si la publicación se realiza mediante programación o con paquetes de contenido, puede ocurrir.

Cuando esto sucede, AEM genera un esquema incompleto del modelo de fragmento del contenido principal. Esto significa que la referencia de fragmento, que depende del modelo no publicado, se elimina del esquema.

Campos

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

  • Campos que genera usted.

    Una selección de Tipos de campo se utiliza para crear campos en función de cómo configure el modelo de fragmento de contenido. Los nombres de campo se toman del campo Nombre de propiedad del Tipo de datos.

    • También se debe tener en cuenta la propiedad Procesar como, ya que los usuarios pueden configurar ciertos tipos de datos; por ejemplo, como texto de una sola línea o como campo múltiple.
  • GraphQL para AEM también genera una serie de campos de ayuda.

    Se utilizan para identificar un fragmento de contenido o para obtener más información acerca de uno.

Tipos de campos

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:

Modelo de fragmento de contenido: tipo de datos Tipo de GraphQL Descripción
Texto de línea única Cadena, [Cadena] Se utiliza para cadenas simples como nombres de autor, nombres de ubicación, etc.
Texto multilínea Cadena Se utiliza para generar texto como el cuerpo de un artículo
Número Flotante, [Flotante] Se utiliza para mostrar números de coma flotante y números regulares
Booleano Booleano Se utiliza para mostrar casillas de verificación → instrucciones simples verdaderas/falsas
Fecha y hora Calendario Se utiliza para mostrar la fecha y la hora en formato ISO 8086. Según el tipo seleccionado, hay tres variantes disponibles para usar en AEM GraphQL: onlyDate, onlyTime, dateTime
Lista desglosada Cadena Se utiliza para mostrar una opción de una lista de opciones definidas en la creación del modelo
Etiquetas [Cadena] Se utiliza para mostrar una lista de cadenas que representan las etiquetas utilizadas en AEM
Referencia de contenido Cadena Se utiliza para mostrar la ruta hacia otro recurso en AEM
Referencia al fragmento Un tipo de modelo Se utiliza para hacer referencia a otro fragmento de contenido de un tipo de modelo determinado, definido cuando se creó el modelo

Campos de ayuda

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

Ruta

El campo de ruta se utiliza como identificador en GraphQL. Representa la ruta del recurso de fragmento de contenido dentro del repositorio de AEM. Lo hemos elegido como identificador de un fragmento de contenido, por los motivos siguientes:

  • es único dentro de AEM,
  • se puede recuperar fácilmente.

El siguiente código muestra las rutas de todos los fragmentos de contenido creados en función del 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:

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

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

Metadatos

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 su título, la ruta de la miniatura, la descripción de un fragmento de contenido o la fecha en que se creó, entre otros.

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:

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

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, sabemos que esta propiedad es de cadena, por lo que consultaremos 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.

NOTA

Diferencia entre metadatos normales y de matriz
Tenga en cuenta que StringMetadata y StringArrayMetadata hacen referencia a lo que se almacena en el repositorio, no a cómo se recuperan.

Por ejemplo, llamando al campo stringMetadata, recibirá una matriz de todos los metadatos almacenados en el repositorio como String, y si llama a stringArrayMetadata recibirá una matriz de todos los metadatos almacenados en el repositorio como String[].

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

Variaciones

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 permite colocar variables en la consulta. Para obtener más información, consulte la 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.

Variables de GraphQL

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

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

Directivas de GraphQL

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.

Directivas de GraphQL

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

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

Filtrado

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.

Por ejemplo, la siguiente consulta (básica) filtra todas las personas que tienen un apellido Jobs o Smith:

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

Para ver más ejemplos, consulte lo siguiente:

GraphQL para AEM: resumen de extensiones

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 con AEM hay algunas extensiones:

Consulta del punto de conexión de GraphQL desde un sitio web externo

Para acceder al punto de conexión de GraphQL desde un sitio web externo, debe configurar lo siguiente:

Autenticación

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

Preguntas frecuentes

Preguntas que han surgido:

  1. P: “¿En qué se diferencia la API de GraphQL para AEM de la API Generador de consultas?

    • R: “La API de GraphQL de AEM ofrece control total sobre la salida JSON y es un estándar en la industria para consultar contenido.
      En adelante, AEM tiene previsto invertir en la API de GraphQL de AEM”.

Tutorial: Introducción a AEM Headless y GraphQL

¿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.

En esta página