Asset Compute Service HTTP API
- Ämnen:
- Asset Compute Microservices
Skapat för:
- Utvecklare
API:t används endast i utvecklingssyfte. API:t anges som ett sammanhang när du utvecklar anpassade program. Adobe Experience Manager som Cloud Service använder API:t för att skicka bearbetningsinformationen till ett anpassat program. Mer information finns i Använda resursmikrotjänster och Bearbeta profiler.
Alla klienter för HTTP-API:t Asset Compute Service måste följa detta högnivåflöde:
-
En klient har etablerats som ett Adobe Developer Console-projekt i en IMS-organisation. Varje separat klient (system eller miljö) kräver ett eget separat projekt för att separera händelsedataflödet.
-
En klient genererar en åtkomsttoken för det tekniska kontot med hjälp av JWT-autentisering (tjänstkonto).
-
En klient anropar bara
/register
en gång för att hämta journal-URL:en. -
En klient anropar
/process
för varje resurs som den vill generera återgivningar för. Anropet är asynkront. -
En klient avsöker regelbundet journalen för att ta emot händelser. Den tar emot händelser för varje begärd återgivning när återgivningen har bearbetats (
rendition_created
händelsetyp) eller om det finns ett fel (rendition_failed
händelsetyp).
Modulen adobe-asset-compute-client gör det enkelt att använda API:t i Node.js-koden.
Autentisering och auktorisering
Alla API:er kräver åtkomsttokenautentisering. Förfrågningarna måste ange följande rubriker:
-
Authorization
-huvud med bearer-token, som är den tekniska kontotoken, har tagits emot via JWT exchange från Adobe Developer Console-projekt. omfattningarna beskrivs nedan. -
x-gw-ims-org-id
-huvud med IMS-organisations-ID. -
x-api-key
med klient-ID från projektet Adobe Developers Console.
Omfång
Kontrollera följande scope för åtkomsttoken:
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
Dessa omfattningar kräver att projektet Adobe Developer Console prenumererar på tjänsterna Asset Compute
, I/O Events
och I/O Management API
. Uppdelningen av enskilda omfattningar är:
-
Grundläggande
- omfattningar:
openid,AdobeID
- omfattningar:
-
Asset compute
- metascope:
asset_compute_meta
- omfattningar:
asset_compute,read_organizations
- metascope:
-
Adobe
I/O Events
- metascope:
event_receiver_api
- omfattningar:
event_receiver,event_receiver_api
- metascope:
-
Adobe
I/O Management API
- metascope:
ent_adobeio_sdk
- omfattningar:
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- metascope:
Registrering
Varje klient för Asset Compute service - ett unikt Adobe Developer Console-projekt som prenumererar på tjänsten - måste registrera innan bearbetningen kan göras. Registreringssteget returnerar den unika händelsjournal som krävs för att hämta asynkrona händelser från återgivningsbearbetningen.
När livscykeln är slut kan en klient avregistrera.
Registrera förfrågan
Detta API-anrop konfigurerar en Asset Compute-klient och tillhandahåller händelsens journal-URL. Den här processen är en depotent åtgärd och behöver bara anropas en gång för varje klient. Den kan anropas igen för att hämta journal-URL:en.
POST
/register
Authorization
x-request-id
Registrera svar
application/json
X-Request-Id
X-Request-Id
eller en unikt genererad. Används för att identifiera förfrågningar mellan system, supportförfrågningar eller båda.journal
, ok
eller requestId
.HTTP-statuskoderna är:
-
200 lyckades: När begäran lyckades. URL:en
journal
får meddelanden om resultatet av den asynkrona bearbetning som initierats med hjälp av/process
. Den varnar omrendition_created
händelser när de har slutförts, ellerrendition_failed
händelser om processen misslyckas.{ "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401 Obehörig: inträffar när begäran inte har giltig autentisering. Ett exempel kan vara en ogiltig åtkomsttoken eller en ogiltig API-nyckel.
-
403 Otillåten: inträffar när begäran inte har giltig auktorisering. Ett exempel kan vara en giltig åtkomsttoken, men Adobe Developer Console-projektet (tekniskt konto) prenumererar inte på alla nödvändiga tjänster.
-
429 För många begäranden: inträffar när den här klienten eller på annat sätt överbelastar systemet. Klienter bör försöka igen med en exponentiell säkerhetskopiering. Brödtexten är tom.
-
4xx-fel: När det fanns något annat klientfel och registreringen misslyckades. Vanligtvis returneras ett JSON-svar som detta, men det garanteras inte för alla fel:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx-fel: inträffar när det finns något annat fel på serversidan och registreringen misslyckades. Vanligtvis returneras ett JSON-svar som detta, men det garanteras inte för alla fel:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Avregistrera förfrågan
Detta API-anrop avregistrerar en Asset Compute-klient. När avregistreringen är klar går det inte längre att anropa /process
. Om API-anropet för en oregistrerad klient eller en ännu inte registrerad klient används returneras felet 404
.
POST
/unregister
Authorization
x-request-id
Avregistrera svar
application/json
X-Request-Id
X-Request-Id
eller en unikt genererad. Används för att identifiera förfrågningar mellan system eller supportförfrågningar.ok
och requestId
.Statuskoderna är:
-
200 lyckades: inträffar när registreringen och journalen hittas och tas bort.
{ "ok": true, "requestId": "1234567890" }
-
401 Obehörig: inträffar när begäran inte har giltig autentisering. Ett exempel kan vara en ogiltig åtkomsttoken eller en ogiltig API-nyckel.
-
403 Otillåten: inträffar när begäran inte har giltig auktorisering. Ett exempel kan vara en giltig åtkomsttoken, men Adobe Developer Console-projektet (tekniskt konto) prenumererar inte på alla nödvändiga tjänster.
-
404 Det gick inte att hitta: Den här statusen visas när de angivna autentiseringsuppgifterna är oregistrerade eller ogiltiga.
{ "ok": true, "requestId": "1234567890" }
-
429 För många begäranden: inträffar när systemet är överbelastat. Klienter bör försöka igen med en exponentiell säkerhetskopiering. Brödtexten är tom.
-
4xx-fel: inträffar när det finns något annat klientfel och avregistreringen misslyckades. Vanligtvis returneras ett JSON-svar som detta, men det garanteras inte för alla fel:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx-fel: inträffar när det finns något annat fel på serversidan och registreringen misslyckades. Vanligtvis returneras ett JSON-svar som detta, men det garanteras inte för alla fel:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Bearbeta begäran
Åtgärden process
skickar ett jobb som omvandlar en källresurs till flera återgivningar, baserat på instruktionerna i begäran. Meddelanden om slutförande (händelsetyp rendition_created
) eller eventuella fel (händelsetyp rendition_failed
) skickas till en händelseljournal som måste hämtas med /register
en gång innan du kan göra ett antal /process
-begäranden. Felaktigt utformade begäranden misslyckas omedelbart med 400-felkod.
Binärfiler refereras med URL:er, som försignerade URL:er för Amazon AWS S3 eller Azure Blob Storage SAS-URL:er. Används för att både läsa source
-resursen (GET
URL:er) och skriva återgivningarna (PUT
URL:er). Klienten ansvarar för att generera dessa försignerade URL:er.
POST
/process
application/json
Authorization
x-request-id
Bearbeta begäran JSON
Begärandetexten för /process
är ett JSON-objekt med detta högnivåschema:
{
"source": "",
"renditions" : []
}
De tillgängliga fälten är:
source
string
fmt=zip
)."http://example.com/image.jpg"
source
object
fmt=zip
).{"url": "http://example.com/image.jpg", "mimeType": "image/jpeg" }
renditions
array
[{ "target": "https://....", "fmt": "png" }]
source
kan antingen vara en <string>
som ses som en URL eller en <object>
med ett extra fält. Följande varianter är lika:
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
Source objektfält
url
string
"http://example.com/image.jpg"
name
string
content-disposition
-huvudet för den binära resursen. Standardvärdet är "file"."image.jpg"
size
number
content-length
huvud för den binära resursen.10234
mimetype
string
content-type
för den binära resursen."image/jpeg"
Ett fullständigt exempel på process
-begäran
{
"source": "https://www.adobe.com/content/dam/acom/en/lobby/lobby-bg-bts2017-logged-out-1440x860.jpg",
"renditions" : [{
"name": "image.48x48.png",
"target": "https://some-presigned-put-url-for-image.48x48.png",
"fmt": "png",
"width": 48,
"height": 48
},{
"name": "image.200x200.jpg",
"target": "https://some-presigned-put-url-for-image.200x200.jpg",
"fmt": "jpg",
"width": 200,
"height": 200
},{
"name": "cqdam.xmp.xml",
"target": "https://some-presigned-put-url-for-cqdam.xmp.xml",
"fmt": "xmp"
},{
"name": "cqdam.text.txt",
"target": "https://some-presigned-put-url-for-cqdam.text.txt",
"fmt": "text"
}]
}
Processsvar
/process
-begäran returneras omedelbart med ett lyckat eller misslyckat svar baserat på den grundläggande begärandevalideringen. Faktisk bearbetning av resurser sker asynkront.
application/json
X-Request-Id
X-Request-Id
eller en unikt genererad. Används för att identifiera förfrågningar mellan system eller supportförfrågningar.ok
och requestId
.Statuskoder:
-
200 lyckades: Om begäran skickades utan fel. Svar-JSON innehåller
"ok": true
:{ "ok": true, "requestId": "1234567890" }
-
400 Ogiltig begäran: Om begäran är felaktigt strukturerad, till exempel om den saknar obligatoriska fält i JSON-nyttolasten. Svar-JSON innehåller
"ok": false
:{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
401 Obehörig: När begäran inte har giltig autentisering. Ett exempel kan vara en ogiltig åtkomsttoken eller en ogiltig API-nyckel.
-
403 Otillåten: När begäran inte har giltig auktorisering. Ett exempel kan vara en giltig åtkomsttoken, men Adobe Developer Console-projektet (tekniskt konto) prenumererar inte på alla nödvändiga tjänster.
-
429 För många begäranden: Inträffar när systemet överbelastas, antingen på grund av den här klienten eller på grund av den totala efterfrågan. Klienterna kan försöka igen med en exponentiell säkerhetskopiering. Brödtexten är tom.
-
4xx-fel: När det fanns något annat klientfel. Vanligtvis returneras ett JSON-svar som detta, men det garanteras inte för alla fel:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx-fel: När det fanns något annat serverfel. Vanligtvis returneras ett JSON-svar som detta, men det garanteras inte för alla fel:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
De flesta klienter vill antagligen försöka utföra samma begäran igen med exponentiell säkerhetskopiering vid ett fel förutom konfigurationsproblem som 401 eller 403, eller ogiltiga begäranden som 400. Förutom en vanlig hastighetsbegränsning med 429 svar kan ett tillfälligt avbrott eller en tillfällig begränsning leda till 5 x fel. Det vore då tillrådligt att försöka igen efter en viss tid.
Alla JSON-svar (om sådana finns) innehåller requestId
, som är samma värde som huvudet X-Request-Id
. Adobe rekommenderar att du läser från sidhuvudet eftersom det alltid finns. requestId
returneras också i alla händelser som rör bearbetning av begäranden som requestId
. Klienterna får inte anta något om formatet för den här strängen. Det är en ogenomskinlig strängidentifierare.
Anmäl dig till efterbearbetning
Asset Compute SDK har stöd för en uppsättning grundläggande alternativ för efterbearbetning av bilder. Anpassade arbetare kan uttryckligen välja att efterbearbeta genom att ange fältet postProcess
för återgivningsobjektet till true
.
De användningsområden som stöds är:
- Beskärning är en återgivning av en rektangel vars gränser definieras genom crop.w, crop.h, crop.x och crop.y. Beskärningsinformationen anges i återgivningsobjektets
instructions.crop
-fält. - Ändra storlek på bilder med bredden, höjden eller båda.
instructions.width
ochinstructions.height
definierar det i återgivningsobjektet. Om du bara vill ändra storlek med bredd eller höjd anger du bara ett värde. Beräkningstjänsten bevarar proportionerna. - Ange kvaliteten för en JPEG-bild.
instructions.quality
definierar det i återgivningsobjektet. En kvalitetsnivå på 100 representerar den högsta kvaliteten, medan lägre tal innebär en kvalitetsförsämring. - Skapa sammanflätade bilder.
instructions.interlace
definierar det i återgivningsobjektet. - Ställ in DPI för att justera den återgivna storleken för DPI-publicering genom att justera den skala som används på pixlarna.
instructions.dpi
definierar den i återgivningsobjektet för att ändra dpi-upplösning. Om du vill ändra storlek på bilden så att den får samma storlek med en annan upplösning använder duconvertToDpi
-instruktionerna. - Ändra bildens storlek så att dess återgivna bredd eller höjd förblir densamma som originalet vid den angivna målupplösningen (DPI).
instructions.convertToDpi
definierar det i återgivningsobjektet.
Vattenstämpelresurser
Asset Compute SDK har stöd för att lägga till en vattenstämpel i bildfilerna PNG, JPEG, TIFF och GIF. Vattenstämpeln läggs till efter återgivningsinstruktionerna i objektet watermark
på återgivningen.
Vattenstämplar görs under efterbearbetningen av återgivningen. För vattenstämpelresurser väljer den anpassade arbetaren efterbearbetning genom att ange fältet postProcess
för återgivningsobjektet till true
. Om arbetaren inte väljer att delta används inte vattenstämplar, även om vattenstämpelobjektet har angetts för återgivningsobjektet i begäran.
Återgivningsinstruktioner
Följande är tillgängliga alternativ för arrayen renditions
i /process
.
Vanliga fält
fmt
string
text
för textrahering och xmp
för att extrahera XMP metadata som xml. Se format som stödspng
worker
string
https://
-URL. Om det här fältet finns skapar ett anpassat program återgivningen. Alla andra inställda återgivningsfält används sedan i det anpassade programmet."https://1234.adobeioruntime.net
/api/v1/web
/example-custom-worker-master/worker"
target
string
http://w.com/img.jpg
target
object
Multipart-försignerad URL-överföringsinformation för den genererade återgivningen. Den här informationen gäller för AEM/Oak Direct Binary Upload med det här multipart-överföringsbeteendet.
Fält:
urls
: strängmatris, en för varje försignerad del-URLminPartSize
: den minsta storleken som ska användas för en del = urlmaxPartSize
: den största storleken som kan användas för en del = url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
Återgivningsspecifika fält
En lista över de filformat som stöds finns i Filformat som stöds.
embedBinaryLimit
number
i byteembedBinaryLimit
-gränsen placeras den på en plats i molnlagringen och bäddas inte in i händelsen.3276
width
number
200
height
number
200
Proportionerna behålls alltid om:
- Både
width
ochheight
har angetts och bilden får plats i storleken samtidigt som proportionerna behålls - Om bara
width
ellerheight
anges används motsvarande dimension för den resulterande bilden, samtidigt som proportionerna behålls - Om
width
ellerheight
inte anges används den ursprungliga bildens pixelstorlek. Det beror på källtypen. För vissa format, till exempel PDF, används en standardstorlek. Det kan finnas en maximal storleksgräns.
quality
number
1
till 100
. Gäller endast för bildåtergivningar.90
xmp
string
interlace
bool
true
. Det påverkar inte andra filformat.jpegSize
number
quality
-inställningar. Det påverkar inte andra format.dpi
number
eller object
96
eller { xdpi: 96, ydpi: 96 }
convertToDpi
number
eller object
96
eller { xdpi: 96, ydpi: 96 }
files
array
Lista över filer som ska inkluderas i ZIP-arkivet (fmt=zip
). Varje post kan antingen vara en URL-sträng eller ett objekt med fälten:
url
: URL för hämtning av filpath
: Lagra filen under den här sökvägen i ZIP
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate
string
fmt=zip
). Som standard genererar flera filer som lagras under samma sökväg i ZIP ett fel. Om duplicate
anges till ignore
sparas bara den första resursen och resten ignoreras.ignore
Vattenstämpelsspecifika fält
PNG-formatet används som vattenstämpel.
scale
number
0.0
och 1.0
. 1.0
betyder att vattenstämpeln har sin ursprungliga skala (1:1) och de lägre värdena minskar storleken på vattenstämpeln.0.5
betyder halva den ursprungliga storleken.image
url
Asynkrona händelser
När bearbetningen av en återgivning är klar eller när ett fel inträffar, skickas en händelse till Adobe I/O Events Journal
. Klienterna måste lyssna på den journal-URL som tillhandahålls via /register
. Journalsvaret innehåller en event
-matris som består av ett objekt för varje händelse, varav fältet event
innehåller den faktiska händelsens nyttolast.
Adobe I/O Events
-typen för alla händelser i Asset Compute Service är asset_compute
. Journalen prenumererar automatiskt på endast den här händelsetypen och det finns inget ytterligare krav på att filtrera baserat på händelsetypen Adobe Developer. Tjänstspecifika händelsetyper är tillgängliga i egenskapen type
för händelsen.
Händelsetyper
rendition_created
rendition_failed
Händelseattribut
date
string
*
requestId
string
*
/process
, samma som för X-Request-Id
.source
object
*
source
för /process
-begäran.userData
object
*
userData
för återgivningen från /process
-begäran om den anges.rendition
object
rendition_*
/process
.errorMessage
string
rendition_failed
Metadata
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
Felorsaker
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
. Den faktiska återgivningsstorleken är tillgänglig som metadata i repo:size
och används av klienten för att bearbeta återgivningen med rätt antal försignerade URL:er.GenericError