Versione | Collegamento articolo |
---|---|
AEM as a Cloud Service | Fai clic qui |
AEM 6.5 | Questo articolo |
Scopri il supporto per i frammenti di contenuto nell’API HTTP di Assets, una funzione importante AEM consegna headless.
La API HTTP di Assets comprende:
L’implementazione corrente dell’API HTTP Assets si basa sul REST stile architettonico.
La API REST di Assets consente agli sviluppatori di Adobe Experience Manager di accedere ai contenuti (memorizzati in AEM) direttamente tramite l’API HTTP tramite operazioni CRUD (Crea, Leggi, Aggiorna, Elimina).
L’API ti consente di utilizzare Adobe Experience Manager come CMS headless (Content Management System) fornendo servizi per contenuti a un’applicazione front-end JavaScript. O qualsiasi altra applicazione in grado di eseguire richieste HTTP e gestire risposte JSON.
Ad esempio, le applicazioni a pagina singola (SPA), basate su framework o personalizzate, richiedono il contenuto fornito tramite l’API HTTP, spesso in formato JSON.
Quando Componenti core AEM fornisce un’API molto completa, flessibile e personalizzabile che può servire le operazioni di lettura necessarie a questo scopo e il cui output JSON può essere personalizzato, richiedono AEM know-how WCM (Web Content Management) per l’implementazione, in quanto devono essere ospitati in pagine basate su modelli AEM dedicati. Non tutte le SPA organizzazioni di sviluppo hanno accesso diretto a tali conoscenze.
Questo è il momento in cui è possibile utilizzare l’API REST di Assets. Consente agli sviluppatori di accedere direttamente alle risorse (ad esempio, immagini e frammenti di contenuto) senza dover prima incorporarle in una pagina e consegnare il contenuto in formato JSON serializzato.
Non è possibile personalizzare l’output JSON dall’API REST di Assets.
L’API REST di Assets consente inoltre agli sviluppatori di modificare il contenuto creando nuove risorse, aggiornando o eliminando risorse esistenti, frammenti di contenuto e cartelle.
API REST di Assets:
segue Principio delle HATEOAS
implementa Formato SIREN
L’API REST di Assets è disponibile per ogni installazione predefinita di una versione di AEM recente.
Le offerte API REST di Assets RESTAccesso in stile -style alle risorse memorizzate all’interno di un’istanza AEM.
Utilizza il /api/assets
e richiede il percorso della risorsa per accedervi (senza l’iniziale /content/dam
).
/content/dam/path/to/asset
/api/assets/path/to/asset
Ad esempio, per accedere a /content/dam/wknd/en/adventures/cycling-tuscany
, richiesta /api/assets/wknd/en/adventures/cycling-tuscany.json
Accedere a:
/api/assets
non l'uso .model
selettore./content/path/to/page
does richiedere l'uso .model
selettore.Il metodo HTTP determina l'operazione da eseguire:
Il corpo della richiesta e/o i parametri URL possono essere utilizzati per configurare alcune di queste operazioni; ad esempio, definisci che una cartella o una risorsa debba essere creata da un POST richiesta.
Il formato esatto delle richieste supportate è definito nella Riferimento API documentazione.
Tutte le richieste sono atomiche.
Ciò significa che il successivo (write
Le richieste ) non possono essere combinate in una singola transazione che potrebbe avere esito positivo o negativo come singola entità.
Aspetto | API REST di Assets |
Componente AEM (componenti che utilizzano modelli Sling) |
Casi d’uso supportati | Scopo generale. | Ottimizzato per il consumo in applicazioni a pagina singola (SPA) o in qualsiasi altro contesto (che consuma contenuti). Può anche contenere informazioni sul layout. |
Operazioni supportate | Crea, Leggi, Aggiorna, Elimina. Con operazioni aggiuntive a seconda del tipo di entità. |
Sola lettura. |
Accesso | È accessibile direttamente. Utilizza il Un esempio di percorso potrebbe essere: |
Deve essere fatto riferimento tramite un componente AEM in una pagina AEM. Utilizza il Un esempio di percorso potrebbe essere: |
Sicurezza | Sono possibili più opzioni. è proposta l’OAuth; può essere configurato separatamente dalla configurazione standard. |
Utilizza AEM configurazione standard. |
Osservazioni architettoniche | L'accesso in scrittura si rivolge in genere a un'istanza dell'autore. La lettura può anche essere diretta a un'istanza di pubblicazione. |
Poiché questo approccio è di sola lettura, in genere viene utilizzato per le istanze di pubblicazione. |
Output | Output SIREN basato su JSON: verboso, ma potente. Consente di spostarsi all’interno del contenuto. | output proprietario basato su JSON; configurabile tramite modelli Sling. La navigazione nella struttura dei contenuti è difficile da implementare (ma non necessariamente impossibile). |
Se l’API REST di Assets viene utilizzata in un ambiente senza requisiti di autenticazione specifici, AEM filtro CORS deve essere configurato correttamente.
Per ulteriori informazioni, consulta:
In ambienti con requisiti di autenticazione specifici, si consiglia OAuth.
I frammenti di contenuto sono un tipo specifico di risorsa, consulta Utilizzo dei frammenti di contenuto.
Per ulteriori informazioni sulle funzioni disponibili tramite API, consulta:
L’API REST di Assets supporta il paging (per richieste GET) tramite i parametri URL:
offset
- il numero della prima entità (figlio) da recuperarelimit
- il numero massimo di entità restituiteLa risposta conterrà informazioni di paging come parte del properties
sezione dell'uscita SIREN. Questo srn:paging
contiene il numero totale di entità (secondarie) ( total
), l'offset e il limite ( offset
, limit
) come specificato nella richiesta.
La paging viene in genere applicata alle entità contenitore (ovvero cartelle o risorse con rendering), in quanto si riferisce agli elementi secondari dell’entità richiesta.
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
Le cartelle fungono da contenitori per risorse e altre cartelle. Essi riflettono la struttura dell’archivio dei contenuti AEM.
L’API REST di Assets espone l’accesso alle proprietà di una cartella; ad esempio nome, titolo, ecc. Le risorse vengono esposte come entità secondarie di cartelle e sottocartelle.
A seconda del tipo di risorsa delle risorse e delle cartelle secondarie, l’elenco delle entità figlio può già contenere l’intero set di proprietà che definisce la rispettiva entità figlio. In alternativa, solo un set ridotto di proprietà può essere esposto per un’entità in questo elenco di entità figlio.
Se viene richiesta una risorsa, la risposta restituirà i relativi metadati; quali titolo, nome e altre informazioni definite dal rispettivo schema di risorse.
I dati binari di una risorsa sono esposti come collegamento SIREN di tipo content
.
Le risorse possono avere più rappresentazioni. Questi sono generalmente esposti come entità secondarie, una delle quali è un rendering di miniature, che è esposto come collegamento di tipo thumbnail
( rel="thumbnail"
).
A frammento di contenuto è un tipo speciale di risorsa. Possono essere utilizzati per accedere a dati strutturati, quali testi, numeri, date, ecc.
Poiché esistono diverse differenze tra standard risorse (come immagini o audio), sono applicabili alcune regole aggiuntive per gestirle.
Frammenti di contenuto:
Non esporre dati binari.
Sono completamente contenuti nell’output JSON (all’interno di properties
proprietà).
Sono anche considerate atomiche, ovvero gli elementi e le varianti sono esposti come parte delle proprietà del frammento rispetto a come collegamenti o entità secondarie. Ciò consente un accesso efficiente al payload di un frammento.
Attualmente i modelli che definiscono la struttura di un frammento di contenuto non sono esposti tramite un’API HTTP. Pertanto, consumer deve conoscere il modello di un frammento (almeno un minimo), anche se la maggior parte delle informazioni può essere dedotta dal payload; come tipi di dati, ecc. fanno parte della definizione.
Per creare un nuovo frammento di contenuto, è necessario fornire il percorso (archivio interno) del modello.
Il contenuto associato non è attualmente esposto.
L’utilizzo può variare a seconda che utilizzi un ambiente di authoring o pubblicazione AEM e del tuo caso d’uso specifico.
Si consiglia vivamente di associare la creazione a un’istanza di authoring (e al momento non esiste alcun modo per replicare un frammento da pubblicare utilizzando questa API).
La consegna è possibile da entrambi, in quanto AEM il contenuto richiesto solo in formato JSON.
L'archiviazione e la consegna da un'istanza di authoring AEM dovrebbero essere sufficienti per le applicazioni di librerie multimediali dietro il firewall.
Per la distribuzione web live, si consiglia un’istanza di pubblicazione AEM.
La configurazione del dispatcher su AEM istanze potrebbe bloccare l’accesso a /api
.
Per ulteriori dettagli, consulta la sezione Riferimento API. In particolare, API di Adobe Experience Manager Assets - Frammenti di contenuto.
L’utilizzo avviene tramite:
GET /{cfParentPath}/{cfName}.json
Esempio:
http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json
La risposta viene serializzata JSON con il contenuto strutturato come nel frammento di contenuto. I riferimenti vengono consegnati come URL di riferimento.
Sono possibili due tipi di operazioni di lettura:
L’utilizzo avviene tramite:
POST /{cfParentPath}/{cfName}
Il corpo deve contenere una rappresentazione JSON del frammento di contenuto da creare, incluso qualsiasi contenuto iniziale da impostare sugli elementi del frammento di contenuto. È obbligatorio impostare il cq:model
e deve puntare a un modello di frammento di contenuto valido. In caso contrario si verifica un errore. È inoltre necessario aggiungere un’intestazione Content-Type
che è impostato su application/json
.
Utilizzo tramite
PUT /{cfParentPath}/{cfName}
Il corpo deve contenere una rappresentazione JSON di ciò che deve essere aggiornato per il frammento di contenuto specificato.
Può trattarsi semplicemente del titolo o della descrizione di un frammento di contenuto, di un singolo elemento o di tutti i valori e/o metadati degli elementi.
L’utilizzo avviene tramite:
DELETE /{cfParentPath}/{cfName}
Ci sono alcune limitazioni:
I seguenti codici di stato possono essere visti nelle circostanze pertinenti:
200 (OK) Restituito quando:
GET
PUT
201 (Creato) Restituito quando:
POST
404 (Non trovato) Restituito quando:
500 (Errore interno del server)
Questo errore viene restituito:
Di seguito sono elencati gli scenari comuni in cui viene restituito questo stato di errore, insieme al messaggio di errore (monospazio) generato:
La cartella principale non esiste (durante la creazione di un frammento di contenuto tramite POST
)
Non viene fornito alcun modello di frammento di contenuto (cq:model mancante), non può essere letto (a causa di un percorso non valido o di un problema di autorizzazione) o non è disponibile un modello di frammento valido:
No content fragment model specified
Cannot create a resource of given model '/foo/bar/qux'
Impossibile creare il frammento di contenuto (potenzialmente un problema di autorizzazione):
Could not create content fragment
Impossibile aggiornare il titolo e la descrizione:
Could not set value on content fragment
Impossibile impostare i metadati:
Could not set metadata on content fragment
Impossibile trovare l'elemento contenuto o aggiornarlo
Could not update content element
Could not update fragment data of element
I messaggi di errore dettagliati vengono in genere restituiti nel modo seguente:
{
"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}.."
}
}
Vedi qui per riferimenti API dettagliati:
Per ulteriori informazioni, consulta: