DocumentaciónAEM as a Cloud ServiceGuía del usuario

Compatibilidad con fragmentos de contenido en la API HTTP de AEM Assets content-fragments-support-in-aem-assets-http-api

Last update: Fri Nov 01 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creado para:

  • Usuario
  • Administrador

Información general overview

Versión
Vínculo del artículo
AEM 6.5
Haga clic aquí
AEM as a Cloud Service
Este artículo

Obtenga información acerca de la compatibilidad con fragmentos de contenido en la API HTTP de Assets, una parte importante de la función de entrega sin encabezado de Adobe Experience Manager AEM ().

NOTE
AEM Consulte API de para la administración y entrega de contenido estructurado para obtener una descripción general de las diversas API disponibles y una comparación de algunos de los conceptos involucrados.
Las OpenAPI de fragmento de contenido y modelo de fragmento de contenidos también están disponibles.
NOTE
La API HTTP de Assets incluye:
  • La API de REST de Recursos
  • incluye compatibilidad con los fragmentos de contenido
La implementación actual de la API HTTP de Assets se basa en el estilo de arquitectura REST.
NOTE
Para obtener la información más reciente sobre las API de Experience Manager, visita también API de Adobe Experience Manager as a Cloud Service.

La API de REST de Assets permite a los desarrolladores que Adobe Experience Manager as a Cloud Service AEM accedan al contenido (almacenado en el archivo de comandos) directamente a través de la API HTTP, mediante las operaciones CRUD (Crear, Leer, Actualizar, Eliminar).

La API le permite utilizar Adobe Experience Manager as a Cloud Service como CMS sin encabezado (sistema de administración de contenido) proporcionando servicios de contenido a una aplicación front-end de JavaScript. O cualquier otra aplicación que pueda ejecutar solicitudes HTTP y gestionar respuestas JSON.

SPA Por ejemplo, Aplicaciones de una sola página (), basadas en un marco de trabajo o personalizadas, requieren contenido proporcionado a través de la API HTTP, a menudo en formato JSON.

AEM AEM Aunque Componentes principales proporcionan una API personalizable que puede servir las operaciones de lectura necesarias para este fin y cuya salida JSON se puede personalizar, requieren conocimientos prácticos de WCM (Administración de contenido web) para la implementación de la. AEM Esto se debe a que deben alojarse en páginas basadas en plantillas de informes dedicadas a la. SPA No todas las organizaciones de desarrollo de la tienen acceso directo a esos conocimientos.

Es entonces cuando se puede utilizar la API de REST de Assets. Permite a los desarrolladores acceder a recursos (por ejemplo, imágenes y fragmentos de contenido) directamente, sin necesidad de incrustarlos primero en una página, y enviar su contenido en formato JSON serializado.

NOTE
No es posible personalizar la salida JSON desde la API de REST de Assets.

La API de REST de Assets también permite a los desarrolladores modificar contenido: creando nuevos recursos, fragmentos de contenido y carpetas, actualizándolos o eliminándolos.

La API de REST de Assets:

Requisitos previos prerequisites

La API de REST de Recursos está disponible en cada instalación predeterminada de una versión reciente de Adobe Experience Manager as a Cloud Service.

Conceptos clave key-concepts

La API de REST de Assets AEM ofrece acceso de tipo REST a los recursos almacenados en una instancia de la.

Utiliza el extremo /api/assets y requiere la ruta del recurso para acceder a él (sin el /content/dam inicial).

  • Esto significa que para acceder al recurso en:
    • /content/dam/path/to/asset
  • Solicitud:
    • /api/assets/path/to/asset

Por ejemplo, para acceder a /content/dam/wknd/en/adventures/cycling-tuscany, solicite /api/assets/wknd/en/adventures/cycling-tuscany.json

NOTE
Acceso:
  • /api/assets no necesita el uso del selector .model.
  • /content/path/to/page sí necesita el uso del selector .model.

El método HTTP determina la operación que se va a ejecutar:

  • GET: recuperar una representación JSON de un recurso o una carpeta.
  • POST: para crear recursos o carpetas
  • PUT: actualizar las propiedades de un recurso o carpeta.
  • DELETE: eliminar un recurso o carpeta.
NOTE
El cuerpo de solicitud o los parámetros de URL se pueden usar para configurar algunas de estas operaciones; por ejemplo, definir que una carpeta o un recurso deben crearse mediante una solicitud POST.

El formato exacto de las solicitudes admitidas se define en la Documentación de referencia de la API.

NOTE
Las OpenAPI de fragmento de contenido y modelo de fragmento de contenidos también están disponibles.

Comportamiento transaccional transactional-behavior

Todas las solicitudes son atómicas.

Esto significa que las solicitudes posteriores (write) no se pueden combinar en una sola transacción que se realice correctamente o que falle como una sola entidad.

AEM API de REST de (Assets AEM) frente a componentes de aem-assets-rest-api-versus-aem-components

Aspecto
API DE REST DE Assets
AEM Componente
(componentes que utilizan modelos Sling)
Casos de uso admitidos
De uso general.

SPA Optimizado para el consumo en una aplicación de una sola página () o en cualquier otro contexto (consumo de contenido).

También puede contener información de diseño.

Operaciones compatibles

Crear, leer, actualizar, eliminar.

Con operaciones adicionales, según el tipo de entidad.

Sólo lectura.
Acceso

Se puede acceder a ella directamente.

Utiliza el extremo /api/assets , asignado a /content/dam (en el repositorio).

Una ruta de ejemplo tendría este aspecto: /api/assets/wknd/en/adventures/cycling-tuscany.json

AEM AEM Se debe hacer referencia a él a través de un componente de la en una página de la aplicación.

Utiliza el selector .model para crear la representación JSON.

Una ruta de ejemplo tendría este aspecto:
/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json

Seguridad

Se pueden seleccionar varias opciones.

Se propone OAuth; se puede configurar por separado de la configuración estándar.

AEM Utiliza la configuración estándar de.
Observaciones arquitectónicas

El acceso de escritura suele dirigirse a una instancia de autor.

El contenido leído también se puede dirigir a una instancia de Publish.

Dado que este método es de solo lectura, generalmente se utiliza para instancias de Publish.
Salida
Salida SIREN basada en JSON: detallada, pero potente. Permite navegar dentro del contenido.
Salida propia basada en JSON; configurable mediante modelos Sling. La navegación por la estructura de contenido es difícil de implementar (pero no necesariamente imposible).

Seguridad security

Si la API de REST de Assets AEM se utiliza en un entorno sin requisitos de autenticación específicos, el filtro CORS debe configurarse correctamente para que se pueda usar el filtro CORS de forma correcta.

NOTE
Para obtener más información, consulte:

En entornos con requisitos de autenticación específicos, se recomienda OAuth.

Funciones disponibles available-features

Los fragmentos de contenido son un tipo específico de recurso. Consulte Uso de fragmentos de contenido.

Para obtener más información sobre las funciones disponibles a través de la API, consulte:

NOTE
Las OpenAPI de fragmento de contenido y modelo de fragmento de contenidos también están disponibles.

Paginación paging

La API de REST de Assets admite la paginación (para solicitudes de GET) mediante los parámetros de URL:

  • offset: el número de la primera entidad (secundaria) que se va a recuperar
  • limit: el número máximo de entidades devueltas

La respuesta contiene información de paginación como parte de la sección properties de la salida SIREN. Esta propiedad srn:paging contiene el número total de entidades (secundarias) ( total), el desplazamiento y el límite ( offset, limit) especificados en la solicitud.

NOTE
La paginación se aplica normalmente a entidades contenedoras (es decir, carpetas o activos con representaciones), en lo que se refiere a las tareas secundarias de la entidad solicitada.

Ejemplo: Paginación example-paging

GET /api/assets.json?offset=2&limit=3

...
"properties": {
    ...
    "srn:paging": {
        "total": 7,
        "offset": 2,
        "limit": 3
    }
    ...
}
...

Tipos de entidad entity-types

Carpetas folders

Las carpetas actúan como contenedores para recursos y otras carpetas. AEM Reflejan la estructura del repositorio de contenido de la.

La API de REST de Assets expone el acceso a las propiedades de una carpeta. Por ejemplo, su nombre y título. Assets se expone como entidades secundarias de carpetas y subcarpetas.

NOTE
Según el tipo de recurso de los recursos y carpetas secundarios, la lista de entidades secundarias puede contener ya el conjunto completo de propiedades que define la entidad secundaria correspondiente. Alternativamente, solo se puede exponer un conjunto reducido de propiedades para una entidad de esta lista de entidades secundarias.

Recursos assets

Si se solicita un recurso, la respuesta devolverá sus metadatos, como el título, el nombre y otra información tal como se define en el esquema de recursos correspondiente.

Los datos binarios de un recurso se exponen como un vínculo SIREN de tipo content.

Assets puede tener varias representaciones. Normalmente se exponen como entidades secundarias; una excepción es una representación en miniatura, que se expone como un vínculo de tipo thumbnail ( rel="thumbnail").

Fragmentos de contenido content-fragments

Un fragmento de contenido es un tipo especial de recurso. Pueden utilizarse para acceder a datos estructurados, como textos, números, fechas, etc.

Dado que existen varias diferencias entre los recursos estándar (como imágenes o audio), se aplican algunas reglas adicionales para administrarlos.

Representación representation

Fragmentos de contenido:

  • No exponga ningún dato binario.

  • Están contenidas en la salida JSON (dentro de la propiedad properties).

  • También se consideran atómicos. Es decir, los elementos y las variaciones se exponen como parte de las propiedades del fragmento en lugar de como vínculos o entidades secundarias. Esto permite un acceso eficiente a la carga útil de un fragmento.

Modelos de contenido y fragmentos de contenido content-models-and-content-fragments

Actualmente, los modelos que definen la estructura de un fragmento de contenido no se exponen a través de una API HTTP. Por lo tanto, consumer debe conocer el modelo de un fragmento (como mínimo), aunque la mayoría de la información se puede inferir de la carga útil, ya que los tipos de datos, etc., forman parte de la definición.

Para crear un fragmento de contenido, se debe proporcionar la ruta (del repositorio interno) del modelo.

Contenido asociado associated-content

El contenido asociado no se expone.

Utilización using

AEM El uso puede variar en función de si utiliza un entorno de autor o de Publish de, junto con el caso de uso específico.

  • Se recomienda que la creación esté enlazada a una instancia de autor ( y actualmente no hay medios para replicar un fragmento para publicarlo mediante esta API ().

  • La entrega es posible desde ambos, ya que AEM sirve contenido solicitado solo en formato JSON.

    • AEM El almacenamiento y el envío desde una instancia de autor de la deberían ser suficientes para las aplicaciones de biblioteca de medios detrás del cortafuegos.

    • AEM Para la entrega web en directo, se recomienda una instancia de Publish en la que se utilice un.

CAUTION
La configuración de Dispatcher AEM en instancias en la nube de podría bloquear el acceso a /api.
NOTE
Consulte la Referencia de API. En particular, la API de Adobe Experience Manager Assets: fragmentos de contenido.
Las OpenAPI de fragmento de contenido y modelo de fragmento de contenidos también están disponibles.

Limitaciones limitations

Hay algunas limitaciones:

  • Actualmente no se admiten los modelos de fragmento de contenido: no se pueden leer ni crear. Para poder crear o actualizar un fragmento de contenido existente, los desarrolladores deben conocer la ruta correcta al modelo de fragmento de contenido. Actualmente, el único método para obtener una descripción general de estos es a través de la IU de administración.
  • Se omiten las referencias. Actualmente no hay comprobaciones sobre si se hace referencia a un fragmento de contenido existente. Por lo tanto, por ejemplo, si elimina un fragmento de contenido, podrían producirse problemas en una página que contenga una referencia al fragmento de contenido eliminado.
  • Tipo de datos JSON La salida de la API de REST de tipo de datos JSON es salida basada en cadenas.

Códigos de estado y mensajes de error status-codes-and-error-messages

Los siguientes códigos de estado se pueden ver en las circunstancias relevantes:

  • 200 (OK)

    Devuelto cuando:

    • solicitando un fragmento de contenido mediante GET
    • se actualizó correctamente un fragmento de contenido mediante PUT

  • 201 (Creado)

    Devuelto cuando:

    • se creó correctamente un fragmento de contenido mediante POST

  • 404 (no encontrado)

    Devuelto cuando:

    • el fragmento de contenido solicitado no existe

  • 500 (error interno del servidor)

    note note
    NOTE
    Se devuelve este error:
    • cuando se ha producido un error que no se puede identificar con un código específico
    • cuando la carga útil proporcionada no era válida

    A continuación se enumeran los escenarios comunes en los que se devuelve este estado de error, junto con el mensaje de error (monoespacio) generado:

    • La carpeta principal no existe (al crear un fragmento de contenido mediante POST)

    • No se ha proporcionado ningún modelo de fragmento de contenido (falta cq:model), no se puede leer (debido a una ruta no válida o a un problema de permisos) o no hay ningún modelo de fragmento válido:

      • No content fragment model specified
      • Cannot create a resource of given model '/foo/bar/qux'

    • No se ha podido crear el fragmento de contenido (potencialmente un problema de permisos):

      • Could not create content fragment

    • No se han podido actualizar el título o la descripción:

      • Could not set value on content fragment

    • No se pudieron establecer los metadatos:

      • Could not set metadata on content fragment

    • El elemento de contenido no se ha podido encontrar o actualizar

      • Could not update content element
      • Could not update fragment data of element

    Los mensajes de error detallados se devuelven de la siguiente manera:

    code language-xml 
    {
  "class": "core/response",
  "properties": {
    "path": "/api/assets/foo/bar/qux",
    "location": "/api/assets/foo/bar/qux.json",
    "parentLocation": "/api/assets/foo/bar.json",
    "status.code": 500,
    "status.message": "...{error message}.."
  }
}

Referencia de la API api-reference

Consulte aquí las referencias detalladas de la API:

Recursos adicionales additional-resources

Para obtener más información, consulte lo siguiente:

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab