Versão | Link do artigo |
---|---|
AEM as a Cloud Service | Clique aqui |
AEM 6.5 | 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 AEM.
A variável API HTTP de ativos abrange:
A implementação atual da API HTTP do Assets baseia-se na REST estilo arquitetônico.
A variável API REST de ativos O permite que os desenvolvedores do Adobe Experience Manager acessem o conteúdo (armazenado em 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 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.
Enquanto Componentes principais do AEM O fornece uma API muito abrangente, flexível e personalizável que pode atender às operações de Leitura necessárias para essa finalidade, e cuja saída em JSON pode ser personalizada, eles exigem o know-how AEM WCM (Web Content Management, Gerenciamento de conteúdo da Web) para implementação, pois devem ser hospedados em páginas baseadas 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.
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:
segue o Princípio do HATEOAS
implementa o Formato SIREN
A API REST do Assets está disponível em cada instalação pronta para uso de uma versão recente do AEM.
As ofertas da API REST do Assets RESTAcesso com estilo do aos ativos armazenados em uma instância do AEM.
Ele usa o /api/assets
ponto de extremidade e exige o caminho do ativo para acessá-lo (sem o ponto de extremidade /content/dam
).
/content/dam/path/to/asset
/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
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:
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 compatíveis é definido no Referência da API documentação.
Todas as solicitações são atômicas.
Isso significa que os subsequentes (write
) solicitações não podem ser combinadas em uma única transação que poderia ter êxito ou falhar como uma única entidade.
Aspecto | API REST de ativos |
Componente AEM (componentes que usam 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 Um caminho de exemplo seria semelhante a: |
Precisa ser referenciado por meio de um componente AEM em uma página AEM. Usa o Um caminho de exemplo seria semelhante a: |
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 endereça uma instância de autor. A leitura também pode ser direcionada a uma instância de publicação. |
Como essa abordagem é somente leitura, ela normalmente será usada para instâncias de publicação. |
Saída | Saída do SIREN baseada em JSON: detalhada, mas poderosa. 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). |
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.
Para obter mais informações, consulte:
Em ambientes com requisitos de autenticação específicos, o OAuth é recomendado.
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 é compatível com paginação (para solicitações GET) por meio dos parâmetros de URL:
offset
- o número da primeira entidade (secundária) a ser recuperadalimit
- o número máximo de entidades retornadasA resposta conterá informações de paginação como parte da variável properties
seção da saída SIREN. Este srn:paging
contém o número total de entidades (filhas) ( total
), o deslocamento e o limite ( offset
, limit
) conforme especificado na solicitação.
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.
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
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 etc. Os ativos são expostos como entidades filhas de pastas e subpastas.
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.
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
.
Os ativos podem 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"
).
A fragmento de conteúdo O é um tipo especial de ativo. Eles podem ser usados para acessar dados estruturados, como textos, números, datas, entre outros.
Uma vez que existem várias diferenças em padrão ativos (como imagens ou áudio), algumas regras adicionais se aplicam à sua manipulação.
Fragmentos de conteúdo:
Não exponha dados binários.
Estão completamente contidos na saída JSON (dentro do properties
propriedade).
Também são considerados atômicos, ou seja, os elementos e as variações são expostos como parte das propriedades do fragmento e não como links ou entidades filhas. Isso permite acesso eficiente à carga útil de um fragmento.
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, a consumidor precisa saber sobre o modelo de um fragmento (pelo menos um mínimo), embora a maioria das informações possa ser inferida a partir da carga, 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.
O conteúdo associado não está exposto no momento.
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.
É altamente recomendável que a criação esteja vinculada a uma instância de autor (e, no momento, não há como replicar um fragmento para publicar usando essa API).
A entrega é possível de ambos os ambientes, pois o AEM apresenta o conteúdo solicitado somente no formato JSON.
Armazenar e entregar a partir de uma instância de autor do AEM deve ser o suficiente para aplicativos de biblioteca de mídia por trás do firewall.
Para entrega em tempo real na web, recomenda-se uma instância de publicação do AEM.
A configuração do dispatcher em instâncias AEM pode bloquear o acesso a /api
.
Para obter mais detalhes, consulte Referência da API. Em especial, a seção API do Adobe Experience Manager Assets - Fragmentos de conteúdo.
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:
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
.
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.
O uso é feito via:
DELETE /{cfParentPath}/{cfName}
Existem algumas limitações:
Os seguintes códigos de status podem ser vistos nas circunstâncias relevantes:
200 (OK) Retornado quando:
GET
PUT
201 (Criado) Retornado quando:
POST
404 (Não encontrado) Retornado quando:
500 (Erro interno do servidor)
Esse erro é retornado:
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 via 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 geralmente 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}.."
}
}
Consulte esta página para obter referências detalhadas de API:
Para obter mais informações, consulte: