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) 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.
- AEM Commerce consume datos de una plataforma de Commerce a través de GraphQL.
- Los fragmentos de contenido de AEM trabajan junto con la API de GraphQL de AEM (una implementación personalizada, basada en GraphQL estándar) para ofrecer contenido estructurado para su uso en aplicaciones.
La API de GraphQL graphql-api
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 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-terminology
GraphQL utiliza lo siguiente:
-
- AEM genera los esquemas basándose en los modelos de fragmentos de contenido.
- Con sus esquemas, GraphQL presenta los tipos y operaciones permitidos para la implementación de GraphQL para AEM.
-
-
La ruta en AEM que responde a las consultas de GraphQL y proporciona acceso a los esquemas de GraphQL.
-
Consulte Activación del punto de conexión de GraphQL para obtener más información.
-
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:
-
Una entrada única
AEM proporciona funcionalidades para convertir consultas (de ambos tipos) a consultas persistentes, que pueden almacenar en caché Dispatcher y la red de distribución de contenido (CDN).
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 estas:
- Se almacenan en caché.
- Se administran centralmente mediante AEM as a Cloud Service
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 pueden alcanzar límites (por ejemplo, la longitud de la URL) que se pueden evitar utilizando Consultas persistentes.
Consulte Habilitar el almacenamiento en caché de consultas persistentes para obtener más información.
- Crea una variable de entorno de Cloud Manager llamada
ENABLE_GRAPHQL_ENDPOINT. - con el valor
true
IDE de GraphiQL graphiql-ide
Puede probar y depurar consultas de GraphQL usando el IDE de GraphiQL.
Casos de uso para la creación, previsualización y publicación use-cases-author-preview-publish
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 previsualización; se usa para:
- Previsualización de consultas antes de implementarlas en el entorno de publicación
- Datos de consulta para la aplicación JS (caso de uso estándar)
- Previsualización de consultas antes de implementarlas en el entorno de publicación
-
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 permission
Los permisos son los necesarios para acceder a Assets.
Las consultas de GraphQL se ejecutan con el permiso del usuario de AEM de la solicitud subyacente. Si el usuario no tiene acceso de lectura a algunos fragmentos (almacenados como activos), no pasarán a formar 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 establecimiento inflexible de tipos, 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 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.
-
Un modelo de fragmento de contenido:
-
El esquema correspondiente de GraphQL (salida de la documentación automática de GraphiQL):
Esto muestra que el tipo generado
ArticleModelcontiene varios campos.-
Tres de ellos han sido controlados por el usuario:
author,mainyreferencearticle. -
Los otros 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, (los campos de ayuda)
_path,_metadata,_variations.
-
-
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.
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:
-
Instala un paquete que contenga
Content-Fragment-Model-1yContent-Fragment-Model-2:- Se generan tipos de GraphQL para
Model-1yModel-2.
- Se generan tipos de GraphQL para
-
A continuación, modifique
Content-Fragment-Model-2:-
Solo el tipo de GraphQL
Model-2se actualizará. -
Mientras que
Model-1seguirá siendo el mismo.
-
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 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.
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 fields
Dentro del esquema hay campos individuales, de dos categorías básicas:
-
Campos que genera usted.
Una selección de Tipos de datos se utiliza para crear campos en función de cómo configure el modelo de fragmentos de contenido. Los nombres de campo se toman del campo Nombre de propiedad de la pestaña Tipo de datos.
- También hay que tener en cuenta el ajuste Procesar como, ya que los usuarios pueden configurar determinados tipos de datos. Por ejemplo, se puede configurar un campo de texto de una sola línea para que contenga varios textos de una sola línea eligiendo
multifieldde la lista desplegable.
- También hay que tener en cuenta el ajuste Procesar como, ya que los usuarios pueden configurar determinados tipos de datos. Por ejemplo, se puede configurar un campo de texto de una sola línea para que contenga varios textos de una sola línea eligiendo
-
GraphQL AEM para la también genera campos de ayuda.
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:
String, [String]String, [String]Float, [Float]BooleanCalendaronlyDate, onlyTime, dateTimeString[String]String, [String]Campo único:
Model - Tipo de modelo, al que se hace referencia directamenteMulticampo, con un tipo al que se hace referencia:
[Model] - Matriz de tipo Model, al que se hace referencia directamente desde la matrizMulticampo, con varios tipos a los que se hace referencia:
[AllFragmentModels] - Matriz de todos los tipos de modelo, a la que se hace referencia desde la matriz con tipo de uniónCampos 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. 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 Author, tal y como se proporciona en el tutorial de WKND.
{
authorList {
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/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_path
firstName
lastName
}
}
}
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 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:
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:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_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.
Tenga en cuenta que
StringMetadata y StringArrayMetadata hacen referencia a lo que se almacena en el repositorio, no a cómo se recuperan.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 variations
El campo _variations se ha implementado para simplificar la consulta de las variaciones que tiene un fragmento de contenido. Por ejemplo:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/ian-provo") {
item {
_variations
}
}
}
_variations no contiene una variación master, ya que técnicamente los datos originales (a los que se hace referencia como Principal en la interfaz de usuario) no se consideran una variación explícita.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 Author en una variación específica (si está disponible), puede especificar el argumento variation en GraphiQL.
Consulta:
query($variation: String!) {
authorList(variation: $variation) {
items {
_variation
lastName
firstName
}
}
}
Variables de consulta:
{
"variation": "another"
}
Esta consulta devolverá la lista completa de autores. Los autores sin la variación another volverán a los datos originales (_variation informará de master en este caso).
Aplique un filtro, si desea restringir la lista a autores que proporcionan la variación especificada (y omitir autores que recurren a los datos originales):
query($variation: String!) {
authorList(variation: $variation, filter: {
_variation: {
_expressions: {
value: $variation
}
}
}) {
items {
_variation
lastName
firstName
}
}
}
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.
Consulta:
query GetAdventureByType($includePrice: Boolean!) {
adventureList {
items {
title
price @include(if: $includePrice)
}
}
}
Variables de consulta:
{
"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 expresión
{
value: "some text"
_op: EQUALS
}
compararía el contenido del campo con el valor some text y se ejecuta correctamente si es igual al valor. De lo contrario, la expresión fallará.
Los siguientes operadores pueden utilizarse para comparar campos con un determinado valor:
EQUALSString, ID, BooleanEQUALS_NOTString, IDCONTAINSString{ value: "mas", _op: CONTAINS } coincidirá con Christmas, Xmas, master…)CONTAINS_NOTStringSTARTS_WITHID{ value: "/content/dam/", _op: STARTS_WITH coincidirá con /content/dam/path/to/fragment, pero no con /namespace/content/dam/somethingEQUALInt, FloatUNEQUALInt, FloatGREATERInt, FloatGREATER_EQUALInt, FloatLOWERInt, FloatLOWER_EQUALInt, FloatATCalendar, Date, TimeNOT_ATCalendar, Date, TimeBEFORECalendar, Date, TimeAT_OR_BEFORECalendar, Date, TimeAFTERCalendar, Date, TimeAT_OR_AFTERCalendar, Date, TimeAlgunos tipos también permiten especificar opciones adicionales que modifican cómo se evalúa una expresión:
_ignoreCaseStringtime coincide con TIME, time, tImE, …_sensitivenessFloatfloat se consideren iguales (para sortear las limitaciones técnicas debidas a la representación interna de los valores float; debe evitarse, ya que esta opción podría repercutir negativamente en el rendimientoLas expresiones se pueden combinar en un conjunto con la ayuda de un operador lógico (_logOp):
OR: el conjunto de expresiones tendrá éxito si al menos una expresión es correctaAND: el conjunto de expresiones tendrá éxito si todas las expresiones son correctas (opción predeterminada).
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 combinarán 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:
- Una subdefinición para cada campo (se puede acceder al campo a través de su nombre, por ejemplo, hay un campo
lastNameen el filtro para el campolastNameen el tipo de datos (campo)) - Cada subdefinición contiene la matriz
_expressions, que proporciona el conjunto de expresiones, y el campo_logOpque define el operador lógico con el que deben combinarse las expresiones - Cada expresión está definida por el valor (campo
value) y el operador (campo_operator), el contenido de un campo debe compararse con
Puede omitir _logOp si desea combinar elementos con AND y _operator si desea comprobar la igualdad, ya que estos son los valores 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
}
}
}
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:
-
detalles de GraphQL para extensiones de AEM
-
Ejemplos de consultas que utilizan este contenido y estructura de muestra
- Y el Contenido y estructura de muestra preparados para su uso en consultas de muestra
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:
-
una lista de valores separados por comas que representa la ruta del campo
- el primer campo de la lista definirá el criterio de ordenación principal, el segundo campo se utiliza si dos valores del criterio de ordenación principal son iguales, el tercero si los dos primeros criterios son iguales, y así sucesivamente.
- notación de puntos, es decir, field1.subfield.subfield, etc.
-
una dirección de orden opcional
- ASC (de subida) o DESC (de bajada); ASC se aplica como predeterminado
- se puede especificar la dirección por campo; esto significa que puede ordenar un campo en orden de subida y otro en orden de bajada (nombre, apellido DESC)
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:
offsetylimiten una consultaListfirstyafteren una consultaPaginated
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:
offset: especifica el primer conjunto de datos que se va a devolverlimit: especifica el número máximo de conjuntos de datos que se van a devolver
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
}
}
}
}
-
La paginación requiere un orden de clasificación estable para funcionar correctamente en varias consultas que soliciten diferentes páginas del mismo conjunto de resultados. De forma predeterminada, utiliza la ruta del repositorio de cada elemento del conjunto de resultados para asegurar que el orden sea siempre el mismo. Si se utiliza un orden de clasificación diferente y si esa clasificación no se puede realizar en el nivel de consulta JCR, se produce un impacto negativo en el rendimiento, ya que todo el conjunto de resultados debe cargarse en la memoria antes de que se puedan determinar las páginas.
-
Cuanto mayor sea el desplazamiento, más tiempo tardará en omitir los elementos del conjunto de resultados completo de la consulta JCR. Una solución alternativa para grandes conjuntos de resultados es utilizar la consulta paginada con el método
firstyafter.
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.
first: los primerosnartículos que se van a devolver.
El valor predeterminado es50.
El número máximo es100.after: el cursor que determina el comienzo de la página solicitada; tenga en cuenta que el elemento representado por el cursor no se incluye en el conjunto de resultados; el cursor de un elemento se determina mediante el campocursorde la estructuraedges.
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
}
}
}
-
De forma predeterminada, la paginación utiliza el UUID del nodo del repositorio que representa el fragmento para ordenar a fin de garantizar que el orden de los resultados sea siempre el mismo. Cuando se utiliza
sort, el UUID se utiliza implícitamente para garantizar una clasificación única; incluso para dos elementos con claves de clasificación idénticas. -
Debido a limitaciones técnicas internas, el rendimiento se degradará si se aplica clasificación y filtrado en los campos anidados. Por lo tanto, se recomienda utilizar campos de filtro/clasificación almacenados en el nivel raíz. Esta es también la forma recomendada si desea consultar grandes conjuntos de resultados paginados.
Envío de imágenes optimizadas para la web en consultas de GraphQL web-optimized-image-delivery-in-graphql-queries
La entrega de imágenes optimizadas para la web permite utilizar una consulta de Graphql para lo siguiente:
-
Solicitar una URL a una imagen de recurso DAM (a la que hace referencia una referencia de contenido)
-
Pase parámetros con la consulta para que se genere y devuelva automáticamente una representación específica de la imagen
note note NOTE La representación especificada no se almacena en AEM Assets. La representación se genera y se conserva en la caché durante un breve período. -
Devolución de la URL como parte del envío JSON
Puede utilizar AEM para lo siguiente:
- Pase Envío de imágenes optimizadas para la web en consultas de GraphQL.
Esto significa que los comandos se aplican durante la ejecución de la consulta, de la misma manera que los parámetros de URL en las solicitudes de GET para esas imágenes.
Esto permite crear de forma dinámica representaciones de imágenes para la entrega JSON, lo que evita tener que crear y almacenar manualmente esas representaciones en el repositorio.
La solución de GraphQL significa que puede hacer lo siguiente:
-
Solicitar una dirección URL: usar
_dynamicUrlen la referenciaImageRef -
Pasar parámetros: agregar
_assetTransformal encabezado de la lista donde se definen los filtros
_dynamicUrl: un recurso DAM_dmS7Url: un recurso de Dynamic Media
_dmS7Url será null. Ver entrega de recursos de Dynamic Media por dirección URL en consultas de GraphQL.Estructura de la solicitud de transformación structure-transformation-request
AssetTransform (_assetTransform) se utiliza para efectuar las solicitudes de transformación de URL.
La estructura y la sintaxis son las siguientes:
-
format: una enumeración con todos los formatos admitidos por su extensión: GIF, PNG, PNG8, JPG, PJPG, BJPG, WEBP, WEBPLL o WEBPLY -
seoName: una cadena que se utiliza como nombre de archivo en lugar del nombre de nodo -
crop: una subestructura de fotograma, si se omite la anchura o la altura, estas se utilizan como el mismo valorxOrigin: el origen x del fotograma, es obligatorioyOrigin: el origen y del fotograma, es obligatoriowidth: la anchura del fotogramaheight: la altura del fotograma
-
size: una subestructura de dimensión, si se omite la anchura o la altura, estas se utilizan como el mismo valorwidth: la anchura de la dimensiónheight: la altura de la dimensión
-
rotation: una enumeración de todas las rotaciones admitidas: R90, R180, R270 -
flip: una enumeración de HORIZONTAL, VERTICAL, HORIZONTAL_AND_VERTICAL -
quality: un entero entre 1 y 100 que indica el porcentaje de calidad de la imagen -
width: un entero que define la anchura de la imagen de salida, pero que el Generador de imágenes ignora -
preferWebp: un booleano que indica si se prefiere webp (el valor predeterminado es falso)
La transformación de URL está disponible para todos los tipos de consulta: por ruta, lista o paginada.
Envío de imágenes optimizado para la web con parámetros completos web-optimized-image-delivery-full-parameters
A continuación se muestra una consulta de ejemplo con un conjunto completo de parámetros:
{
articleList(
_assetTransform: {
format:GIF
seoName:"test"
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
Envío de imágenes optimizadas para la web con una sola variable de consulta web-optimized-image-delivery-single-query-variable
El siguiente ejemplo muestra el uso de una sola variable de consulta:
query ($seoName: String!) {
articleList(
_assetTransform: {
format:GIF
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
Envío de imágenes optimizadas para web con múltiples variables de consulta web-optimized-image-delivery-multiple-query-variables
El siguiente ejemplo muestra el uso de múltiples variables de consulta:
query ($seoName: String!, $format: AssetTransformFormat!) {
articleList(
_assetTransform: {
format:$format
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
Solicitud de envío de imágenes optimizadas para la web por dirección URL web-optimized-image-delivery-request-url
Si guarda la consulta como una consulta persistente (por ejemplo, con el nombre dynamic-url-x), puede ejecutar la consulta persistente directamente.
Por ejemplo, para ejecutar directamente los ejemplos anteriores (guardados como consultas persistentes), utilice las siguientes direcciones URL:
-
Parámetro único; consulta persistente con el nombre
dynamic-url-x-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic-url-x;seoName=xxxLa respuesta será la siguiente:
-
-
Múltiples parámetros; consulta persistente con el nombre
dynamic-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic;seoName=billiboy;format=GIF;note caution CAUTION El ;final es obligatorio para terminar de forma limpia la lista de parámetros.
-
Limitaciones de la entrega de imágenes optimizadas para la web web-optimized-image-delivery-limitations
Existen las siguientes limitaciones:
-
Modificadores aplicados a todas las imágenes que forman parte de la consulta (parámetros globales)
-
Almacenamiento en caché de encabezados
- Sin almacenamiento en caché en creación
- Almacenamiento en caché en publicación: max-age de 10 minutos (el cliente no puede modificarlo)
Entrega de recursos de Dynamic Media por dirección URL en consultas de GraphQL dynamic-media-asset-delivery-by-url
Los fragmentos de contenido de GraphQL AEM AEM para la le permiten solicitar una dirección URL a un recurso de Dynamic Media (Scene7) de la aplicación (al que hace referencia una referencia de contenido).
La solución de GraphQL significa que puede hacer lo siguiente:
-
use
_dmS7Urlen la referencia deImageRef -
usar
_dmS7Urlen múltiples referencias;ImageRef,MultimediaRefyDocumentRef -
usar
_dmS7Urlcon funcionalidad de recorte inteligente-
La propiedad
_smartCropsexpone las configuraciones de recorte inteligente disponibles para un recurso específico
-
dam:scene7File y dam:scene7Domain a los metadatos del recurso cuando se crea._dmS7Url: un recurso de Dynamic Media_dynamicUrl: un recurso DAM
_dynamicURL será null. Ver entrega de imágenes optimizadas para la web en consultas de GraphQL.Consulta de muestra para la entrega de recursos de Dynamic Media por dirección URL: referencia de imagen sample-query-dynamic-media-asset-delivery-by-url-imageref
A continuación se muestra un ejemplo de consulta:
- para varios fragmentos de contenido de tipo
teamyperson, devolviendo unImageRef
query allTeams {
teamList {
items {
_path
title
teamMembers {
fullName
profilePicture {
__typename
... on ImageRef{
_dmS7Url
height
width
}
}
}
}
}
}
Consulta de muestra para la entrega de recursos de Dynamic Media por dirección URL: varias referencias sample-query-dynamic-media-asset-delivery-by-url-multiple-refs
A continuación se muestra un ejemplo de consulta:
- para varios fragmentos de contenido de tipo
teamyperson, devolviendo unImageRef,MultimediaRefyDocumentRef:
query allTeams {
teamList {
items {
_path
title
teamMembers {
fullName
profilePicture {
__typename
... on ImageRef{
_dmS7Url
height
width
}
}
featureVideo {
__typename
... on MultimediaRef{
_dmS7Url
size
}
}
about-me {
__typename
... on DocumentRef{
_dmS7Url
_path
}
}
}
}
}
}
Consulta de muestra para la entrega de recursos de Dynamic Media por dirección URL: con recorte inteligente sample-query-dynamic-media-asset-delivery-by-url-smart-crop
A continuación se muestra un ejemplo de consulta:
- para exponer las configuraciones de recorte inteligente disponibles para los recursos solicitados
query allTeams {
teamList {
items {
title
teamMembers {
profilePicture {
... on ImageRef {
height
width
_dmS7Url
_smartCrops {
width
height
name
}
}
}
}
}
}
}
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 con AEM hay algunas extensiones:
-
Si necesita un solo resultado:
- use el nombre del modelo; por ejemplo, ciudad
-
Si espera una lista de resultados:
- añada
Listal nombre del modelo; por ejemplo,cityList - Consulte Consulta de muestra: toda la información acerca de todas las ciudades
Podrá hacer lo siguiente:
-
Clasificación de los resultados
ASC: ascendenteDESC: descendente
-
Devuelva una página de resultados utilizando lo siguiente:
-
Consulte Consulta de muestra: toda la información acerca de todas las ciudades
- añada
-
El filtro
includeVariationsestá incluido en los tipos de consultaListyPaginated. Para recuperar las variaciones de fragmentos de contenido en los resultados de la consulta, el filtroincludeVariationsdebe establecerse entrue.- Consulte Consulta de muestra para varios fragmentos de contenido y sus variaciones de un modelo determinado
note caution CAUTION El filtro includeVariationsy el campo generado por el sistema_variationno se pueden usar juntos en la misma definición de consulta. -
Si desea utilizar un OR lógico:
- use
_logOp: OR - Consulte Consulta de muestra: todas las personas que tienen el apellido “Jobs” o “Smith”
- use
-
El AND lógico también existe, pero (a menudo) está implícito
-
Puede consultar los nombres de campo que se correspondan con los campos del modelo de fragmento de contenido
-
Además de los campos del modelo, hay algunos campos generados por el sistema (precedidos de guiones bajos):
-
Para el contenido:
-
_locale: para revelar el idioma; basado en el Administrador de idiomas -
_metadata: para mostrar los metadatos del fragmento -
_model: permitir la consulta de un modelo de fragmento de contenido (ruta y título) -
_path: la ruta al fragmento de contenido dentro del repositorio -
_reference: para revelar referencias, incluyendo referencias en línea en el Editor de texto enriquecido -
_variation: para mostrar variaciones específicas dentro del fragmento de contenidonote note NOTE Si la variación dada no existe para un Fragmento de contenido, la variación principal se devuelve como una predeterminada (alternativa). note caution CAUTION El campo generado por el sistema _variationno se puede usar junto con el filtroincludeVariations.
-
-
Para la entrega de imágenes:
-
AEM
_authorURL: la dirección URL completa del recurso de imagen en el autor de la -
AEM
_publishURL: la dirección URL completa del recurso de imagen en Publish, en la que se ha producido la -
Para entrega de imágenes optimizadas para la web (de recursos DAM):
-
_dynamicUrl: la dirección URL completa del recurso DAM optimizado para la web en la referenciaImageRefnote note NOTE _dynamicUrles la dirección URL preferida que se usa para los recursos DAM optimizados para la web y debe reemplazar el uso de_path,_authorUrly_publishUrlsiempre que sea posible. -
_assetTransform: para pasar parámetros en el encabezado de lista donde se definen los filtros -
Consulte:
-
-
_dmS7Url: en la referenciaImageRefpara el envío de la URL a un recurso de Dynamic Media
-
-
_tags: para revelar los identificadores de los fragmentos de contenido o las variaciones que contienen etiquetas; se trata de una matriz de identificadorescq:tags.- Consulte Consulta de muestra: nombres de todas las ciudades etiquetadas como escapadas
- Consulte Consulta de muestra para variaciones de fragmentos de contenido de un modelo determinado que tienen una etiqueta específica adjunta
- Consulte Consulta de muestra con filtrado por los ID _tags y excluyendo variaciones
- Consulte Consulta de muestra con filtrado por los ID _tags e incluyendo variaciones
note note NOTE Las etiquetas también se pueden consultar enumerando los metadatos de un fragmento de contenido. -
Y operaciones:
-
_operator: aplicar operadores específicos;EQUALS,EQUALS_NOT,GREATER_EQUAL,LOWER,CONTAINS,STARTS_WITH -
_apply: para aplicar condiciones específicas; por ejemplo,AT_LEAST_ONCE -
_ignoreCase: para ignorar el caso al consultar
-
-
-
Se admiten los tipos de unión de GraphQL:
-
Alternativa cuando se consultan fragmentos anidados:
- Si una variación determinada no existe en un fragmento anidado, se devolvería la variación Principal.
Consulta del punto de conexión de GraphQL desde un sitio web externo query-graphql-endpoint-from-external-website
Para acceder al punto de conexión de GraphQL desde un sitio web externo, debe configurar lo siguiente:
Autenticación authentication
Consulte Autenticación para consultas de GraphQL de AEM remotas en fragmentos de contenido.
Pruebas automatizadas automated-testing
Al ejecutar una canalización de implementación en AEM Cloud Manager, las pruebas automatizadas se ejecutan durante la ejecución de la canalización.
Para proporcionar resultados precisos, el entorno de AEM as a Cloud Service Stage debe reflejar su entorno de producción lo más fielmente posible. Esto es especialmente importante para el contenido.
Puede conseguirlo utilizando la herramienta de copia de contenido de AEM as a Cloud Service para copiar el contenido de producción en el entorno de ensayo.
Limitaciones limitations
Para protegerse de posibles problemas, se han impuesto limitaciones predeterminadas a las consultas:
- La consulta no puede contener más de 1 millón de caracteres (1024 * 1024)
- La consulta no puede contener más de 15000 tokens
- La consulta no puede contener más de 200000 tokens de espacio en blanco
También debe tener en cuenta lo siguiente:
-
Se devolverá un error de conflicto de campos cuando la consulta de GraphQL contenga campos con el mismo nombre en dos (o más) modelos y se cumplan las siguientes condiciones:
-
Entonces, ¿dónde?
- Dos (o más modelos) se usan como posibles referencias; cuando se definen como un Tipo de modelo permitido en la referencia de fragmento de contenido.
y:
- Estos dos modelos tienen campos con un nombre común; es decir, el mismo nombre se produce en ambos modelos.
y
- Estos campos son de diferentes tipos de datos.
-
Por ejemplo:
-
Cuando se usan dos (o más) fragmentos con modelos diferentes (por ejemplo,
M1,M2) como posibles referencias (Referencia de contenido o Referencia de fragmento) de otro fragmento; por ejemplo,Fragment1MultiField/List -
Y estos dos fragmentos con diferentes modelos (
M1,M2) tienen campos con el mismo nombre, pero de diferentes tipos.
Como ejemplo:M1.TitlecomoTextM2.TitlecomoText/MultiField
-
Entonces, se producirá un error de conflicto de campos si la consulta de GraphQL contiene el campo
Title.
-
-
Preguntas frecuentes faqs
Preguntas que han surgido:
-
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.”
- 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.
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.