DocumentaçãoAEM as a Cloud ServiceGuia do usuário

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

Last update: Mon Nov 04 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Criado para:

  • Usuário
  • Administrador

Visão geral overview

Versão
Link do artigo
AEM 6.5
Clique aqui
AEM as a Cloud Service
Este artigo

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

NOTE
Consulte APIs de AEM para Entrega e Gerenciamento de Conteúdo Estruturado para obter uma visão geral das várias APIs disponíveis e uma comparação de alguns dos conceitos envolvidos.
As OpenAPIs de Fragmento de Conteúdo e de Modelo de Fragmento de Conteúdo também estão disponíveis.
NOTE
A API HTTP do Assets abrange:
  • API REST de ativos
  • incluindo suporte para fragmentos de conteúdo
A implementação atual da API HTTP do Assets é baseada no estilo de arquitetura REST.
NOTE
Para obter as informações mais recentes sobre as APIs Experience Manager, visite também as APIs Adobe Experience Manager as a Cloud Service.

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

A API permite operar o Adobe Experience Manager as a Cloud Service como um CMS headless (sistema de gerenciamento de conteúdo), 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, os 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 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. Isso ocorre porque eles devem ser hospedados em páginas baseadas em modelos de 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.

NOTE
Não é possível personalizar a saída JSON da API REST do Assets.

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 de ativos está disponível em cada instalação pronta para uso de versões recentes do Adobe Experience Manager as a Cloud Service.

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).

  • Isso significa que para acessar o ativo em:
    • /content/dam/path/to/asset
  • Solicitação:
    • /api/assets/path/to/asset

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

NOTE
O acesso por:
  • /api/assets não precisa da utilização do seletor .model.
  • /content/path/to/page precisa da utilização do seletor .model.

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

  • GET: para recuperar uma representação JSON de um ativo ou uma pasta
  • POST - para criar ativos ou pastas
  • PUT: para atualizar as propriedades de um ativo ou pasta
  • DELETE: para excluir um ativo ou pasta
NOTE
O corpo da solicitação e/ou os parâmetros de URL podem ser usados para configurar algumas dessas operações; por exemplo, definir que uma pasta ou um ativo deve ser criado por uma solicitação POST.

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

NOTE
As OpenAPIs de Fragmento de Conteúdo e de Modelo de Fragmento de Conteúdo também estão disponíveis.

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

Aspecto
API REST DO Assets
Componente de AEM
(componentes usando Modelos Sling)
Casos de uso compatíveis
Finalidade geral.

Otimizado para consumo em um Aplicativo de página única (SPA) ou em qualquer outro contexto (que consome conteúdo).

Ele 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

Ele pode ser acessado diretamente.

Usa o ponto de extremidade /api/assets , mapeado para /content/dam (no repositório).

Um caminho de exemplo seria semelhante a: /api/assets/wknd/en/adventures/cycling-tuscany.json

Ele deve ser referenciado por meio de um componente AEM em uma página AEM.

Usa o seletor .model para criar a representação JSON.

Um caminho de exemplo seria semelhante a:
/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json

Segurança

Várias opções são possíveis.

O OAuth é proposto; 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 aborda uma instância de Autor.

A leitura também pode ser direcionada a uma instância do Publish.

Como essa abordagem é somente leitura, ela geralmente é usada para instâncias do Publish.
Saída
Saída do SIREN baseada em JSON: detalhada, mas poderosa. Ela permite navegar dentro do conteúdo.
Saída proprietária baseada em JSON; configurável por meio de Modelos Sling. Navegar pela estrutura de conteúdo é difícil de implementar (mas não necessariamente impossível).

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 deverá ser configurado corretamente.

NOTE
Para obter mais informações, consulte:

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:

NOTE
As OpenAPIs de Fragmento de Conteúdo e de Modelo de Fragmento de Conteúdo também estão disponíveis.

Paginação paging

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

  • offset - o número da primeira entidade (filha) a ser recuperada
  • limit - o número máximo de entidades retornadas

A resposta contém 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.

NOTE
A paginação normalmente é aplicada em entidades de contêiner (ou seja, pastas ou ativos com representações), pois está relacionada aos filhos da entidade solicitada.

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 e título. Os Assets são expostos como entidades filhas de pastas e subpastas.

NOTE
Dependendo do tipo de ativo dos ativos e pastas secundários, a lista de entidades secundárias pode já conter o conjunto completo de propriedades que define a respectiva entidade secundária. Como alternativa, somente um conjunto reduzido de propriedades pode ser exposto para uma entidade nesta lista de entidades filhas.

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:

  • Não exponha dados binários.

  • Estão contidos na saída JSON (na propriedade properties ).

  • Eles também são considerados atômicos. Ou seja, os elementos e as variações são expostos como parte das propriedades do fragmento em vez de como links ou entidades filhas. Isso permite acesso eficiente à carga útil de um fragmento.

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 deve 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 é exposto.

Usar using

O uso pode variar dependendo se você está usando um autor de AEM ou um ambiente Publish, juntamente com o caso de uso específico.

  • Recomenda-se que a criação esteja associada a uma instância de Autor ( e, no momento, não há como replicar um fragmento para publicar usando esta API).

  • A entrega é possível de ambos os ambientes, pois o AEM apresenta o conteúdo solicitado somente no formato JSON.

    • O armazenamento e a entrega de uma instância de autor do AEM devem ser suficientes para aplicativos de biblioteca de mídia com firewall.

    • Para entrega na Web ao vivo, é recomendada uma instância de Publish do AEM.

CAUTION
A configuração do Dispatcher em instâncias da nuvem AEM pode bloquear o acesso a /api.
NOTE
Consulte a Referência da API. Em especial, a seção API do Adobe Experience Manager Assets - Fragmentos de conteúdo.
As OpenAPIs de Fragmento de Conteúdo e de Modelo de Fragmento de Conteúdo também estão disponíveis.

Limitações limitations

Existem algumas limitações:

  • Não há suporte no momento para modelos de fragmento de conteúdo: eles não podem ser lidos ou criados. Para criar ou atualizar um fragmento de conteúdo existente, os desenvolvedores precisam saber o caminho correto para o modelo do fragmento de conteúdo. Atualmente, o único método para obter uma visão geral é por meio da interface de administração.
  • Referências ignoradas. Atualmente, não há verificações sobre 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 contém uma referência ao fragmento de conteúdo excluído.
  • Tipo de dados JSON A saída da API REST do tipo de dados JSON é a saída baseada em cadeia de caracteres.

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:

  • 200 (OK)

    Retornado quando:

    • solicitando um fragmento de conteúdo por meio de GET
    • atualização bem-sucedida de um fragmento de conteúdo por meio de PUT

  • 201 (Criado)

    Retornado quando:

    • criação de fragmento de conteúdo bem-sucedida por meio de POST

  • 404 (Não encontrado)

    Retornado quando:

    • o fragmento de conteúdo solicitado não existe

  • 500 (Erro interno do servidor)

    note note
    NOTE
    Esse erro é retornado:
    • quando ocorreu um erro que não pode ser identificado com um código específico
    • quando a carga fornecida não era válida

    A seguir, há uma lista de cenários comuns em que esse status de erro é retornado, juntamente com a mensagem de erro (monospace) gerada:

    • A pasta primária não existe (ao criar um fragmento de conteúdo por meio de POST)

    • Nenhum modelo de fragmento de conteúdo foi fornecido (cq:model está ausente), não pode ser lido (devido a um caminho inválido ou um problema de permissão) ou não há um modelo de fragmento válido:

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

    • Não foi possível criar o fragmento de 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 os metadados:

      • Could not set metadata on content fragment

    • O elemento de conteúdo não pôde ser encontrado ou atualizado

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

    As mensagens de erro detalhadas são retornadas da seguinte maneira:

    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}.."
  }
}

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:

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