Show Menu
TÓPICOS×

Suporte a fragmentos de conteúdo na API HTTP do AEM Assets

Visão geral

A API HTTP Assets engloba:
  • API REST de ativos
  • incluindo suporte para fragmentos de conteúdo
A implementação atual da API HTTP Assets baseia-se no estilo de arquitetura REST .
A API REST de ativos permite que os desenvolvedores do Adobe Experience Manager como um serviço em nuvem acessem o conteúdo (armazenado no AEM) diretamente pela API HTTP, por meio de operações CRUD (Criar, Ler, Atualizar, Excluir).
A API permite que você opere o Adobe Experience Manager como um serviço em nuvem como um CMS (Sistema de Gestão de conteúdo) sem cabeçalho, fornecendo Serviços de conteúdo a um aplicativo front-end 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 ofereçam uma API abrangente, flexível e personalizável que possa servir as operações de Leitura necessárias para essa finalidade, e cuja saída JSON possa ser personalizada, eles exigem o know-how WCM do AEM (Gestão de conteúdo da Web) para implementação, pois devem ser hospedados em páginas baseadas em modelos dedicados do AEM. Nem todas as organizações de desenvolvimento da ZPE têm acesso direto a esses conhecimentos.
É quando a API REST de ativos pode ser usada. Ela 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 em formato JSON serializado.
Não é possível personalizar a saída JSON da API REST de ativos.
A API REST de ativos 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 de ativos:

Pré-requisitos

A API REST de ativos está disponível em cada instalação predefinida de uma versão recente do Adobe Experience Manager como uma versão do Cloud Service.

Principais conceitos

A API REST de ativos oferta o acesso ao estilo REST a ativos armazenados em uma instância do AEM.
Ele usa o /api/assets terminal e exige que o caminho do ativo acesse-o (sem o pontilhado /content/dam ).
  • Isso significa que para acessar o ativo em:
    • /content/dam/path/to/asset
  • Você precisa solicitar:
    • /api/assets/path/to/asset
Por exemplo, para acessar /content/dam/wknd/en/adventures/cycling-tuscany , solicitar /api/assets/wknd/en/adventures/cycling-tuscany.json
Acesso através de:
  • /api/assets não precisa do uso do .model seletor.
  • /content/assets requer o uso do .model seletor.
O método HTTP determina a operação a ser executada:
  • GET - para recuperar uma representação JSON de um ativo ou pasta
  • POST - para criar novos ativos ou pastas
  • PUT - para atualizar as propriedades de um ativo ou pasta
  • EXCLUIR - para excluir um ativo ou pasta
Os parâmetros do corpo da solicitação e/ou URL podem ser usados para configurar algumas dessas operações; por exemplo, defina que uma pasta ou um ativo deve ser criado por uma solicitação POST .

Comportamento transacional

Todas as solicitações são atômicas.
Isso significa que as solicitações subsequentes ( write ) não podem ser combinadas em uma única transação que pode ser bem-sucedida ou falhar como uma única entidade.

API REST do AEM (Assets) versus componentes do AEM

Aspecto API REST de ativos Componente AEM (componentes usando modelos Sling)
Casos de uso suportados Finalidade geral.
Otimizado para consumo em um aplicativo de página única (SPA) ou em qualquer outro contexto (que consome conteúdo).
Também pode conter informações de layout.
Operações suportadas
Criar, Ler, Atualizar, Excluir.
Com operações adicionais, dependendo do tipo de entidade.
Somente leitura.
Acesso
Pode ser acessado diretamente.
Usa o /api/assets terminal, mapeado para /content/dam (no repositório).
Um caminho de exemplo seria: /api/assets/wknd/en/adventures/cycling-tuscany.json
Precisa ser referenciado por meio de um componente AEM em uma página do AEM.
Usa o .model seletor para criar a representação JSON.
Um caminho de exemplo seria: /content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
Segurança
Várias opções são possíveis.
É proposta a OAuth; pode ser configurado separadamente da configuração padrão.
Usa a configuração padrão do AEM.
Observações arquitetônicas
O acesso de gravação normalmente endereçará uma instância do autor.
A leitura também pode ser direcionada para uma instância de publicação.
Como essa abordagem é somente leitura, normalmente será usada para instâncias de publicação.
Saída Saída SIREN baseada em JSON: profundo, mas poderoso. Permite navegar dentro do conteúdo. Saída proprietária baseada em JSON; configurável por meio de modelos Sling. É difícil implementar a navegação na estrutura de conteúdo (mas não é necessariamente impossível).

Segurança

Se a API REST de ativos for usada dentro de um ambiente sem requisitos específicos de autenticação, o filtro CORS do AEM precisará ser configurado corretamente.
Em ambientes com requisitos de autenticação específicos, o OAuth é recomendado.

Recursos disponíveis

Fragmentos de conteúdo são um tipo específico de Ativo, consulte Trabalhar com fragmentos de conteúdo.
Para obter mais informações sobre os recursos disponíveis por meio da API, consulte:
  • A API REST do Assets
  • Tipos de entidade, onde os recursos específicos para cada tipo suportado (conforme relevante para Fragmentos de conteúdo) são explicados

Paginação

A API REST de ativos suporta paginação (para solicitações GET) pelos parâmetros de URL:
  • offset - o número da primeira entidade (filho) a recuperar
  • limit - o número máximo de entidades devolvidas
A resposta conterá informações de paginação como parte da properties seção da saída SIREN. Essa srn:paging propriedade contém o número total de entidades (filhas) ( total ), o deslocamento e o limite ( offset , limit ) conforme especificado na solicitação.
O paginação normalmente é aplicado em entidades de container (ou seja, pastas ou ativos com renderizações), pois está relacionado aos filhos da entidade solicitada.

Exemplo: Paginação

GET /api/assets.json?offset=2&limit=3
...
"properties": {
    ...
    "srn:paging": {
        "total": 7,
        "offset": 2,
        "limit": 3
    }
    ...
}
...

Tipos de entidade

Pastas

As pastas atuam como container para ativos e outras pastas. Elas refletem a estrutura do repositório de conteúdo do AEM.
A API REST de ativos expõe o acesso às propriedades de uma pasta; por exemplo, seu nome, título etc. Os ativos são expostos como entidades filhas de pastas e subpastas.
Dependendo do tipo de ativo dos ativos e pastas filho, a lista de entidades filhas já pode conter o conjunto completo de propriedades que define a respectiva entidade-filho. Como alternativa, apenas um conjunto reduzido de propriedades pode ser exposto para uma entidade nesta lista de entidades-filho.

Ativos

Se um ativo for solicitado, a resposta retornará seus metadados; como título, nome e outras informações, conforme definido pelo respectivo schema de ativos.
Os dados binários de um ativo são expostos como um link SIREN do tipo content (também conhecido como o rel attribute ).
Os ativos podem ter várias representações. Normalmente, são expostos como entidades filhas, uma exceção é uma execução em miniatura, que é exposta como um link do tipo thumbnail ( rel="thumbnail" ).

Fragmentos de conteúdo

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 nos ativos padrão (como imagens ou áudio), algumas regras adicionais se aplicam ao seu manuseio.

Representação

Fragmentos de conteúdo:
  • Não exponha quaisquer dados binários.
  • Estão completamente contidos na saída JSON (dentro da properties propriedade).
  • Também são considerados atômicos, ou seja, os elementos e variações são expostos como parte das propriedades do fragmento vs. como links ou entidades filhas. Isso permite um acesso eficiente à carga de um fragmento.

Modelos de conteúdo e fragmentos de conteúdo

Atualmente, os modelos que definem a estrutura de um fragmento de conteúdo não são expostos por meio de uma API HTTP. Por conseguinte, o consumidor precisa de conhecer o modelo de um fragmento (pelo menos um mínimo) - embora a maior parte das informações possa ser inferida a partir da carga útil; como tipos de dados, etc. fazem parte da definição.
Para criar um novo fragmento de conteúdo, o caminho (repositório interno) do modelo deve ser fornecido.

Conteúdo associado

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

Usar

O uso pode ser diferente se você estiver usando um autor ou ambiente de publicação do AEM, juntamente com seu caso de uso específico.
  • A criação é estritamente vinculada a uma instância do autor ( e atualmente não há como replicar um fragmento para publicação usando essa API ).
  • O Delivery é possível de ambos, pois o AEM serve o conteúdo solicitado somente no formato JSON.
    • O Armazenamento e o delivery de uma instância de autor de AEM devem ser suficientes para aplicativos de biblioteca de mídia atrás do firewall.
    • Para o delivery online ao vivo, uma instância de publicação do AEM é recomendada.
A configuração do dispatcher em instâncias da nuvem do AEM pode bloquear o acesso ao /api .

Leitura/Delivery

O uso é feito via:
GET /{cfParentPath}/{cfName}.json
Por exemplo:
http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json
A resposta é JSON serializado com o conteúdo estruturado como no fragmento de conteúdo. As referências são enviadas como URLs de referência.
Dois tipos de operações de leitura são possíveis:
  • Ao ler um fragmento de conteúdo específico por caminho, isso retorna a representação JSON do fragmento de conteúdo.
  • Leitura de uma pasta de fragmentos de conteúdo por caminho: isso retorna as representações JSON de todos os fragmentos de conteúdo dentro da pasta.

Criar

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 cq:model propriedade e deve apontar para um modelo de fragmento de conteúdo válido. Se isso não for feito, ocorrerá um erro. Também é necessário adicionar um cabeçalho Content-Type definido como application/json .

Atualizar

O uso é via
PUT /{cfParentPath}/{cfName}
O corpo deve conter uma representação JSON do que deve ser atualizado para o fragmento de conteúdo fornecido.
Pode ser simplesmente o título ou a descrição de um fragmento de conteúdo, um único elemento ou todos os valores de elementos e/ou metadados.

Exclua

O uso é feito via:
DELETE /{cfParentPath}/{cfName}

Limitações

Há algumas limitações:
  • As variações não podem ser gravadas e atualizadas. Se essas variações forem adicionadas a uma carga (por exemplo, para atualizações), elas serão ignoradas. No entanto, a variação será servida através do delivery ( GET ).
  • Os modelos de fragmento de conteúdo não são suportados no momento: eles não podem ser lidos ou criados. Para poder criar um novo fragmento de conteúdo ou atualizar um existente, os desenvolvedores precisam saber o caminho correto para o modelo de fragmento de conteúdo. Atualmente, o único método para obter uma visão geral desses recursos é por meio da interface de usuário administrativa.
  • As referências são ignoradas . Atualmente, não há verificações para determinar se um fragmento de conteúdo existente é referenciado. Portanto, por exemplo, excluir um fragmento de conteúdo pode resultar em problemas em uma página que contenha uma referência ao fragmento de conteúdo excluído.

Códigos de status e mensagens de erro

Os seguintes códigos de status podem ser vistos nas circunstâncias relevantes:
  1. 200 (OK)
    Retornado quando:
    • solicitação de um fragmento de conteúdo via GET
    • atualização bem-sucedida de um fragmento de conteúdo por meio de PUT
  2. 201 (Criado)
    Retornado quando:
    • criação de um fragmento de conteúdo por meio de POST
  3. 404 (Não encontrado)
    Retornado quando:
    • o fragmento de conteúdo solicitado não existe
  4. 500 (Erro interno do servidor)
    Este erro é retornado:
    • quando um erro que não pode ser identificado com um código específico tiver ocorrido
    • quando a carga fornecida não era válida
    O seguinte lista cenários comuns quando esse status de erro é retornado, juntamente com a mensagem de erro (monospace) gerada:
    • A pasta pai não existe (ao criar um fragmento de conteúdo via POST )
    • Nenhum modelo de fragmento de conteúdo é fornecido (cq:model está ausente), não pode ser lido (devido a um caminho inválido ou a um problema de permissão) ou não há modelo/modelo de fragmento válido:
      • No content fragment model specified
      • Cannot create a resource of given model '/foo/bar/qux'
      • Cannot adapt the resource '/foo/bar/qux' to a content fragment template
    • Não foi possível criar o fragmento do conteúdo (possivelmente um problema de permissão):
      • Could not create content fragment
    • Não foi possível atualizar o título e/ou a descrição:
      • Could not set value on content fragment
    • Não foi possível definir metadados:
      • Could not set metadata on content fragment
    • O elemento de conteúdo não foi encontrado ou não pôde ser atualizado
      • Could not update content element
      • Could not update fragment data of element
    As mensagens de erro detalhadas normalmente são retornadas da seguinte maneira:
    {
      "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}.."
      }
    }
    
    

API Reference

Consulte aqui para obter referências detalhadas da API:

Recursos adicionais

Para obter mais informações, consulte: