Documentazione Commerce Adobe Commerce as a Cloud Service

Prerequisiti del tutorial

Last update: Mon Mar 23 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

Argomenti:
App Builder
Cloud

Creato per:

Intermedio
Sviluppatore

In questa pagina sono elencati i prerequisiti e i passaggi di configurazione per le esercitazioni di Adobe Commerce as a Cloud Service, ad esempio l'esercitazione sull'estensione delle classificazioni e l'esercitazione sull'estensione del metodo di spedizione.

Prerequisiti generali

In questo tutorial sono necessari i seguenti strumenti per lo sviluppo sia di estensioni che di vetrine.

Node.js (versione 22.x.x) e npm (9.0.0 o successiva): Verificare l'installazione utilizzando il comando seguente:

code language-bash
`node --version npm --version`

Installa Git. Verificare l'installazione:

code language-bash
`git --version`

Guscio Bash
- macOS/Linux: nessuna installazione richiesta
- Windows: utilizzare Git Bash o Windows Subsystem for Linux (WSL)
Scarica un IDE basato su IA, ad esempio Cursore (consigliato). Sono supportati anche altri IDE, come Claude Code, Gemini CLI o Copilot, ma potrebbero richiedere modifiche ai prompt e ad altri passaggi dell’esercitazione.

Adobe Commerce as a Cloud Service prerequisiti

Installa Adobe I/O CLI

code language-bash
`npm install -g @adobe/aio-cli`

Installa i plug-in Adobe I/O CLI Commerce, Adobe I/O CLI Runtime e App Builder CLI:

code language-bash
`aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce @adobe/aio-cli-plugin-app-dev @adobe/aio-cli-plugin-runtime`

Dopo aver installato Adobe I/O CLI e i plug-in richiesti, configurare l'area di lavoro di estensibilità. Adobe consiglia di utilizzare la configurazione automatica per un’esperienza più rapida.

Installazione automatizzata (scelta consigliata): esegui un singolo comando per configurare automaticamente l'area di lavoro.
Configurazione manuale: seguire le istruzioni dettagliate per configurare ogni singolo componente.

Configurazione automatica (scelta consigliata) automated-setup

TIP

In caso di problemi con la configurazione automatica, segui i passaggi manuali di seguito.

Il comando app-setup automatizza il processo di configurazione dell'area di lavoro, inclusa la creazione di un progetto Adobe Developer Console, l'aggiunta delle API richieste, la configurazione di Adobe I/O CLI, la clonazione del kit di avvio, la connessione dell'area di lavoro locale e l'installazione degli strumenti di IA per l'estensibilità.

Il comando app-setup ti guida attraverso i seguenti passaggi:

Selezione o creazione di un progetto Adobe Developer Console con le API richieste
Configurazione di Adobe I/O CLI con l'organizzazione, il progetto e l'area di lavoro
Clonazione del kit di avvio appropriato e configurazione del progetto
Configurazione dell’ambiente e connessione dell’area di lavoro locale all’area di lavoro remota
Installazione degli strumenti di estensibilità di Commerce e competenze dell’agente di codifica

Esegui il comando seguente e segui i prompt interattivi:

aio commerce extensibility app-setup

Al termine del comando, accedi alla directory del progetto e riavvia l’agente di codifica per caricare i nuovi strumenti e le nuove competenze MCP. Se l'esercitazione richiede una vetrina, eseguire nuovamente il comando e selezionare il kit di avvio AEM Boilerplate Commerce.

L'installazione di esempio seguente mostra i prompt interattivi e l'output per il kit di avvio per l'estrazione.

Esempio di installazione (kit di avvio di checkout)

code language-shell-session

code language-shell-session
aio commerce extensibility app-setup 🚀 Adobe Commerce Extensibility App Setup ✔ Logged in 📁 Working directory: /Users/username/projects/my-commerce-project ✔ Which starter kit would you like to use? Checkout Starter Kit ✔ Enter a name for your project directory: my-extension ✔ Which coding agent would you like to install the skills for? Cursor 📦 Cloning Checkout Starter Kit... ✔ Repository cloned Using npm (package-lock.json found) ✔ Dependencies installed 📋 Current Adobe I/O Console configuration: Org: My Organization (1234567) Project: My Commerce Project (1234567890123456789) Workspace: Stage (9876543210987654321) ✔ Do you want to continue with this configuration? (Answer "No" to select a different org/project/workspace) No 🔧 Selecting Adobe I/O Console org, project, and workspace... ? Select Org: My Organization Org selected My Organization You are currently in: 1. Org: My Organization 2. Project: <no project selected> 3. Workspace: <no workspace selected> ? Select Project: My Commerce Project Project selected : My Commerce Project You are currently in: 1. Org: My Organization 2. Project: My Commerce Project 3. Workspace: <no workspace selected> ? Select Workspace: Stage Workspace selected Stage You are currently in: 1. Org: My Organization 2. Project: My Commerce Project 3. Workspace: Stage ✅ Console configured: Org: My Organization Project: My Commerce Project Workspace: Stage 🔐 Configuring workspace credentials and services... ✔ Workspace configuration loaded ✔ OAuth server-to-server credentials already configured ✔ All required services available in organization ✔ Subscribed to: Adobe Commerce as a Cloud Service 📋 Configuring Checkout Starter Kit... Creating .env from env.dist... ✔ Select tenant (type to search) My Commerce Instance: https://<region>.api.commerce.adobe.com/<tenant-id>/graphql ✔ Commerce instance configured ✔ Enter the event prefix for your workspace: my-prefix ✔ Workspace IDs configured ✔ OAuth credentials configured ✔ Checkout Starter Kit configured 🔧 Installing Commerce Extensibility tools and agent skills... ✔ Commerce Extensibility tools installed 🎉 App setup complete! 📁 Project directory: /Users/username/projects/my-commerce-project/my-extension Next steps: 1. cd into your project directory 2. Restart your coding agent to load the Commerce Extensibility tools and skills

aio commerce extensibility app-setup

🚀 Adobe Commerce Extensibility App Setup

✔ Logged in
📁 Working directory: /Users/username/projects/my-commerce-project

✔ Which starter kit would you like to use? Checkout Starter Kit
✔ Enter a name for your project directory: my-extension
✔ Which coding agent would you like to install the skills for? Cursor

📦 Cloning Checkout Starter Kit...
   ✔ Repository cloned
   Using npm (package-lock.json found)
   ✔ Dependencies installed

📋 Current Adobe I/O Console configuration:
   Org: My Organization (1234567)
   Project: My Commerce Project (1234567890123456789)
   Workspace: Stage (9876543210987654321)
✔ Do you want to continue with this configuration? (Answer "No" to select a different org/project/workspace)
No

🔧 Selecting Adobe I/O Console org, project, and workspace...

? Select Org: My Organization
Org selected My Organization
You are currently in:
1. Org: My Organization
2. Project: <no project selected>
3. Workspace: <no workspace selected>

? Select Project: My Commerce Project
Project selected : My Commerce Project
You are currently in:
1. Org: My Organization
2. Project: My Commerce Project
3. Workspace: <no workspace selected>

? Select Workspace: Stage
Workspace selected Stage
You are currently in:
1. Org: My Organization
2. Project: My Commerce Project
3. Workspace: Stage

✅ Console configured:
   Org: My Organization
   Project: My Commerce Project
   Workspace: Stage

🔐 Configuring workspace credentials and services...
   ✔ Workspace configuration loaded
   ✔ OAuth server-to-server credentials already configured
   ✔ All required services available in organization
   ✔ Subscribed to: Adobe Commerce as a Cloud Service

📋 Configuring Checkout Starter Kit...
   Creating .env from env.dist...
✔ Select tenant (type to search) My Commerce Instance:
https://<region>.api.commerce.adobe.com/<tenant-id>/graphql
   ✔ Commerce instance configured
✔ Enter the event prefix for your workspace: my-prefix
   ✔ Workspace IDs configured
   ✔ OAuth credentials configured
   ✔ Checkout Starter Kit configured

🔧 Installing Commerce Extensibility tools and agent skills...
   ✔ Commerce Extensibility tools installed

🎉 App setup complete!

📁 Project directory: /Users/username/projects/my-commerce-project/my-extension

Next steps:
   1. cd into your project directory
   2. Restart your coding agent to load the Commerce Extensibility tools and skills

Impostazione manuale manual-setup

Nelle sezioni seguenti viene descritto come impostare manualmente ogni componente dell’area di lavoro di estensibilità. Segui questi passaggi se preferisci la configurazione manuale o se riscontri problemi con la configurazione automatica.

Prerequisiti di Adobe Developer Console

Configura un progetto in Adobe Developer Console con le API e le credenziali richieste.

Passa a Adobe Developer Console.
Accedi utilizzando l’e-mail e la password.

Crea un nuovo progetto

Crea un progetto App Builder in Adobe Developer Console per ospitare la tua estensione.

Passa a Adobe Developer Console.
Fare clic su Create project from a template.
Selezionare il modello App Builder.
Immettere Project Title e App Name.
Verificare che la casella di controllo Include Runtime sia contrassegnata.

{width="600" modal="regular"}
Fare clic su Save.

Aggiungere API all’area di lavoro

Aggiungi le API richieste all’area di lavoro di Stage per la gestione degli eventi e l’integrazione con Commerce.

Fare clic sull'area di lavoro Stage e quindi ripetere i passaggi seguenti per ogni API.

{width="600" modal="regular"}
Fare clic su Add Service e selezionare API.
Seleziona una delle seguenti API. Ripeti questo processo per ogni API elencata di seguito:
- Filtro Adobe Services:
  - I/O Management API
  - API I/O Events
- Filtro Experience Cloud:
  - API Adobe I/O Events for Adobe Commerce
Fare clic su Next.
Fare clic su Save configured API.
Ripeti i passaggi precedenti fino a aggiungere tutte le API all’area di lavoro.

{width="600" modal="regular"}

Configurare Adobe I/O CLI

Connetti Adobe I/O CLI all'organizzazione, al progetto e all'area di lavoro.

Cancella eventuali configurazioni esistenti:

code language-bash
`aio config clear`

Accedi utilizzando Adobe I/O CLI:

code language-bash
`aio auth login -f`

Seleziona l’organizzazione, il progetto e l’area di lavoro utilizzando ciascuno dei seguenti comandi:

code language-bash
`aio console org select`

code language-bash
`aio console project select`

code language-bash
`aio console workspace select`

Terminale che mostra la selezione del progetto e dell'area di lavoro dell'organizzazione CLI di Adobe I/O {width="600" modal="regular"}

Clonare i kit di avvio

Clona uno dei seguenti archivi di Commerce Starter Kit per l’estensione che stai creando e prepara il progetto:

Kit di avvio dell’integrazione:

git clone https://github.com/adobe/commerce-integration-starter-kit.git extension
cd extension

Kit di avvio per il pagamento:

git clone https://github.com/adobe/commerce-checkout-starter-kit.git extension
cd extension

Kit di avvio dell'integrazione

Creare un file .env

Creare il file di configurazione dell’ambiente:

code language-bash
`cp env.dist .env`

Apri il file .env in un editor di testo e aggiungi le seguenti credenziali OAuth:

code language-bash
`OAUTH_CLIENT_ID= OAUTH_CLIENT_SECRET= OAUTH_TECHNICAL_ACCOUNT_ID= OAUTH_TECHNICAL_ACCOUNT_EMAIL= OAUTH_ORG_ID=`

Copiare questi valori dalla pagina Credential details in Developer Console facendo clic sulla scheda OAuth Server-to-Server nell'area di lavoro.

Pagina credenziali server-to-server OAuth in Adobe Developer Console {width="600" modal="regular"}

Aggiungere la configurazione Commerce

Aggiungi i seguenti dettagli dell'istanza di Commerce al file .env:

code language-bash
`COMMERCE_BASE_URL= COMMERCE_GRAPHQL_ENDPOINT=`

Per trovare questi valori:

Passa a istanze del servizio Commerce Cloud.
Fai clic sull’icona delle informazioni accanto all’istanza.
Copiare l'endpoint REST come COMMERCE_BASE_URL.
Copiare l'endpoint GraphQL come COMMERCE_GRAPHQL_ENDPOINT.

Impostare il prefisso dell’evento

Imposta un valore temporaneo per il prefisso dell'evento:

code language-bash
`EVENT_PREFIX=test`

Scarica la configurazione dell’area di lavoro

Esegui il comando seguente per scaricare il file di configurazione dell’area di lavoro:

code language-bash
`aio console workspace download workspace.json`

Copiare il file di configurazione dell'area di lavoro nella directory scripts:

code language-bash
`cp workspace.json scripts/`

Connetti l'area di lavoro locale all'area di lavoro remota

Collega il progetto locale all’area di lavoro remota:

code language-bash
`aio app use workspace.json -m`

Terminale che mostra la connessione all'area di lavoro riuscita con il comando aio app use {width="600" modal="regular"}

Kit di avvio estrazione

Connetti area di lavoro locale a area di lavoro remota

Collega il progetto locale all’area di lavoro remota. Dalla directory principale del progetto (la cartella extension), eseguire:

code language-bash
`aio app use --merge`

Quando richiesto, scegli l’opzione che utilizza l’organizzazione, il progetto e l’area di lavoro selezionati durante la configurazione di Adobe I/O CLI. In questo modo la configurazione dell’area di lavoro viene scritta nell’app in modo che l’area di lavoro venga utilizzata sia per la distribuzione che per lo sviluppo locale.

Terminale che mostra la connessione all'area di lavoro riuscita con il comando aio app use {width="600" modal="regular"}

Installare gli strumenti di extensibility AI

Questo processo crea la configurazione MCP (.<agent>/mcp.json), la directory delle abilità (.<agent>/skills/) e aggiunge AGENTS.md alla directory principale del progetto. Verrà richiesto di scegliere un kit di avvio, un agente di codifica e un gestore di pacchetti.

Impostare gli strumenti di sviluppo assistito da IA nella cartella extension utilizzando i seguenti comandi:

code language-bash
`cd extension`

code language-bash
`aio commerce extensibility tools-setup`

Terminale che mostra l'output del comando di installazione degli strumenti di estensibilità AI {width="600" modal="regular"}

Al termine dell’installazione, riavvia l’agente di codifica per consentirgli di caricare i nuovi strumenti e le nuove competenze MCP. Gli strumenti Commerce App Builder sono ora disponibili nel tuo ambiente.

note note

note note
NOTE
Se viene visualizzato un avviso che indica che non sono state trovate abilità per il kit di avvio, si è verificato un errore, spesso perché la configurazione veniva eseguita in una cartella diversa da quella in cui è stato clonato il kit di avvio. Eseguire `aio commerce extensibility tools-setup` dalla cartella `extension` (radice del progetto del kit di avvio) e selezionare il kit di avvio appropriato quando richiesto.

NOTE

Se viene visualizzato un avviso che indica che non sono state trovate abilità per il kit di avvio, si è verificato un errore, spesso perché la configurazione veniva eseguita in una cartella diversa da quella in cui è stato clonato il kit di avvio. Eseguire aio commerce extensibility tools-setup dalla cartella extension (radice del progetto del kit di avvio) e selezionare il kit di avvio appropriato quando richiesto.

Terminale che mostra la configurazione degli strumenti di estensibilità AI con il kit di avvio selezionato {width="600" modal="regular"}

Configurazione manuale della vetrina

In questa sezione viene descritto come configurare manualmente la vetrina per l'esercitazione sulle estensioni delle valutazioni e altre esercitazioni della vetrina.

Per configurare automaticamente la vetrina, eseguire il comando app-setup descritto nella sezione Installazione automatica e selezionare il kit di avvio AEM Boilerplate Commerce.

Prerequisiti

I seguenti elementi sono necessari per completare la sezione storefront del tutorial sull'estensione delle valutazioni e visualizzare le valutazioni del prodotto nel tuo store.

Google Chrome - Necessario per testare la vetrina
Progetto vetrina connesso all'istanza Commerce. Se non disponi di un progetto storefront, segui i passaggi descritti in Creare una vetrina, inclusa la sezione Collegare l'archivio ai dati di e-commerce.

Clona l’archivio della vetrina

Apri il terminale e clona l’archivio:

git clone https://github.com/hlxsites/aem-boilerplate-commerce.git storefront
cd storefront

Installare le dipendenze

Installare le dipendenze del progetto:

npm install

Installare gli strumenti di IA per la vetrina

Configurare gli strumenti di sviluppo assistiti da IA nella cartella storefront.

Esegui il comando seguente dalla directory principale del progetto boilerplate. Il comando installa il pacchetto @adobe-commerce/commerce-extensibility-tools come dipendenza di sviluppo, copia i file delle abilità nella directory delle abilità dell'agente e configura MCP (Model Context Protocol) in modo che l'agente possa accedere agli strumenti di ricerca della documentazione di Commerce.

aio commerce extensibility tools-setup

Il comando illustra due prompt:

Selezionare un kit di avvio. Scegliere AEM Boilerplate Commerce.
Selezionare l'agente di codifica — Scegliere l'agente dall'elenco degli agenti supportati.

recommendation-more-help

8562d99f-dbeb-485e-bae7-5e82fa87f463