DocumentazioneAEMTutorial su AEMTutorial su AEM as a Cloud Service

Richiama le API AEM basate su OpenAPI utilizzando l’autenticazione server-to-server OAuth

Ultimo aggiornamento: 18 giugno 2025
  • 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:

  • Accesso alle API di Adobe e ai concetti correlati.
  • Configura l'articolo sulle API AEM basate su OpenAPI.

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.

  • 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:

  1. Configura progetto ADC

    1. Aggiungere l’API di authoring di Assets
    2. Configurare il relativo metodo di autenticazione come server-to-server OAuth
    3. Associare il profilo di prodotto alla configurazione di autenticazione
  2. Configura l’istanza di AEM per abilitare la comunicazione del progetto ADC

  3. Sviluppare un esempio di applicazione NodeJS

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

TIP
Assicurati di aver completato il passaggio Abilita accesso API di AEM dall'articolo Configura API di AEM basate su OpenAPI. Senza di esso, l’opzione di autenticazione server-to-server non è disponibile.
  1. Da Adobe Developer Console, apri il progetto desiderato.

  2. Per aggiungere le API di AEM, fai clic sul pulsante Aggiungi API.

    Aggiungi API

  3. Nella finestra di dialogo Aggiungi API, filtra per Experience Cloud, seleziona la scheda API Autore AEM Assets e fai clic su Avanti.

    Aggiungi API AEM

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

    Seleziona autenticazione

    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.
  5. Rinominare le credenziali per semplificarne l'identificazione (se necessario) e fare clic su Avanti. A scopo dimostrativo, viene utilizzato il nome predefinito.

    Rinomina credenziali

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

    Seleziona profilo prodotto

  7. Controlla l’API di AEM e la configurazione dell’autenticazione.

    Configurazione API AEM

    Configurazione 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'attributo data-id="urn:aaid:aem:...".

    Verifica risorsa

Richiama l’API tramite il browser

Prima di sviluppare l'applicazione, richiamiamo l'API utilizzando la funzionalità Prova nella documentazione API.

  1. Apri la documentazione dell'API Assets Author nel browser.

  2. Espandi la sezione Metadati e fai clic sull'opzione Distribuisce i metadati della risorsa specificata.

  3. Nel riquadro destro fare clic sul pulsante Prova.
    Documentazione API

  4. Immetti i seguenti valori:

    Sezione
    Parametro
    Valore
    bucket
    Il nome dell'istanza AEM senza il nome di dominio Adobe (.adobeaemcloud.com), ad esempio author-p63947-e1420428.
    Sicurezza
    Token Bearer
    Utilizza il token di accesso dalle credenziali server-to-server OAuth del progetto ADC.
    Sicurezza
    X-Api-Key
    Utilizza il valore ClientID dalle credenziali server-to-server OAuth del progetto ADC.
    Parametri
    assetId
    Identificatore univoco della risorsa in AEM, ad esempio urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
    Parametri
    X-Adobe-Accept-Experimental
    1

    Richiama API - token di accesso

    Richiama API - valori di input

  5. Fai clic su Invia per richiamare l'API e controlla la risposta nella scheda Risposta.

    Richiama API - 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.

Esegui l'applicazione campione
  1. Scarica il file zip dell'applicazione demo-nodejs-app-to-invoke-aem-openapi di esempio ed estrailo.

  2. Passa alla cartella estratta e installa le dipendenze.

    $ npm install
    
  3. Sostituire i segnaposto nel file .env con i valori effettivi delle credenziali server-to-server OAuth del progetto ADC.

  4. Sostituire <BUCKETNAME> e <ASSETID> nel file src/index.js con i valori effettivi.

  5. Esegui l’applicazione NodeJS.

    $ node src/index.js
    
Sviluppo guidato
  1. Crea un nuovo progetto NodeJS.

    $ mkdir demo-nodejs-app-to-invoke-aem-openapi
    $ cd demo-nodejs-app-to-invoke-aem-openapi
    $ npm init -y
    
  2. Installa le librerie fetch e dotenv per effettuare richieste HTTP e leggere le variabili di ambiente rispettivamente.

    $ npm install node-fetch
    $ npm install dotenv
    
  3. Apri il progetto nel tuo editor di codice preferito e aggiorna il file package.json per aggiungere type a module.

    {
        ...
        "version": "1.0.0",
        "type": "module",
        "main": "index.js",
        ...
    }
    
  4. 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>
    
  5. 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();
    
  6. 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:

  1. 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;
    };
    ...
    
  2. 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.

    E-mail account tecnico

  • Nel servizio AEM Author, passa a Strumenti > Sicurezza > Utenti e cerca il valore E-mail account tecnico.

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

    Appartenenza utente account tecnico

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

    Profilo prodotto utente account tecnico

  • Il profilo prodotto e l'associazione utente dell'account tecnico possono essere verificati nella scheda Credenziali API di Profili prodotto.

    Credenziali API profilo 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:

    Sezione
    Parametro
    Valore
    Bucket
    Il nome dell'istanza AEM senza il nome di dominio Adobe (.adobeaemcloud.com), ad esempio author-p63947-e1420428.
    Sicurezza
    Token Bearer
    Utilizza il token di accesso dalle credenziali server-to-server OAuth del progetto ADC.
    Sicurezza
    X-Api-Key
    Utilizza il valore ClientID dalle credenziali server-to-server OAuth del progetto ADC.
    Corpo
    [{ "op": "add", "path": "foo","value": "bar"}]
    Parametri
    assetId
    Identificatore univoco della risorsa in AEM, ad esempio urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da
    Parametri
    X-Adobe-Accept-Experimental
    *
    Parametri
    X-Adobe-Accept-Experimental
    1
  • Fai clic su Invia per richiamare la richiesta PATCH e osservare la risposta di errore 403.

    Richiama API - Richiesta PATCH

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.

Risorse aggiuntive

  • Guida all’implementazione delle credenziali da server a server OAuth
recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69