DocumentaciónAEMTutoriales de AEMTutorial de AEM sin encabezado

Exploración de la API de GraphQL de AEM

Last update: Mon Mar 24 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Creado para:

  • Intermedio
  • Desarrollador

La API de GraphQL en AEM le permite exponer los datos de fragmentos de contenido a aplicaciones de flujo descendente. En el tutorial básico tutorial de GraphQL de varios pasos, utilizó el Explorador de GraphiQL para probar y refinar las consultas de GraphQL.

En este capítulo, utiliza el Explorador de GraphiQL para definir consultas más avanzadas con el fin de recopilar datos de los fragmentos de contenido que creó en el capítulo anterior.

Requisitos previos prerequisites

Este documento forma parte de un tutorial de varias partes. Asegúrese de que los capítulos anteriores se hayan completado antes de continuar con este capítulo.

Objetivos objectives

En este capítulo, aprenderá a hacer lo siguiente:

  • Filtrado de una lista de fragmentos de contenido con referencias mediante variables de consulta
  • Filtrado de contenido dentro de una referencia de fragmento
  • Consulta de contenido en línea y referencias de fragmento desde un campo de texto multilínea
  • Consulta mediante directivas
  • Consulta del tipo de contenido de objeto JSON

Uso del Explorador de GraphiQL

La herramienta Explorador de GraphiQL permite a los desarrolladores crear y probar consultas con contenido en el entorno de AEM actual. La herramienta GraphiQL también permite a los usuarios mantener o guardar consultas para que las usen las aplicaciones cliente en una configuración de producción.

A continuación, explore la potencia de la API de GraphQL de AEM mediante el Explorador de GraphiQL integrado.

  1. En la pantalla de inicio de AEM, vaya a Herramientas > General > Editor de consultas de GraphQL.

    Vaya al IDE de GraphiQL

IMPORTANT
En, algunas versiones de AEM (6.X.X) y la herramienta Explorador de GraphiQL (también conocida como IDE de GraphiQL) deben instalarse manualmente. Siga las instrucciones desde aquí.

  1. En la esquina superior derecha, asegúrese de que el extremo está establecido en WKND Shared Endpoint. Si se cambia el valor desplegable Extremo aquí, se mostrarán las Consultas persistentes existentes en la esquina superior izquierda.

    Establecer extremo de GraphQL

Esto ampliará todas las consultas a los modelos creados en el proyecto WKND compartido.

Filtrado de una lista de fragmentos de contenido mediante variables de consulta

En el tutorial anterior de GraphQL de varios pasos, definió y utilizó consultas persistentes básicas para obtener datos de fragmentos de contenido. Aquí puede ampliar este conocimiento y filtrar los datos de fragmentos de contenido pasando variables a las consultas persistentes.

Al desarrollar aplicaciones cliente, normalmente debe filtrar los fragmentos de contenido en función de argumentos dinámicos. La API de GraphQL de AEM le permite pasar estos argumentos como variables en una consulta para evitar la construcción de cadenas en el lado del cliente durante la ejecución. Para obtener más información sobre las variables de GraphQL, consulte la documentación de GraphQL.

Para este ejemplo, consulte todos los instructores que tengan una aptitud determinada.

  1. En el IDE de GraphiQL, pegue la siguiente consulta en el panel izquierdo:

    code language-graphql 
    query listPersonBySkill ($skillFilter: String!){
  personList(
    _locale: "en"
    filter: {skills: {_expressions: [{value: $skillFilter}]}}
  ) {
    items {
      fullName
      contactInfo {
        phone
        email
      }
      profilePicture {
        ... on ImageRef {
          _path
        }
      }
      biography {
        plaintext
      }
      instructorExperienceLevel
      skills
    }
  }
}

    La consulta listPersonBySkill anterior acepta una variable (skillFilter) que es un(a) String obligatorio(a). Esta consulta realiza una búsqueda en todos los fragmentos de contenido de persona y los filtra en función del campo skills y de la cadena pasada en skillFilter.

    listPersonBySkill incluye la propiedad contactInfo, que es una referencia de fragmento al modelo de información de contacto definido en los capítulos anteriores. El modelo de información de contacto contiene phone y email campos. Debe haber al menos uno de estos campos en la consulta para que funcione correctamente.

    code language-graphql 
    contactInfo {
        phone
        email
      }

  2. A continuación, definamos skillFilter y obtengamos todos los instructores que sean competentes en esquí. Pegue la siguiente cadena JSON en el panel Variables de consulta del IDE de GraphiQL:

    code language-json 
    {
    "skillFilter": "Skiing"
}

  3. Ejecute la consulta. El resultado debe ser similar al siguiente:

    code language-json 
    {
  "data": {
    "personList": {
      "items": [
        {
          "fullName": "Stacey Roswells",
          "contactInfo": {
            "phone": "209-888-0011",
            "email": "sroswells@wknd.com"
          },
          "profilePicture": {
            "_path": "/content/dam/wknd-shared/en/contributors/stacey-roswells.jpg"
          },
          "biography": {
            "plaintext": "Stacey Roswells is an accomplished rock climber and alpine adventurer. Born in Baltimore, Maryland, Stacey is the youngest of six children. Stacey's father was a lieutenant colonel in the US Navy and mother was a modern dance instructor. Stacey's family moved frequently with father's duty assignments and took the first pictures when father was stationed in Thailand. This is also where Stacey learned to rock climb."
          },
          "instructorExperienceLevel": "Advanced",
          "skills": [
            "Rock Climbing",
            "Skiing",
            "Backpacking"
          ]
        }
      ]
    }
  }
}

Presione el botón Reproducir en el menú superior para ejecutar la consulta. Debería ver los resultados de los fragmentos de contenido del capítulo anterior:

Resultados de persona por aptitud

Filtrado de contenido dentro de una referencia de fragmento

La API de AEM GraphQL permite consultar fragmentos de contenido anidados. En el capítulo anterior, agregó tres nuevas referencias de fragmento a un fragmento de contenido de aventura: location, instructorTeam y administrator. Ahora, vamos a filtrar todas las aventuras para cualquier administrador que tenga un nombre en particular.

CAUTION
Solo se debe permitir un modelo como referencia para que esta consulta funcione correctamente.

  1. En el IDE de GraphiQL, pegue la siguiente consulta en el panel izquierdo:

    code language-graphql 
    query getAdventureAdministratorDetailsByAdministratorName ($name: String!){
  adventureList(
  _locale: "en"
    filter: {administrator: {fullName: {_expressions: [{value: $name}]}}}
  ) {
    items {
      title
      administrator {
        fullName
        contactInfo {
          phone
          email
        }
        administratorDetails {
          json
        }
      }
    }
  }
}

  2. A continuación, pegue la siguiente cadena JSON en el panel Variables de consulta:

    code language-json 
    {
    "name": "Jacob Wester"
}

    La consulta getAdventureAdministratorDetailsByAdministratorName filtra todas las aventuras para cualquier administrator de fullName "Jacob Wester", devolviendo información de entre dos fragmentos de contenido anidados: Aventura e Instructor.

  3. Ejecute la consulta. El resultado debe ser similar al siguiente:

    code language-json 
    {
  "data": {
    "adventureList": {
      "items": [
        {
          "title": "Yosemite Backpacking",
          "administrator": {
            "fullName": "Jacob Wester",
            "contactInfo": {
              "phone": "209-888-0000",
              "email": "jwester@wknd.com"
            },
            "administratorDetails": {
              "json": [
                {
                  "nodeType": "paragraph",
                  "content": [
                    {
                      "nodeType": "text",
                      "value": "Jacob Wester has been coordinating backpacking adventures for three years."
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Consulta de referencias en línea desde un campo de texto multilínea query-rte-reference

La API de GraphQL de AEM le permite consultar contenido y referencias de fragmento dentro de campos de texto multilínea. En el capítulo anterior, agregó ambos tipos de referencia al campo Descripción del fragmento de contenido del equipo de Yosemite. Ahora, vamos a recuperar estas referencias.

  1. En el IDE de GraphiQL, pegue la siguiente consulta en el panel izquierdo:

    code language-graphql 
    query getTeamByAdventurePath ($fragmentPath: String!){
  adventureByPath (_path: $fragmentPath) {
    item {
      instructorTeam {
        _metadata {
          stringMetadata {
            name
            value
          }
      }
        teamFoundingDate
        description {
          plaintext
        }
      }
    }
    _references {
      ... on ImageRef {
        __typename
        _path
      }
      ... on LocationModel {
        __typename
        _path
        name
        address {
          streetAddress
          city
          zipCode
          country
        }
        contactInfo {
          phone
          email
        }
      }
    }
  }
}

    La consulta getTeamByAdventurePath filtra todas las aventuras por ruta de acceso y devuelve datos para la referencia de fragmento instructorTeam de una aventura específica.

    _references es un campo generado por el sistema que se usa para mostrar referencias, incluidas las que se insertan en campos de texto multilínea.

    La consulta getTeamByAdventurePath recupera varias referencias. En primer lugar, utiliza el objeto integrado ImageRef para recuperar las _path y __typename de imágenes insertadas como referencias de contenido en el campo de texto multilínea. A continuación, utiliza LocationModel para recuperar los datos del fragmento de contenido de ubicación insertado en el mismo campo.

    La consulta también incluye el campo _metadata. Esto le permite recuperar el nombre del fragmento de contenido del equipo y mostrarlo más adelante en la aplicación WKND.

  2. A continuación, pegue la siguiente cadena JSON en el panel Variables de consulta para obtener la aventura de mochilero de Yosemite:

    code language-json 
    {
    "fragmentPath": "/content/dam/wknd-shared/en/adventures/yosemite-backpacking/yosemite-backpacking"
}

  3. Ejecute la consulta. El resultado debe ser similar al siguiente:

    code language-json 
    {
  "data": {
    "adventureByPath": {
      "item": {
        "instructorTeam": {
          "_metadata": {
            "stringMetadata": [
              {
                "name": "title",
                "value": "Yosemite Team"
              },
              {
                "name": "description",
                "value": ""
              }
            ]
          },
          "teamFoundingDate": "2016-05-24",
          "description": {
            "plaintext": "\n\nThe team of professional adventurers and hiking instructors working in Yosemite National Park.\n\nYosemite Valley Lodge"
          }
        }
      },
      "_references": [
        {
          "__typename": "LocationModel",
          "_path": "/content/dam/wknd-shared/en/adventures/locations/yosemite-valley-lodge/yosemite-valley-lodge",
          "name": "Yosemite Valley Lodge",
          "address": {
            "streetAddress": "9006 Yosemite Lodge Drive",
            "city": "Yosemite National Park",
            "zipCode": "95389",
            "country": "United States"
          },
          "contactInfo": {
            "phone": "209-992-0000",
            "email": "yosemitelodge@wknd.com"
          }
        },
        {
          "__typename": "ImageRef",
          "_path": "/content/dam/wknd-shared/en/adventures/teams/yosemite-team/team-yosemite-logo.png"
        }
      ]
    }
  }
}

    El campo _references muestra tanto la imagen del logotipo como el fragmento de contenido de Yosemite Valley Lodge que se insertó en el campo Descripción.

Consulta mediante directivas

A veces, al desarrollar aplicaciones cliente, debe cambiar condicionalmente la estructura de las consultas. En este caso, la API de GraphQL de AEM le permite utilizar directivas de GraphQL para cambiar el comportamiento de las consultas en función de los criterios proporcionados. Para obtener más información sobre las directivas de GraphQL, consulte la documentación de GraphQL.

En la sección anterior, aprendió a consultar referencias en línea dentro de campos de texto multilínea. El contenido se recuperó del campo description en formato plaintext. A continuación, expandamos esa consulta y utilicemos una directiva para recuperar condicionalmente description en el formato json.

  1. En el IDE de GraphiQL, pegue la siguiente consulta en el panel izquierdo:

    code language-graphql 
    query getTeamByAdventurePath ($fragmentPath: String!, $includeJson: Boolean!){
  adventureByPath(_path: $fragmentPath) {
    item {
      instructorTeam {
        _metadata{
          stringMetadata{
            name
            value
          }
        }
        teamFoundingDate
        description {
          plaintext
          json @include(if: $includeJson)
        }
      }
    }
    _references {
      ... on ImageRef {
        __typename
        _path
      }
      ... on LocationModel {
        __typename
        _path
        name
        address {
          streetAddress
          city
          zipCode
          country
        }
        contactInfo {
          phone
          email
        }
      }
    }
  }
}

    La consulta anterior acepta una variable más (includeJson) que es una Boolean necesaria, también conocida como directiva de la consulta. Se puede usar una directiva para incluir condicionalmente datos del campo description en el formato json en función del booleano que se pasa en includeJson.

  2. A continuación, pegue la siguiente cadena JSON en el panel Variables de consulta:

    code language-json 
    {
  "fragmentPath": "/content/dam/wknd-shared/en/adventures/yosemite-backpacking/yosemite-backpacking",
  "includeJson": false
}

  3. Ejecute la consulta. Debería obtener el mismo resultado que en la sección anterior de cómo consultar referencias en línea dentro de campos de texto multilínea.

  4. Actualice la directiva includeJson a true y ejecute de nuevo la consulta. El resultado debe ser similar al siguiente:

    code language-json 
    {
  "data": {
    "adventureByPath": {
      "item": {
        "instructorTeam": {
          "_metadata": {
            "stringMetadata": [
              {
                "name": "title",
                "value": "Yosemite Team"
              },
              {
                "name": "description",
                "value": ""
              }
            ]
          },
          "teamFoundingDate": "2016-05-24",
          "description": {
            "plaintext": "\n\nThe team of professional adventurers and hiking instructors working in Yosemite National Park.\n\nYosemite Valley Lodge",
            "json": [
              {
                "nodeType": "paragraph",
                "content": [
                  {
                    "nodeType": "reference",
                    "data": {
                      "path": "/content/dam/wknd-shared/en/adventures/teams/yosemite-team/team-yosemite-logo.png",
                      "mimetype": "image/png"
                    }
                  }
                ]
              },
              {
                "nodeType": "paragraph",
                "content": [
                  {
                    "nodeType": "text",
                    "value": "The team of professional adventurers and hiking instructors working in Yosemite National Park."
                  }
                ]
              },
              {
                "nodeType": "paragraph",
                "content": [
                  {
                    "nodeType": "reference",
                    "data": {
                      "href": "/content/dam/wknd-shared/en/adventures/locations/yosemite-valley-lodge/yosemite-valley-lodge",
                      "type": "fragment"
                    },
                    "value": "Yosemite Valley Lodge"
                  }
                ]
              }
            ]
          }
        }
      },
      "_references": [
        {
          "__typename": "LocationModel",
          "_path": "/content/dam/wknd-shared/en/adventures/locations/yosemite-valley-lodge/yosemite-valley-lodge",
          "name": "Yosemite Valley Lodge",
          "address": {
            "streetAddress": "9006 Yosemite Lodge Drive",
            "city": "Yosemite National Park",
            "zipCode": "95389",
            "country": "United States"
          },
          "contactInfo": {
            "phone": "209-992-0000",
            "email": "yosemitelodge@wknd.com"
          }
        },
        {
          "__typename": "ImageRef",
          "_path": "/content/dam/wknd-shared/en/adventures/teams/yosemite-team/team-yosemite-logo.png"
        }
      ]
    }
  }
}

Consulta del tipo de contenido de objeto JSON

Recuerde que en el capítulo anterior sobre la creación de fragmentos de contenido, agregó un objeto JSON al campo Clima por temporada. Ahora recuperemos esos datos dentro del fragmento de contenido de ubicación.

  1. En el IDE de GraphiQL, pegue la siguiente consulta en el panel izquierdo:

    code language-graphql 
    query getLocationDetailsByLocationPath ($fragmentPath: String!) {
  locationByPath(_path: $fragmentPath) {
    item {
      name
      description {
        json
      }
      contactInfo {
        phone
        email
      }
      locationImage {
        ... on ImageRef {
          _path
        }
      }
      weatherBySeason
      address {
        streetAddress
        city
        state
        zipCode
        country
      }
    }
  }
}

  2. A continuación, pegue la siguiente cadena JSON en el panel Variables de consulta:

    code language-json 
    {
  "fragmentPath": "/content/dam/wknd-shared/en/adventures/locations/yosemite-national-park/yosemite-national-park"
}

  3. Ejecute la consulta. El resultado debe ser similar al siguiente:

    code language-json 
    {
  "data": {
    "locationByPath": {
      "item": {
        "name": "Yosemite National Park",
        "description": {
          "json": [
            {
              "nodeType": "paragraph",
              "content": [
                {
                  "nodeType": "text",
                  "value": "Yosemite National Park is in California's Sierra Nevada mountains. It's famous for its gorgeous waterfalls, giant sequoia trees, and iconic views of El Capitan and Half Dome cliffs."
                }
              ]
            },
            {
              "nodeType": "paragraph",
              "content": [
                {
                  "nodeType": "text",
                  "value": "Hiking and camping are the best ways to experience Yosemite. Numerous trails provide endless opportunities for adventure and exploration."
                }
              ]
            }
          ]
        },
        "contactInfo": {
          "phone": "209-999-0000",
          "email": "yosemite@wknd.com"
        },
        "locationImage": {
          "_path": "/content/dam/wknd-shared/en/adventures/locations/yosemite-national-park/yosemite-national-park.jpeg"
        },
        "weatherBySeason": {
          "summer": "81 / 89°F",
          "fall": "56 / 83°F",
          "winter": "46 / 51°F",
          "spring": "57 / 71°F"
        },
        "address": {
          "streetAddress": "9010 Curry Village Drive",
          "city": "Yosemite Valley",
          "state": "CA",
          "zipCode": "95389",
          "country": "United States"
        }
      }
    }
  }
}

    El campo weatherBySeason contiene el objeto JSON agregado en el capítulo anterior.

Consultar todo el contenido a la vez

Hasta ahora, se han ejecutado varias consultas para ilustrar las capacidades de la API de GraphQL de AEM.

Los mismos datos se pudieron recuperar con una sola consulta y esta consulta se utiliza posteriormente en la aplicación cliente para recuperar información adicional como la ubicación, el nombre del equipo o los integrantes del equipo de una aventura:

query getAdventureDetailsBySlug($slug: String!) {
  adventureList(filter: {slug: {_expressions: [{value: $slug}]}}) {
    items {
      _path
      title
      activity
      adventureType
      price
      tripLength
      groupSize
      difficulty
      primaryImage {
        ... on ImageRef {
          _path
          mimeType
          width
          height
        }
      }
      description {
        html
        json
      }
      itinerary {
        html
        json
      }
      location {
        _path
        name
        description {
          html
          json
        }
        contactInfo {
          phone
          email
        }
        locationImage {
          ... on ImageRef {
            _path
          }
        }
        weatherBySeason
        address {
          streetAddress
          city
          state
          zipCode
          country
        }
      }
      instructorTeam {
        _metadata {
          stringMetadata {
            name
            value
          }
        }
        teamFoundingDate
        description {
          json
        }
        teamMembers {
          fullName
          contactInfo {
            phone
            email
          }
          profilePicture {
            ... on ImageRef {
              _path
            }
          }
          instructorExperienceLevel
          skills
          biography {
            html
          }
        }
      }
      administrator {
        fullName
        contactInfo {
          phone
          email
        }
        biography {
          html
        }
      }
    }
    _references {
      ... on ImageRef {
        _path
        mimeType
      }
      ... on LocationModel {
        _path
        __typename
      }
    }
  }
}


# in Query Variables
{
  "slug": "yosemite-backpacking"
}

Enhorabuena.

¡Enhorabuena! Ahora ha probado las consultas avanzadas para recopilar datos de los fragmentos de contenido que creó en el capítulo anterior.

Pasos siguientes

En el capítulo siguiente, aprenderá a hacer que persistan las consultas de GraphQL y por qué es recomendable usar consultas persistentes en las aplicaciones.

recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4