Dokumentation AEM Självstudiekurser om AEM Självstudiekurser om AEM as a Cloud Service

Anropa OpenAPI-baserade AEM-API:er med OAuth Server-till-Server-autentisering

Last update: Wed Mar 05 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Ämnen:
Utveckling

Skapat för:

Nybörjare
Utvecklare
Ledare

Lär dig hur du anropar OpenAPI-baserade AEM-API:er på AEM as a Cloud Service från anpassade program med OAuth Server-till-Server-autentisering.

OAuth Server-till-Server-autentiseringen är idealisk för backend-tjänster som behöver API-åtkomst utan användarinteraktion. Den använder tilldelningstypen client_credentials för OAuth 2.0 för att autentisera klientprogrammet.

AVAILABILITY

OpenAPI-baserade AEM API:er är tillgängliga som en del av ett program för tidig åtkomst. Om du är intresserad av att få tillgång till dem bör du skicka ett e-postmeddelande till aem-apis@adobe.com med en beskrivning av ditt användningsfall.

Vad du lär dig what-you-learn

I den här självstudiekursen får du lära dig att:

Konfigurera ett Adobe Developer Console-projekt (ADC) så att du får åtkomst till Assets Author API med hjälp av OAuth Server-till-Server-autentisering.
Utveckla ett exempel på ett NodeJS-program som anropar Assets Author API för att hämta metadata för en viss resurs.

Innan du börjar bör du kontrollera följande:

Åtkomst till Adobe API:er och relaterade koncept-avsnitt.
Konfigurera OpenAPI-baserade AEM API:er-artiklar.

Förutsättningar

För att kunna genomföra den här självstudiekursen behöver du:

Moderniserad AEM as a Cloud Service-miljö med följande:
- AEM version 2024.10.18459.20241031T210302Z eller senare.
- Nya produktprofiler (om miljön skapades före november 2024)
Mer information finns i artikeln Konfigurera OpenAPI-baserade AEM API:er.
Exempelprojektet WKND Sites måste distribueras till det.
Åtkomst till Adobe Developer Console.
Installera Node.js på den lokala datorn för att köra exempelprogrammet NodeJS.

Utvecklingssteg

Utvecklingsstegen på hög nivå är följande:

Konfigurera ADC-projekt
1. Lägg till Assets Author API
2. Konfigurera autentiseringsmetoden som OAuth Server-till-Server
3. Associera produktprofil med autentiseringskonfigurationen
Konfigurera AEM-instansen för att aktivera ADC-projektkommunikation
Utveckla ett exempel på ett NodeJS-program
Verifiera flödet från början till slut

Konfigurera ADC-projekt

Konfigurationssteget för ADC-projekt är upprepat från Konfigurera OpenAPI-baserade AEM-API:er. Det upprepas att lägga till API:t för Assets Author och konfigurera autentiseringsmetoden som OAuth Server-to-Server.

Öppna önskat projekt från Adobe Developer Console.
Om du vill lägga till AEM API:er klickar du på knappen Lägg till API .
I dialogrutan Lägg till API filtrerar du efter Experience Cloud, markerar AEM Assets Author API-kortet och klickar på Nästa.
I dialogrutan Konfigurera API väljer du autentiseringsalternativet Server-till-server och klickar på Nästa. Server-till-server-autentiseringen är idealisk för backend-tjänster som behöver API-åtkomst utan användarinteraktion.
Byt namn på autentiseringsuppgifterna för enklare identifiering (om det behövs) och klicka på Nästa. I demosyfte används standardnamnet.
Välj AEM Assets Collaborator Users - författare - Program XXX - Miljö XXX Produktprofil och klicka på Spara. Som du ser kan du bara välja den produktprofil som är kopplad till AEM Assets API-användartjänst.
Granska AEM API och autentiseringskonfigurationen.

Konfigurera AEM-instans för att aktivera ADC-projektkommunikation

Följ instruktionerna i artikeln Konfigurera OpenAPI-baserade AEM API:er för att konfigurera AEM-instansen så att ADC-projektkommunikation aktiveras.

Utveckla ett exempel på ett NodeJS-program

Låt oss utveckla ett exempel på ett NodeJS-program som anropar Assets Author API.

Du kan använda andra programmeringsspråk som Java, Python osv. för att utveckla programmet.

I testsyfte kan du använda Postman, curl eller någon annan REST-klient för att anropa AEM API:er.

Granska API

Innan vi utvecklar programmet ska vi granska den angivna resursens metadata-slutpunkt från Assets Author API. API-syntaxen är:

GET https://{bucket}.adobeaemcloud.com/adobe/../assets/{assetId}/metadata

Om du vill hämta metadata för en viss resurs behöver du värdena bucket och assetId. bucket är AEM-instansnamnet utan Adobe-domännamnet (.adobeaemcloud.com), till exempel author-p63947-e1420428.

assetId är JCR UUID för resursen med prefixet urn:aaid:aem:, till exempel urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da. Det finns flera sätt att hämta assetId:

Lägg till AEM resurssökväg .json för att hämta metadata för resursen. Till exempel https://author-p63947-e1420429.adobeaemcloud.com/content/dam/wknd-shared/en/adventures/cycling-southern-utah/adobestock-221043703.jpg.json och leta efter egenskapen jcr:uuid.
Du kan också hämta assetId genom att inspektera resursen i webbläsarens elementkontroll. Leta efter attributet data-id="urn:aaid:aem:...".

Anropa API:t med webbläsaren

Innan vi utvecklar programmet måste vi anropa API:t med funktionen Prova i API-dokumentationen.

Öppna Assets Author API-dokumentationen i webbläsaren.
Expandera avsnittet Metadata och klicka på alternativet Levererar den angivna resursens metadata.
Klicka på knappen Testa i den högra rutan.

Ange följande värden:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
Avsnitt	Parameter	Värde
	bucket	AEM-instansnamnet utan Adobe-domännamnet (.adobeaemcloud.com), till exempel `author-p63947-e1420428`.
Säkerhet	Bearer Token	Använd åtkomsttoken från ADC-projektets autentiseringsuppgifter för OAuth Server-till-server.
Säkerhet	X-API-tangent	Använd värdet `ClientID` från ADC-projektets autentiseringsuppgifter för OAuth Server-till-server.
Parametrar	assetId	Den unika identifieraren för resursen i AEM, till exempel `urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da`
Parametrar	X-Adobe-Accept-Experimental	1

Anropa API - åtkomsttoken

Anropa API - indatavärden

Klicka på Skicka för att anropa API:t och granska svaret på fliken Svar.

Stegen ovan bekräftar moderniseringen av AEM as a Cloud Service-miljön och ger åtkomst till AEM API:er. Det bekräftar också den lyckade konfigurationen av ADC-projektet och kommunikationen mellan klient-ID för OAuth Server-till-Server-autentiseringsuppgifter och AEM Author-instansen.

Exempel på NodeJS-program

Låt oss utveckla ett exempel på ett NodeJS-program.

Om du vill utveckla programmet kan du antingen använda instruktionerna Kör-the-sample-application eller Steg-för-steg-utveckling .

Kör-the-sample-application

Hämta exempelfilen demo-nodatums-app-to-invoke-aem-openapi för programmet och extrahera den.

Navigera till den extraherade mappen och installera beroendena.

code language-bash
`$ npm install`

Ersätt platshållarna i filen .env med de faktiska värdena från ADC-projektets autentiseringsuppgifter för OAuth Server-till-server.
Ersätt <BUCKETNAME> och <ASSETID> i filen src/index.js med de faktiska värdena.

Kör programmet NodeJS.

code language-bash
`$ node src/index.js`

Steg-för-steg-utveckling

Skapa ett nytt NodeJS-projekt.

code language-bash
`$ mkdir demo-nodejs-app-to-invoke-aem-openapi $ cd demo-nodejs-app-to-invoke-aem-openapi $ npm init -y`

Installera biblioteket fetch och dotenv om du vill göra HTTP-begäranden och läsa miljövariablerna.

code language-bash
`$ npm install node-fetch $ npm install dotenv`

Öppna projektet i din favoritkodredigerare och uppdatera filen package.json för att lägga till filen type i module.

code language-json
`{ ... "version": "1.0.0", "type": "module", "main": "index.js", ... }`

Skapa filen .env och lägg till följande konfiguration. Ersätt platshållarna med de faktiska värdena från ADC-projektets autentiseringsuppgifter för OAuth Server-till-Server.

code language-properties

code language-properties
`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>`

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>

Skapa filen src/index.js och lägg till följande kod och ersätt <BUCKETNAME> och <ASSETID> med de faktiska värdena.

code language-javascript

code language-javascript
// 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();

// 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();

Kör programmet NodeJS.

code language-bash
`$ node src/index.js`

API-svar

När körningen är klar visas API-svaret i konsolen. Svaret innehåller metadata för angiven resurs.

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

Grattis! Du har anropat de OpenAPI-baserade AEM-API:erna från ditt anpassade program med OAuth Server-till-Server-autentisering.

Granska programkoden

Huvudpratbubblorna från exemplet NodeJS-programkod är:

IMS-autentisering: Hämtar en åtkomsttoken med hjälp av inställningarna för OAuth Server-till-Server-autentiseringsuppgifter i ADC-projektet.

code language-javascript

code language-javascript
// 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; }; ...

// 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;
};
...

API-anrop: Anropar Assets Author API för att hämta metadata för en viss resurs genom att ange åtkomsttoken för auktorisering.

code language-javascript

code language-javascript
// 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 }; ...

// 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
};
...

Under huven

När API-anropet lyckades skapas en användare som representerar ADC-projektets autentiseringsuppgifter för OAuth Server-till-Server i AEM Author-tjänsten tillsammans med användargrupperna som matchar produktprofilen och tjänstkonfigurationen. Den tekniska kontoanvändaren är kopplad till produktprofilen och användargruppen Services som har de behörigheter som krävs för att LÄS resursens metadata.

Följ de här stegen för att verifiera att den tekniska kontoanvändaren och användargruppen har skapats:

Gå till autentiseringskonfigurationen OAuth Server-till-Server i ADC-projektet. Observera värdet för e-postadress för tekniskt konto.
Gå till Verktyg > Säkerhet > Användare i AEM Author-tjänsten och sök efter värdet E-post för tekniskt konto.
Klicka på den tekniska kontoanvändaren för att visa användarinformation, som Grupper-medlemskap. Som framgår nedan är den tekniska kontoanvändaren associerad med användargrupperna AEM Assets Collaborator Users - författare - Program XXX - Environment XXX och AEM Assets Collaborator Users - Service .
Observera att den tekniska kontoanvändaren är kopplad till produktprofilen AEM Assets Collaborator Users - författare - Program XXX - Miljö XXX. Produktprofilen är associerad med AEM Assets API-användare och AEM Assets Collaborator-användartjänster.
Produktprofilen och associationen för tekniska kontoanvändare kan verifieras på fliken API-autentiseringsuppgifter för produktprofiler.

403-fel för icke-GET-begäranden

För att LÄS resursens metadata har den tekniska kontoanvändaren som skapades för OAuth Server-till-Server-autentiseringsuppgifterna nödvändiga behörigheter via användargruppen Tjänster (till exempel AEM Assets Collaborator Users - Service).

Om du vill skapa, uppdatera, ta bort (CUD) metadata för resursen måste den tekniska kontoanvändaren ha ytterligare behörigheter. Du kan verifiera det genom att anropa API:t med en begäran som inte är GET (till exempel PATCH, DELETE) och observera 403-felsvaret.

Låt oss anropa PATCH -begäran för att uppdatera metadata för resursen och observera 403-felsvaret.

Öppna Assets Author API-dokumentationen i webbläsaren.

Ange följande värden:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3
Avsnitt	Parameter	Värde
Bucket		AEM-instansnamnet utan Adobe-domännamnet (.adobeaemcloud.com), till exempel `author-p63947-e1420428`.
Säkerhet	Bearer Token	Använd åtkomsttoken från ADC-projektets autentiseringsuppgifter för OAuth Server-till-server.
Säkerhet	X-API-tangent	Använd värdet `ClientID` från ADC-projektets autentiseringsuppgifter för OAuth Server-till-server.
Brödtext		`[{ "op": "add", "path": "foo","value": "bar"}]`
Parametrar	assetId	Den unika identifieraren för resursen i AEM, till exempel `urn:aaid:aem:a200faf1-6d12-4abc-bc16-1b9a21f870da`
Parametrar	X-Adobe-Accept-Experimental	*
Parametrar	X-Adobe-Accept-Experimental	1

Klicka på Skicka för att anropa PATCH-begäran och observera 403-felsvaret.

Du kan åtgärda felet 403 på två sätt:

I ADC Project uppdaterar du den associerade produktprofilen för OAuth Server-till-Server-autentiseringsuppgiften med en lämplig produktprofil som har de behörigheter som krävs för att skapa, uppdatera, ta bort (CUD) metadata för resursen, till exempel AEM-administratörer - författare - Program XXX - Miljö XXX. Mer information finns i artikeln Använda - API:ts anslutna autentiseringsuppgifter och hantering av produktprofiler .
Med AEM Project uppdaterar du den associerade AEM-tjänstanvändargruppens (till exempel AEM Assets Collaborator Users - Service) behörigheter i AEM Author så att Create, Update, Delete (CUD) of the asset metadata. Mer information finns i artikeln Använda - behörighetshantering för AEM-användargrupper.

Sammanfattning

I den här självstudiekursen lärde du dig att anropa OpenAPI-baserade AEM-API:er från anpassade program. Du har aktiverat åtkomst till AEM API:er, skapat och konfigurerat ett Adobe Developer Console-projekt (ADC).
I ADC-projektet lade du till AEM API:er, konfigurerade autentiseringstypen och kopplade till produktprofilen. Du har även konfigurerat AEM-instansen för att aktivera ADC-projektkommunikation och utvecklat ett exempel-NodeJS-program som anropar Assets Author API.

Ytterligare resurser

Implementeringshandbok för autentiseringsuppgifter för OAuth Server-till-Server

recommendation-more-help

4859a77c-7971-4ac9-8f5c-4260823c6f69