Richiama le API AEM basate su OpenAPI utilizzando l’autenticazione server-to-server OAuth
- Si applica a:
- Experience Manager as a Cloud Service
- Argomenti:
- Sviluppo
Creato per:
- Principiante
- Sviluppatore
- Leader
Scopri come richiamare le API AEM basate su OpenAPI su AEM as a Cloud Service da applicazioni personalizzate utilizzando l’autenticazione OAuth Server-to-Server.
L’autenticazione server-to-server di OAuth è ideale per i servizi back-end che richiedono l’accesso API senza l’interazione dell’utente. Utilizza il tipo di sovvenzione OAuth 2.0 client_credentials per autenticare l'applicazione client.
Argomenti trattati
In questo tutorial imparerai a:
-
Configura un progetto Adobe Developer Console (ADC) per accedere all'API di authoring di Assets utilizzando Autenticazione server-to-server OAuth.
-
Sviluppa un’applicazione NodeJS di esempio che chiama l’API Assets Author per recuperare i metadati di una risorsa specifica.
Prima di iniziare, assicurati di aver rivisto quanto segue:
Prerequisiti
Per completare questa esercitazione, è necessario:
-
L’ambiente AEM as a Cloud Service è stato modernizzato con:
- AEM versione
2024.10.18459.20241031T210302Z
o successiva. - Nuovi profili di prodotto (se l’ambiente è stato creato prima di novembre 2024)
Consulta l'articolo Configurare le API AEM basate su OpenAPI per ulteriori dettagli.
- AEM versione
-
Il progetto WKND Sites di esempio deve essere distribuito su di esso.
-
Accesso a Adobe Developer Console.
-
Installa Node.js nel computer locale per eseguire l'applicazione NodeJS di esempio.
Passaggi di sviluppo
Le fasi di sviluppo di alto livello sono:
-
Configura progetto ADC
- Aggiungere l’API di authoring di Assets
- Configurare il relativo metodo di autenticazione come server-to-server OAuth
- Associare il profilo di prodotto alla configurazione di autenticazione
-
Configura l’istanza di AEM per abilitare la comunicazione del progetto ADC
-
Sviluppare un esempio di applicazione NodeJS
-
Verificare il flusso end-to-end
Configura progetto ADC
Il passaggio di configurazione del progetto ADC è repeat dalle API AEM basate su OpenAPI. Viene ripetuto per aggiungere l’API di authoring di Assets e configurare il relativo metodo di autenticazione come server-to-server OAuth.
-
Da Adobe Developer Console, apri il progetto desiderato.
-
Per aggiungere le API di AEM, fai clic sul pulsante Aggiungi API.
-
Nella finestra di dialogo Aggiungi API, filtra per Experience Cloud, seleziona la scheda API Autore AEM Assets e fai clic su Avanti.
TIP
Se la scheda API AEM desiderata è disabilitata e Perché è disabilitata?Le informazioni di mostrano il messaggio Licenza richiesta uno dei motivi potrebbe essere che NON hai modernizzato l'ambiente AEM as a Cloud Service. Per ulteriori informazioni, consulta Modernizzazione dell'ambiente AEM as a Cloud Service. -
Nella finestra di dialogo Configura API, selezionare l'opzione di autenticazione Server-to-Server e fare clic su Avanti. L’autenticazione server-to-server è ideale per i servizi back-end che richiedono accesso API senza interazione da parte dell’utente.
TIP
Se l’opzione di autenticazione da server a server non è visibile, significa che l’utente che configura l’integrazione non viene aggiunto come sviluppatore al profilo di prodotto a cui è associato il servizio. Per ulteriori informazioni, vedere Abilitare l'autenticazione server-to-server. -
Rinominare le credenziali per semplificarne l'identificazione (se necessario) e fare clic su Avanti. A scopo dimostrativo, viene utilizzato il nome predefinito.
-
Seleziona il profilo di prodotto Utenti AEM Assets Collaborator - Autore - Programma XXX - Ambiente XXX e fai clic su Salva. Come puoi vedere, è disponibile per la selezione solo il profilo di prodotto associato al servizio Utenti API di AEM Assets.
-
Controlla l’API di AEM e la configurazione dell’autenticazione.
Configura istanza AEM per abilitare la comunicazione del progetto ADC
Segui le istruzioni riportate nell'articolo Configura le API AEM basate su OpenAPI per configurare l'istanza di AEM in modo da abilitare la comunicazione con il progetto ADC.
Sviluppare un esempio di applicazione NodeJS
Sviluppiamo un’applicazione NodeJS di esempio che chiama l’API Assets Author.
Per sviluppare l’applicazione puoi utilizzare altri linguaggi di programmazione come Java, Python, ecc.
A scopo di test, puoi utilizzare Postman, curl o qualsiasi altro client REST per richiamare le API di AEM.
Rivedere l’API
Prima di sviluppare l'applicazione, esaminiamo distribuire l'endpoint dei metadati della risorsa specificata dall'API Assets Author. La sintassi API è:
GET https://{bucket}.adobeaemcloud.com/adobe/../assets/{assetId}/metadata
Per recuperare i metadati di una risorsa specifica, sono necessari i valori bucket
e assetId
. bucket
è il nome dell'istanza di AEM senza il nome di dominio di Adobe (.adobeaemcloud.com), ad esempio author-p63947-e1420428
.
assetId
è l'UUID JCR della risorsa con il prefisso urn:aaid:aem:
, ad esempio urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
. Esistono diversi modi per ottenere assetId
:
-
Aggiungere l'estensione del percorso della risorsa AEM
.json
per ottenere i metadati della risorsa.https://author-p63947-e1420429.adobeaemcloud.com/content/dam/wknd-shared/en/adventures/cycling-southern-utah/adobestock-221043703.jpg.json
e cercare la proprietàjcr:uuid
. -
In alternativa, è possibile ottenere
assetId
esaminando la risorsa nella finestra di ispezione degli elementi del browser. Cercare l'attributodata-id="urn:aaid:aem:..."
.
Richiama l’API tramite il browser
Prima di sviluppare l'applicazione, richiamiamo l'API utilizzando la funzionalità Prova nella documentazione API.
-
Apri la documentazione dell'API Assets Author nel browser.
-
Espandi la sezione Metadati e fai clic sull'opzione Distribuisce i metadati della risorsa specificata.
-
Nel riquadro destro fare clic sul pulsante Prova.
-
Immetti i seguenti valori:
SezioneParametroValorebucketIl nome dell'istanza AEM senza il nome di dominio Adobe (.adobeaemcloud.com), ad esempioauthor-p63947-e1420428
.SicurezzaToken BearerUtilizza il token di accesso dalle credenziali server-to-server OAuth del progetto ADC.SicurezzaX-Api-KeyUtilizza il valoreClientID
dalle credenziali server-to-server OAuth del progetto ADC.ParametriassetIdIdentificatore univoco della risorsa in AEM, ad esempiourn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
ParametriX-Adobe-Accept-Experimental1 -
Fai clic su Invia per richiamare l'API e controlla la risposta nella scheda Risposta.
I passaggi precedenti confermano la modernizzazione dell’ambiente AEM as a Cloud Service, consentendo l’accesso alle API di AEM. Inoltre, conferma la corretta configurazione del progetto ADC e la comunicazione delle credenziali server-to-server OAuth ClientID con l’istanza Autore AEM.
Esempio di applicazione NodeJS
Creiamo un esempio di applicazione NodeJS.
Per sviluppare l'applicazione, puoi utilizzare Esegui l'applicazione campione o le istruzioni Sviluppo.
-
Scarica il file zip dell'applicazione demo-nodejs-app-to-invoke-aem-openapi di esempio ed estrailo.
-
Passa alla cartella estratta e installa le dipendenze.
$ npm install
-
Sostituire i segnaposto nel file
.env
con i valori effettivi delle credenziali server-to-server OAuth del progetto ADC. -
Sostituire
<BUCKETNAME>
e<ASSETID>
nel filesrc/index.js
con i valori effettivi. -
Esegui l’applicazione NodeJS.
$ node src/index.js
-
Crea un nuovo progetto NodeJS.
$ mkdir demo-nodejs-app-to-invoke-aem-openapi $ cd demo-nodejs-app-to-invoke-aem-openapi $ npm init -y
-
Installa le librerie fetch e dotenv per effettuare richieste HTTP e leggere le variabili di ambiente rispettivamente.
$ npm install node-fetch $ npm install dotenv
-
Apri il progetto nel tuo editor di codice preferito e aggiorna il file
package.json
per aggiungeretype
amodule
.{ ... "version": "1.0.0", "type": "module", "main": "index.js", ... }
-
Crea il file
.env
e aggiungi la seguente configurazione. Sostituisci i segnaposto con i valori effettivi delle credenziali server-to-server OAuth del progetto ADC.CLIENT_ID=<ADC Project OAuth Server-to-Server credential ClientID> CLIENT_SECRET=<ADC Project OAuth Server-to-Server credential Client Secret> SCOPES=<ADC Project OAuth Server-to-Server credential Scopes>
-
Creare il file
src/index.js
e aggiungere il codice seguente e sostituire<BUCKETNAME>
e<ASSETID>
con i valori effettivi.// Import the dotenv configuration to load environment variables from the .env file import "dotenv/config"; // Import the fetch function to make HTTP requests import fetch from "node-fetch"; // REPLACE THE FOLLOWING VALUES WITH YOUR OWN const bucket = "<BUCKETNAME>"; // Bucket name is the AEM instance name (e.g. author-p63947-e1420428) const assetId = "<ASSETID>"; // Asset ID is the unique identifier for the asset in AEM (e.g. urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da). You can get it by inspecting the asset in browser's element inspector, look for data-id="urn:aaid:aem:..." // Load environment variables for authentication const clientId = process.env.CLIENT_ID; // Adobe IMS client ID const clientSecret = process.env.CLIENT_SECRET; // Adobe IMS client secret const scopes = process.env.SCOPES; // Scope for the API access // Adobe IMS endpoint for obtaining an access token const adobeIMSV3TokenEndpointURL = "https://ims-na1.adobelogin.com/ims/token/v3"; // Function to obtain an access token from Adobe IMS const getAccessToken = async () => { console.log("Getting access token from IMS"); // Log process initiation //console.log("Client ID: " + clientId); // Display client ID for debugging purposes // Configure the HTTP POST request to fetch the access token const options = { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", // Specify form data content type }, // Send client ID, client secret, and scopes as the request body body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`, }; // Make the HTTP request to fetch the access token const response = await fetch(adobeIMSV3TokenEndpointURL, options); //console.log("Response status: " + response.status); // Log the HTTP status for debugging const responseJSON = await response.json(); // Parse the JSON response console.log("Access token received"); // Log success message // Return the access token return responseJSON.access_token; }; // Function to retrieve metadata for a specific asset from AEM const getAssetMetadat = async () => { // Fetch the access token using the getAccessToken function const accessToken = await getAccessToken(); console.log("Getting asset metadata from AEM"); // Invoke the Assets Author API to retrieve metadata for a specific asset const resp = await fetch( `https://${bucket}.adobeaemcloud.com/adobe/../assets/${assetId}/metadata`, // Construct the URL with bucket and asset ID { method: "GET", headers: { "If-None-Match": "string", // Header to handle caching (not critical for this tutorial) "X-Adobe-Accept-Experimental": "1", // Header to enable experimental Adobe API features Authorization: "Bearer " + accessToken, // Provide the access token for authorization "X-Api-Key": clientId, // Include the OAuth S2S ClientId for identification }, } ); const data = await resp.json(); // Parse the JSON response console.log("Asset metadata received"); // Log success message console.log(data); // Display the retrieved metadata }; // Call the getAssets function to start the process getAssetMetadat();
-
Esegui l’applicazione NodeJS.
$ node src/index.js
Risposta API
Dopo la corretta esecuzione, la risposta API viene visualizzata nella console. La risposta contiene i metadati della risorsa specificata.
{
"assetId": "urn:aaid:aem:9c09ff70-9ee8-4b14-a5fa-ec37baa0d1b3",
"assetMetadata": {
...
"dc:title": "A Young Mountain Biking Couple Takes A Minute To Take In The Scenery",
"xmp:CreatorTool": "Adobe Photoshop Lightroom Classic 7.5 (Macintosh)",
...
},
"repositoryMetadata": {
...
"repo:name": "adobestock-221043703.jpg",
"repo:path": "/content/dam/wknd-shared/en/adventures/cycling-southern-utah/adobestock-221043703.jpg",
"repo:state": "ACTIVE",
...
}
}
Congratulazioni Le API AEM basate su OpenAPI sono state richiamate dall’applicazione personalizzata mediante l’autenticazione server-to-server di OAuth.
Rivedi il codice dell’applicazione
I callout chiave dal codice di esempio dell’applicazione NodeJS sono:
-
Autenticazione IMS: recupera un token di accesso utilizzando l'impostazione delle credenziali da server a server OAuth nel progetto ADC.
// Function to obtain an access token from Adobe IMS const getAccessToken = async () => { // Configure the HTTP POST request to fetch the access token const options = { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", // Specify form data content type }, // Send client ID, client secret, and scopes as the request body body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}&scope=${scopes}`, }; // Make the HTTP request to fetch the access token from Adobe IMS token endpoint https://ims-na1.adobelogin.com/ims/token/v3 const response = await fetch(adobeIMSV3TokenEndpointURL, options); const responseJSON = await response.json(); // Parse the JSON response // Return the access token return responseJSON.access_token; }; ...
-
Chiamata API: richiama l'API Assets Author per recuperare i metadati per una risorsa specifica fornendo il token di accesso per l'autorizzazione.
// Function to retrieve metadata for a specific asset from AEM const getAssetMetadat = async () => { // Fetch the access token using the getAccessToken function const accessToken = await getAccessToken(); console.log("Getting asset metadata from AEM"); // Invoke the Assets Author API to retrieve metadata for a specific asset const resp = await fetch( `https://${bucket}.adobeaemcloud.com/adobe/../assets/${assetId}/metadata`, // Construct the URL with bucket and asset ID { method: "GET", headers: { "If-None-Match": "string", // Header to handle caching (not critical for this tutorial) "X-Adobe-Accept-Experimental": "1", // Header to enable experimental Adobe API features Authorization: "Bearer " + accessToken, // Provide the access token for authorization "X-Api-Key": clientId, // Include the OAuth S2S ClientId for identification }, } ); const data = await resp.json(); // Parse the JSON response console.log("Asset metadata received"); // Log success message console.log(data); // Display the retrieved metadata }; ...
Sotto il cofano
Dopo aver chiamato correttamente l’API, nel servizio AEM Author viene creato un utente che rappresenta le credenziali da server a server OAuth del progetto ADC, insieme ai gruppi di utenti che corrispondono alla configurazione del profilo di prodotto e dei servizi. L'utente account tecnico è associato al profilo di prodotto e al gruppo di utenti Servizi, che dispone delle autorizzazioni necessarie per LEGGERE i metadati della risorsa.
Per verificare la creazione di utenti e gruppi di utenti per l’account tecnico, effettua le seguenti operazioni:
-
Nel progetto ADC, passa alla configurazione delle credenziali OAuth Server-to-Server. Nota il valore E-mail account tecnico.
-
Nel servizio AEM Author, passa a Strumenti > Sicurezza > Utenti e cerca il valore E-mail account tecnico.
-
Fai clic sull'utente account tecnico per visualizzare i dettagli dell'utente, ad esempio l'iscrizione a Gruppi. Come mostrato di seguito, l'utente dell'account tecnico è associato ai gruppi di utenti AEM Assets Collaborator Users - author - Program XXX - Environment XXX e AEM Assets Collaborator Users - Service.
-
L'utente dell'account tecnico è associato al profilo di prodotto Utenti AEM Assets Collaborator - Autore - Programma XXX - Ambiente XXX. Il profilo di prodotto è associato ai servizi Utenti API AEM Assets e Utenti AEM Assets Collaborator.
-
Il profilo prodotto e l'associazione utente dell'account tecnico possono essere verificati nella scheda Credenziali API di Profili prodotto.
Errore 403 per richieste non GET
Per LEGGERE i metadati della risorsa, l'utente dell'account tecnico creato per le credenziali server-to-server OAuth dispone delle autorizzazioni necessarie tramite il gruppo di utenti Servizi (ad esempio, Utenti di AEM Assets Collaborator - Servizio).
Tuttavia, per creare, aggiornare, eliminare (CUD) i metadati della risorsa, l'utente dell'account tecnico necessita di autorizzazioni aggiuntive. Puoi verificarla richiamando l’API con una richiesta non GET (ad esempio, PATCH, DELETE) e osservare la risposta di errore 403.
Invochiamo la richiesta PATCH per aggiornare i metadati della risorsa e osservare la risposta all'errore 403.
-
Apri la documentazione dell'API Assets Author nel browser.
-
Immetti i seguenti valori:
SezioneParametroValoreBucketIl nome dell'istanza AEM senza il nome di dominio Adobe (.adobeaemcloud.com), ad esempioauthor-p63947-e1420428
.SicurezzaToken BearerUtilizza il token di accesso dalle credenziali server-to-server OAuth del progetto ADC.SicurezzaX-Api-KeyUtilizza il valoreClientID
dalle credenziali server-to-server OAuth del progetto ADC.Corpo[{ "op": "add", "path": "foo","value": "bar"}]
ParametriassetIdIdentificatore univoco della risorsa in AEM, ad esempiourn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
ParametriX-Adobe-Accept-Experimental*ParametriX-Adobe-Accept-Experimental1 -
Fai clic su Invia per richiamare la richiesta PATCH e osservare la risposta di errore 403.
Per correggere l'errore 403, sono disponibili due opzioni:
-
In ADC Project, aggiorna il profilo di prodotto associato alle credenziali server-to-server OAuth con un profilo di prodotto appropriato che disponga delle autorizzazioni necessarie per creare, aggiornare, eliminare (CUD) i metadati della risorsa, ad esempio Amministratori AEM - Autore - Programma XXX - Ambiente XXX. Per ulteriori informazioni, consulta l'articolo Procedura: credenziali connesse dell'API e gestione dei profili di prodotto.
-
Utilizzando AEM Project, aggiorna le autorizzazioni del gruppo di utenti del servizio AEM associato (ad esempio, Utenti di AEM Assets Collaborator - Servizio) in AEM Author per consentire la creazione, l'aggiornamento, l'eliminazione (CUD) dei metadati della risorsa. Per ulteriori informazioni, vedere l'articolo Procedura: gestione delle autorizzazioni dei gruppi di utenti del servizio AEM.
Riepilogo
In questo tutorial, hai imparato a richiamare le API AEM basate su OpenAPI da applicazioni personalizzate. Hai abilitato l’accesso alle API di AEM, hai creato e configurato un progetto Adobe Developer Console (ADC).
Nel progetto ADC, hai aggiunto le API di AEM, ne hai configurato il tipo di autenticazione e hai associato il profilo di prodotto. Hai anche configurato l’istanza di AEM per abilitare la comunicazione al progetto ADC e sviluppato un’applicazione NodeJS di esempio che chiama l’API di authoring di Assets.