Suporte a fragmentos de conteúdo na API HTTP do AEM Assets content-fragments-support-in-aem-assets-http-api

Visão geral overview

Saiba mais sobre o suporte a Fragmentos de conteúdo na API HTTP do Assets, uma parte importante do recurso de entrega headless do AEM.

A API REST do Assets permite que os desenvolvedores do Adobe Experience Manager acessem o conteúdo (armazenado no AEM) diretamente pela API HTTP, por meio de operações CRUD (Criar, Ler, Atualizar, Excluir).

A API permite operar o Adobe Experience Manager como um CMS (Content Management System, Sistema de gerenciamento de conteúdo) headless, fornecendo serviços de conteúdo a um aplicativo front-end do JavaScript. Ou qualquer outro aplicativo que possa executar solicitações HTTP e manipular respostas JSON.

Por exemplo, Aplicativos de página única (SPA), baseados em estrutura ou personalizados, exigem conteúdo fornecido pela API HTTP, geralmente no formato JSON.

Embora os Componentes principais do AEM forneçam uma API muito abrangente, flexível e personalizável que possa atender às operações de Leitura necessárias para essa finalidade, e cuja saída em JSON possa ser personalizada, eles exigem o know-how AEM WCM (Web Content Management) para implementação, pois devem ser hospedados em páginas que se baseiam em modelos AEM dedicados. Nem todas as organizações de desenvolvimento de SPA têm acesso direto a esse conhecimento.

É quando a API REST do Assets pode ser usada. Ele permite que os desenvolvedores acessem ativos (por exemplo, imagens e fragmentos de conteúdo) diretamente, sem a necessidade de primeiro incorporá-los em uma página e entregar seu conteúdo no formato JSON serializado.

A API REST do Assets também permite que os desenvolvedores modifiquem o conteúdo, criando novos ativos, atualizando ou excluindo ativos, fragmentos de conteúdo e pastas existentes.

A API REST do Assets:

Pré-requisitos prerequisites

A API REST do Assets está disponível em cada instalação pronta para uso de uma versão recente do AEM.

Principais conceitos key-concepts

A API REST do Assets oferece acesso com estilo REST a ativos armazenados em uma instância AEM.

Ele usa o ponto de extremidade /api/assets e requer o caminho do ativo para acessá-lo (sem o /content/dam principal).

Por exemplo, para acessar /content/dam/wknd/en/adventures/cycling-tuscany, solicite /api/assets/wknd/en/adventures/cycling-tuscany.json

O método HTTP determina a operação a ser executada:

O formato exato das solicitações com suporte está definido na documentação da Referência de API.

Comportamento transacional transactional-behavior

Todas as solicitações são atômicas.

Isso significa que solicitações subsequentes (write) não podem ser combinadas em uma única transação que poderia ter êxito ou falhar como uma única entidade.

API REST do AEM (Assets) versus Componentes do AEM aem-assets-rest-api-versus-aem-components

Segurança security

Se a API REST do Assets for usada em um ambiente sem requisitos de autenticação específicos, o filtro CORS do AEM precisará ser configurado corretamente.

Em ambientes com requisitos de autenticação específicos, o OAuth é recomendado.

Recursos disponíveis available-features

Fragmentos de conteúdo são um tipo específico de ativo. Consulte Trabalho com fragmentos de conteúdo.

Para obter mais informações sobre os recursos disponíveis por meio da API, consulte:

Paginação paging

A API REST do Assets oferece suporte à paginação (para solicitações GET) por meio dos parâmetros de URL:

A resposta conterá informações de paginação como parte da seção properties da saída SIREN. Esta propriedade srn:paging contém o número total de entidades (filhas) ( total), o deslocamento e o limite ( offset, limit) conforme especificado na solicitação.

Exemplo: Paginação example-paging

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

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

Tipos de entidade entity-types

Pastas folders

As pastas atuam como containers para ativos e outras pastas. Elas refletem a estrutura do repositório de conteúdo do AEM.

A API REST do Assets expõe o acesso às propriedades de uma pasta; por exemplo, seu nome, título e assim por diante. O Assets é exposto como entidades filhas de pastas e subpastas.

Ativos assets

Se um ativo for solicitado, a resposta retornará seus metadados; como título, nome e outras informações conforme definido pelo respectivo esquema de ativo.

Os dados binários de um ativo são expostos como um link SIREN do tipo content.

O Assets pode ter várias representações. Normalmente, elas são expostas como entidades filhas, com uma exceção sendo uma representação em miniatura, que é exposta como um link do tipo thumbnail ( rel="thumbnail").

Fragmentos de conteúdo content-fragments

Um fragmento de conteúdo é um tipo especial de ativo. Eles podem ser usados para acessar dados estruturados, como textos, números, datas, entre outros.

Como há várias diferenças em relação aos ativos padrão (como imagens ou áudio), algumas regras adicionais se aplicam à sua manipulação.

Representação representation

Fragmentos de conteúdo:

Modelos de conteúdo e fragmentos de conteúdo content-models-and-content-fragments

Atualmente, os modelos que definem a estrutura de um fragmento de conteúdo não são expostos por meio de uma API HTTP. Portanto, o consumidor precisa saber sobre o modelo de um fragmento (pelo menos um mínimo), embora a maioria das informações possa ser inferida da carga, como tipos de dados e assim por diante. fazem parte da definição.

Para criar um fragmento de conteúdo, o caminho (repositório interno) do modelo deve ser fornecido.

Conteúdo associado associated-content

O conteúdo associado não está exposto no momento.

Usar using

O uso pode ser diferente dependendo se você está usando um ambiente de autor ou de publicação no AEM, juntamente com seu caso de uso específico.

Leitura/entrega read-delivery

O uso é feito via:

GET /{cfParentPath}/{cfName}.json

Por exemplo:

http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json

A resposta é em JSON serializado e o conteúdo é estruturado de acordo com o fragmento de conteúdo. As referências são fornecidas como URLs de referência.

Dois tipos de operações de leitura são possíveis:

Criar create

O uso é feito via:

POST /{cfParentPath}/{cfName}

O corpo deve conter uma representação JSON do fragmento de conteúdo a ser criado, incluindo qualquer conteúdo inicial que deve ser definido nos elementos do fragmento de conteúdo. É obrigatório definir a propriedade cq:model e ela deve apontar para um modelo de fragmento de conteúdo válido. Se isso não for feito, haverá um erro. Também é necessário adicionar um cabeçalho Content-Type definido como application/json.

Atualizar o update

O uso é feito via

PUT /{cfParentPath}/{cfName}

O corpo deve conter uma representação JSON referente ao que deve ser atualizado para o fragmento de conteúdo especificado.

Isso pode ser simplesmente o título ou a descrição de um fragmento de conteúdo, um único elemento ou todos os valores e/ou metadados do elemento.

Excluir delete

O uso é feito via:

DELETE /{cfParentPath}/{cfName}

Limitações limitations

Existem algumas limitações:

Códigos de status e mensagens de erro status-codes-and-error-messages

Os seguintes códigos de status podem ser vistos nas circunstâncias relevantes:

Referência da API api-reference

Consulte esta página para obter referências detalhadas de API:

Recursos adicionais additional-resources

Para obter mais informações, consulte: