Adobe Experience Manager Assets casi d’uso per sviluppatori, API e materiale di riferimento assets-cloud-service-apis
L’articolo contiene consigli, materiali di riferimento e risorse per gli sviluppatori di Assets as a Cloud Service. Include un nuovo modulo di caricamento delle risorse, un riferimento API e informazioni sul supporto fornito nei flussi di lavoro di post-elaborazione.
Experience Manager Assets API e operazioni use-cases-and-apis
Assets as a Cloud Service fornisce diverse API per interagire in modo programmatico con le risorse digitali. Ogni API supporta casi d’uso specifici, come indicato nella tabella seguente. Il Assets interfaccia utente, Experience Manager app desktop e Adobe Asset Link supporta tutte o alcune delle operazioni.
Caricamento risorse asset-upload
In entrata Experience Manager as a Cloud Service, puoi caricare direttamente le risorse nell’archiviazione cloud utilizzando l’API HTTP. Di seguito sono riportati i passaggi per caricare un file binario. Esegui questi passaggi in un’applicazione esterna e non all’interno del Experience Manager JVM
- Inviare una richiesta HTTP. Informa Experience Manageo la distribuzione dell’intento di caricare un nuovo binario.
- PUT il contenuto del file binario a uno o più URI forniti dalla richiesta di avvio.
- Inviare una richiesta HTTP per informare il server che il contenuto del binario è stato caricato correttamente.
L’approccio offre una gestione scalabile e più performante dei caricamenti di risorse. Le differenze rispetto a Experience Manager 6.5 sono:
- I file binari non vengono attraversati Experience Manager, che ora coordina semplicemente il processo di caricamento con l’archiviazione cloud binaria configurata per la distribuzione.
- L’archiviazione cloud binaria funziona con una rete CDN (Content Delivery Network) o Edge. Una rete CDN seleziona un endpoint di caricamento più vicino a un client. Quando i dati vengono trasferiti a una distanza inferiore da un endpoint vicino, le prestazioni di caricamento e l’esperienza utente migliorano, in particolare per i team distribuiti geograficamente.
Avvia caricamento initiate-upload
Invia una richiesta HTTP POST alla cartella desiderata. Le risorse vengono create o aggiornate in questa cartella. Includi il selettore .initiateUpload.json
per indicare che la richiesta deve avviare il caricamento di un file binario. Ad esempio, il percorso della cartella in cui deve essere creata la risorsa è /assets/folder
. La richiesta POST è POST https://[aem_server]:[port]/content/dam/assets/folder.initiateUpload.json
.
Il tipo di contenuto del corpo della richiesta deve essere application/x-www-form-urlencoded
dati del modulo, contenenti i seguenti campi:
(string) fileName
: obbligatorio. Nome della risorsa così come appare in Experience Manager.(number) fileSize
: obbligatorio. Dimensione file, in byte, della risorsa caricata.
È possibile utilizzare una singola richiesta per avviare caricamenti per più file binari, purché ogni file binario contenga i campi obbligatori. In caso di esito positivo, la richiesta risponde con un 201
il codice di stato e un corpo contenente i dati JSON nel formato seguente:
{
"completeURI": "(string)",
"folderPath": "(string)",
"files": [
{
"fileName": "(string)",
"mimeType": "(string)",
"uploadToken": "(string)",
"uploadURIs": [
"(string)"
],
"minPartSize": (number),
"maxPartSize": (number)
}
]
}
completeURI
(stringa): chiama questo URI al termine del caricamento del binario. L’URI può essere assoluto o relativo e i client devono essere in grado di gestirlo. Il valore può essere"https://[aem_server]:[port]/content/dam.completeUpload.json"
o"/content/dam.completeUpload.json"
Consulta caricamento completo.folderPath
(stringa): percorso completo della cartella in cui viene caricato il file binario.(files)
(matrice): Elenco di elementi la cui lunghezza e ordine corrispondono alla lunghezza e all'ordine dell'elenco di informazioni binarie fornite nella richiesta di avvio.fileName
(stringa): nome del file binario corrispondente, come specificato nella richiesta di avvio. Questo valore deve essere incluso nella richiesta completa.mimeType
(stringa): tipo mime del file binario corrispondente, come specificato nella richiesta di avvio. Questo valore deve essere incluso nella richiesta completa.uploadToken
(stringa): token di caricamento per il file binario corrispondente. Questo valore deve essere incluso nella richiesta completa.uploadURIs
(matrice): elenco di stringhe i cui valori sono URI completi in cui caricare il contenuto del binario (vedere Carica binario).minPartSize
(numero): Lunghezza minima, in byte, dei dati che possono essere forniti a uno qualsiasi deiuploadURIs
, se è presente più di un URI.maxPartSize
(numero): La lunghezza massima, in byte, dei dati che possono essere forniti a uno qualsiasi deiuploadURIs
, se è presente più di un URI.
Carica binario upload-binary
L’output dell’avvio di un caricamento include uno o più valori URI di caricamento. Se viene fornito più di un URI, il client può suddividere il binario in parti ed effettuare richieste PUT di ciascuna parte agli URI di caricamento forniti, nell'ordine. Se scegli di dividere il binario in parti, attieniti alle seguenti linee guida:
- Ciascuna parte, ad eccezione dell'ultima, deve essere di dimensioni pari o superiori a
minPartSize
. - Ogni parte deve avere una dimensione minore o uguale a
maxPartSize
. - Se le dimensioni del file binario superano
maxPartSize
, dividi il binario in parti per caricarlo. - Non è necessario utilizzare tutti gli URI.
Se la dimensione del file binario è minore o uguale a maxPartSize
, è invece possibile caricare l’intero binario in un singolo URI di caricamento. Se viene fornito più di un URI di caricamento, utilizza il primo e ignora il resto. Non è necessario utilizzare tutti gli URI.
I nodi edge CDN consentono di accelerare il caricamento richiesto di dati binari.
Il modo più semplice per farlo è utilizzare il valore di maxPartSize
come dimensione della parte. Il contratto API garantisce che siano presenti URI di caricamento sufficienti per caricare il file binario se utilizzi questo valore come dimensione della parte. Per eseguire questa operazione, dividere il binario in parti di dimensione maxPartSize
, utilizzando un URI per ogni parte, nell'ordine. La parte finale può essere di qualsiasi dimensione minore o uguale a maxPartSize
. Si supponga, ad esempio, che la dimensione totale del file binario sia 20.000 byte, minPartSize
è di 5.000 byte, maxPartSize
è di 8.000 byte e il numero di URI di caricamento è 5. Esegui i passaggi seguenti:
- Carica i primi 8.000 byte del file binario utilizzando l’URI del primo caricamento.
- Carica i secondi 8.000 byte del file binario utilizzando il secondo URI di caricamento.
- Carica gli ultimi 4.000 byte del file binario utilizzando il terzo URI di caricamento. Poiché questa è la parte finale, non è necessario che sia maggiore di
minPartSize
. - Non è necessario utilizzare gli ultimi due URI di caricamento. Puoi ignorarli.
Un errore comune consiste nel calcolare la dimensione della parte in base al numero di URI di caricamento forniti dall’API. Il contratto API non garantisce che questo approccio funzioni e può effettivamente causare dimensioni delle parti che non rientrano nell’intervallo tra minPartSize
e maxPartSize
. Questo può causare errori di caricamento binario.
Anche in questo caso, il modo più semplice e sicuro è quello di utilizzare semplicemente parti di dimensione uguale a maxPartSize
.
Se il caricamento ha esito positivo, il server risponde a ogni richiesta con un 201
codice di stato.
Caricamento completo complete-upload
Dopo aver caricato tutte le parti di un file binario, invia una richiesta HTTP POST all’URI completo fornito dai dati di avvio. Il tipo di contenuto del corpo della richiesta deve essere application/x-www-form-urlencoded
dati del modulo, contenenti i seguenti campi.
fileName
mimeType
uploadToken
createVersion
True
ed esiste già una risorsa con il nome specificato, quindi Experience Manager crea una nuova versione della risorsa.versionLabel
versionComment
replace
True
ed esiste già una risorsa con il nome specificato, Experience Manager elimina la risorsa e la ricrea.uploadDuration
fileSize
createVersion
né replace
è specificato, quindi Experience Manager aggiorna la versione corrente della risorsa con il nuovo binario.Analogamente al processo di avvio, i dati completi della richiesta possono contenere informazioni relative a più file.
Il processo di caricamento di un file binario non viene eseguito finché non viene richiamato l’URL completo del file. Una risorsa viene elaborata al termine del processo di caricamento. L’elaborazione non viene avviata anche se il file binario della risorsa è stato caricato completamente, ma il processo di caricamento non è stato completato. Se il caricamento ha esito positivo, il server risponde con un 200
codice di stato.
Esempio di script della shell per caricare le risorse in AEM as a Cloud Service upload-assets-shell-script
Il processo di caricamento a più passaggi per l’accesso binario diretto all’interno di AEM as a Cloud Service è illustrato nell’esempio seguente shell-script aem-upload.sh
:
#!/bin/bash
# Check if pv is installed
if ! command -v pv &> /dev/null; then
echo "Error: 'pv' command not found. Please install it before running the script."
exit 1
fi
# Check if jq is installed
if ! command -v jq &> /dev/null; then
echo "Error: 'jq' command not found. Please install it before running the script."
exit 1
fi
# Set DEBUG to true to enable debug statements
DEBUG=true
# Function for printing debug statements
function debug() {
if [ "${DEBUG}" = true ]; then
echo "[DEBUG] $1"
fi
}
# Function to check if a file exists
function file_exists() {
[ -e "$1" ]
}
# Function to check if a path is a directory
function is_directory() {
[ -d "$1" ]
}
# Check if the required number of parameters are provided
if [ "$#" -ne 4 ]; then
echo "Usage: $0 <aem-url> <asset-folder> <file-to-upload> <bearer-token>"
exit 1
fi
AEM_URL="$1"
ASSET_FOLDER="$2"
FILE_TO_UPLOAD="$3"
BEARER_TOKEN="$4"
# Extracting file name or folder name from the file path
NAME=$(basename "${FILE_TO_UPLOAD}")
# Step 1: Check if "file-to-upload" is a folder
if is_directory "${FILE_TO_UPLOAD}"; then
echo "Uploading files from the folder recursively..."
# Recursively upload files in the folder
find "${FILE_TO_UPLOAD}" -type f | while read -r FILE_PATH; do
FILE_NAME=$(basename "${FILE_PATH}")
debug "Uploading file: ${FILE_PATH}"
# You can choose to initiate upload for each file here
# For simplicity, let's assume you use the same ASSET_FOLDER for all files
./aem-upload.sh "${AEM_URL}" "${ASSET_FOLDER}" "${FILE_PATH}" "${BEARER_TOKEN}"
done
else
# "file-to-upload" is a single file
FILE_NAME="${NAME}"
# Step 2: Calculate File Size
FILE_SIZE=$(stat -c %s "${FILE_TO_UPLOAD}")
# Step 3: Initiate Upload
INITIATE_UPLOAD_ENDPOINT="${AEM_URL}/content/dam/${ASSET_FOLDER}.initiateUpload.json"
debug "Initiating upload..."
debug "Initiate Upload Endpoint: ${INITIATE_UPLOAD_ENDPOINT}"
debug "File Name: ${FILE_NAME}"
debug "File Size: ${FILE_SIZE}"
INITIATE_UPLOAD_RESPONSE=$(curl -X POST \
-H "Authorization: Bearer ${BEARER_TOKEN}" \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
-d "fileName=${FILE_NAME}" \
-d "fileSize=${FILE_SIZE}" \
${INITIATE_UPLOAD_ENDPOINT})
# Continue with the rest of the script...
fi
# Check if the response body contains the specified HTML content for a 404 error
if echo "${INITIATE_UPLOAD_RESPONSE}" | grep -q "<title>404 Specified folder not found</title>"; then
echo "Folder not found. Creating the folder..."
# Attempt to create the folder
CREATE_FOLDER_ENDPOINT="${AEM_URL}/api/assets/${ASSET_FOLDER}"
debug "Creating folder..."
debug "Create Folder Endpoint: ${CREATE_FOLDER_ENDPOINT}"
CREATE_FOLDER_RESPONSE=$(curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${BEARER_TOKEN}" \
-d '{"class":"'${ASSET_FOLDER}'","properties":{"title":"'${ASSET_FOLDER}'"}}' \
${CREATE_FOLDER_ENDPOINT})
# Check the response code and inform the user accordingly
STATUS_CODE_CREATE_FOLDER=$(echo "${CREATE_FOLDER_RESPONSE}" | jq -r '.properties."status.code"')
case ${STATUS_CODE_CREATE_FOLDER} in
201)
echo "Folder created successfully. Initiating upload again..."
# Retry Initiate Upload after creating the folder
INITIATE_UPLOAD_RESPONSE=$(curl -X POST \
-H "Authorization: Bearer ${BEARER_TOKEN}" \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
-d "fileName=${FILE_NAME}" \
-d "fileSize=${FILE_SIZE}" \
${INITIATE_UPLOAD_ENDPOINT})
;;
409)
echo "Error: Folder already exists."
;;
412)
echo "Error: Precondition failed. Root collection cannot be found or accessed."
exit 1
;;
500)
echo "Error: Internal Server Error. Something went wrong."
exit 1
;;
*)
echo "Error: Unexpected response code ${STATUS_CODE_CREATE_FOLDER}"
exit 1
;;
esac
fi
# Extracting values from the response
FOLDER_PATH=$(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.folderPath')
UPLOAD_URIS=($(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.files[0].uploadURIs[]'))
UPLOAD_TOKEN=$(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.files[0].uploadToken')
MIME_TYPE=$(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.files[0].mimeType')
MIN_PART_SIZE=$(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.files[0].minPartSize')
MAX_PART_SIZE=$(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.files[0].maxPartSize')
COMPLETE_URI=$(echo "${INITIATE_UPLOAD_RESPONSE}" | jq -r '.completeURI')
# Extracting "Affinity-cookie" from the response headers
AFFINITY_COOKIE=$(echo "${INITIATE_UPLOAD_RESPONSE}" | grep -i 'Affinity-cookie' | awk '{print $2}')
debug "Folder Path: ${FOLDER_PATH}"
debug "Upload Token: ${UPLOAD_TOKEN}"
debug "MIME Type: ${MIME_TYPE}"
debug "Min Part Size: ${MIN_PART_SIZE}"
debug "Max Part Size: ${MAX_PART_SIZE}"
debug "Complete URI: ${COMPLETE_URI}"
debug "Affinity Cookie: ${AFFINITY_COOKIE}"
if $DEBUG; then
i=1
for UPLOAD_URI in "${UPLOAD_URIS[@]}"; do
debug "Upload URI $i: "$UPLOAD_URI
i=$((i+1))
done
fi
# Calculate the number of parts needed
NUM_PARTS=$(( (FILE_SIZE + MAX_PART_SIZE - 1) / MAX_PART_SIZE ))
debug "Number of Parts: $NUM_PARTS"
# Calculate the part size for the last chunk
LAST_PART_SIZE=$(( FILE_SIZE % MAX_PART_SIZE ))
if [ "${LAST_PART_SIZE}" -eq 0 ]; then
LAST_PART_SIZE=${MAX_PART_SIZE}
fi
# Step 4: Upload binary to the blob store in parts
PART_NUMBER=1
for i in $(seq 1 $NUM_PARTS); do
PART_SIZE=${MAX_PART_SIZE}
if [ ${PART_NUMBER} -eq ${NUM_PARTS} ]; then
PART_SIZE=${LAST_PART_SIZE}
debug "Last part size: ${PART_SIZE}"
fi
PART_FILE="/tmp/${FILE_NAME}_part${PART_NUMBER}"
# Creating part file
SKIP=$((PART_NUMBER - 1))
SKIP=$((MAX_PART_SIZE * SKIP))
dd if="${FILE_TO_UPLOAD}" of="${PART_FILE}" bs="${PART_SIZE}" skip="${SKIP}" count="${PART_SIZE}" iflag=skip_bytes,count_bytes > /dev/null 2>&1
debug "Creating part file: ${PART_FILE} with size ${PART_SIZE}, skipping first ${SKIP} bytes."
UPLOAD_URI=${UPLOAD_URIS[$PART_NUMBER-1]}
debug "Uploading part ${PART_NUMBER}..."
debug "Part Size: $PART_SIZE"
debug "Part File: ${PART_FILE}"
debug "Part File Size: $(stat -c %s "${PART_FILE}")"
debug "Upload URI: ${UPLOAD_URI}"
# Upload the part in the background
if command -v pv &> /dev/null; then
pv "${PART_FILE}" | curl --progress-bar -X PUT --data-binary "@-" "${UPLOAD_URI}" &
else
curl -# -X PUT --data-binary "@${PART_FILE}" "${UPLOAD_URI}" &
fi
PART_NUMBER=$((PART_NUMBER + 1))
done
# Wait for all background processes to finish
wait
# Step 5: Complete the upload in AEM
COMPLETE_UPLOAD_ENDPOINT="${AEM_URL}${COMPLETE_URI}"
debug "Completing the upload..."
debug "Complete Upload Endpoint: ${COMPLETE_UPLOAD_ENDPOINT}"
RESPONSE=$(curl -X POST \
-H "Authorization: Bearer ${BEARER_TOKEN}" \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
-H "Affinity-cookie: ${AFFINITY_COOKIE}" \
--data-urlencode "uploadToken=${UPLOAD_TOKEN}" \
--data-urlencode "fileName=${FILE_NAME}" \
--data-urlencode "mimeType=${MIME_TYPE}" \
"${COMPLETE_UPLOAD_ENDPOINT}")
debug $RESPONSE
echo "File upload completed successfully."
Libreria di caricamento open-source open-source-upload-library
Per ulteriori informazioni sugli algoritmi di caricamento o per creare script e strumenti di caricamento, Adobe fornisce librerie e strumenti open-source:
API di caricamento risorse obsolete deprecated-asset-upload-api
Il nuovo metodo di caricamento è supportato solo per Adobe Experience Manager as a Cloud Service. Le API di Adobe Experience Manager 6.5 sono obsolete. I metodi relativi al caricamento o all’aggiornamento delle risorse o delle rappresentazioni (qualsiasi caricamento binario) sono obsoleti nelle seguenti API:
- API HTTP EXPERIENCE MANAGER ASSETS
AssetManager
API Java, likeAssetManager.createAsset(..)
,AssetManager.createAssetForBinary(..)
,AssetManager.getAssetForBinary(..)
,AssetManager.removeAssetForBinary(..)
,AssetManager.createOrUpdateAsset(..)
,AssetManager.createOrReplaceAsset(..)
Flussi di lavoro di elaborazione e post-elaborazione delle risorse post-processing-workflows
In entrata Experience Manager, l’elaborazione delle risorse si basa su Profili elaborazione configurazione che utilizza microservizi per risorse. L’elaborazione non richiede estensioni per sviluppatori.
Per la configurazione del flusso di lavoro di post-elaborazione, utilizza i flussi di lavoro standard con estensioni e passaggi personalizzati.
Supporto dei passaggi del flusso di lavoro nella post-elaborazione del flusso di lavoro post-processing-workflows-steps
Se esegui l’aggiornamento da una versione precedente di Experience Manager, puoi utilizzare i microservizi per le risorse per elaborarle. I microservizi per le risorse native per il cloud sono più semplici da configurare e utilizzare. Alcuni passaggi del flusso di lavoro utilizzati in Aggiorna risorsa DAM nella versione precedente non sono supportati. Per ulteriori informazioni sulle classi supportate, vedere Riferimento API Java o JavaScript.
I seguenti modelli di flusso di lavoro tecnico sono sostituiti dai microservizi per le risorse oppure il supporto non è disponibile:
com.day.cq.dam.cameraraw.process.CameraRawHandlingProcess
com.day.cq.dam.core.process.CommandLineProcess
com.day.cq.dam.pdfrasterizer.process.PdfRasterizerHandlingProcess
com.day.cq.dam.core.process.AddPropertyWorkflowProcess
com.day.cq.dam.core.process.CreateSubAssetsProcess
com.day.cq.dam.core.process.DownloadAssetProcess
com.day.cq.dam.word.process.ExtractImagesProcess
com.day.cq.dam.word.process.ExtractPlainProcess
com.day.cq.dam.ids.impl.process.IDSJobProcess
com.day.cq.dam.indd.process.INDDMediaExtractProcess
com.day.cq.dam.indd.process.INDDPageExtractProcess
com.day.cq.dam.core.impl.lightbox.LightboxUpdateAssetProcess
com.day.cq.dam.pim.impl.sourcing.upload.process.ProductAssetsUploadProcess
com.day.cq.dam.core.process.SendDownloadAssetEmailProcess
com.day.cq.dam.similaritysearch.internal.workflow.smarttags.StartTrainingProcess
com.day.cq.dam.similaritysearch.internal.workflow.smarttags.TransferTrainingDataProcess
com.day.cq.dam.switchengine.process.SwitchEngineHandlingProcess
com.day.cq.dam.core.process.GateKeeperProcess
com.day.cq.dam.s7dam.common.process.DMEncodeVideoWorkflowCompletedProcess
com.day.cq.dam.core.process.DeleteImagePreviewProcess
com.day.cq.dam.video.FFMpegTranscodeProcess
com.day.cq.dam.core.process.ThumbnailProcess
com.day.cq.dam.video.FFMpegThumbnailProcess
com.day.cq.dam.core.process.CreateWebEnabledImageProcess
com.day.cq.dam.core.process.CreatePdfPreviewProcess
com.day.cq.dam.s7dam.common.process.VideoUserUploadedThumbnailProcess
com.day.cq.dam.s7dam.common.process.VideoThumbnailDownloadProcess
com.day.cq.dam.s7dam.common.process.VideoProxyServiceProcess
com.day.cq.dam.scene7.impl.process.Scene7UploadProcess
com.day.cq.dam.s7dam.common.process.S7VideoThumbnailProcess
com.day.cq.dam.core.process.MetadataProcessorProcess
com.day.cq.dam.core.process.AssetOffloadingProcess
com.adobe.cq.dam.dm.process.workflow.DMImageProcess
Consulta anche