Asset Compute Service HTTP-API
- Onderwerpen:
- Asset Compute-microservices
Gemaakt voor:
- Ontwikkelaar
Het gebruik van de API is beperkt tot ontwikkelingsdoeleinden. De API wordt als context verstrekt wanneer het ontwikkelen van douanetoepassingen. Adobe Experience Manager als Cloud Service gebruikt de API om de verwerkingsgegevens door te geven aan een aangepaste toepassing. Voor meer informatie, zie de activamicrodiensten van het Gebruik en Profielen van de Verwerking.
Elke client van de Asset Compute Service HTTP API moet deze flow op hoog niveau volgen:
-
Een client wordt ingericht als een Adobe Developer Console -project in een IMS-organisatie. Elke afzonderlijke client (systeem of omgeving) vereist een eigen afzonderlijk project om de gegevensstroom van de gebeurtenis te scheiden.
-
Een cliënt produceert een toegangstoken voor de technische rekening gebruikend JWT (de Rekening van de Dienst) Authentificatie.
-
Een client roept
/register
slechts eenmaal aan om de journaal-URL op te halen. -
Een client roept
/process
aan voor elk element waarvoor de client uitvoeringen wil genereren. De vraag is asynchroon. -
Een cliënt pollt regelmatig het dagboek om gebeurtenissente ontvangen. Het ontvangt gebeurtenissen voor elke gevraagde vertoning wanneer de vertoning met succes wordt verwerkt (
rendition_created
gebeurtenistype) of als er een fout (rendition_failed
gebeurtenistype) is.
De adobe-asset-compute-cliëntmodule maakt het gemakkelijk om API in code Node.js te gebruiken.
Verificatie en autorisatie
Voor alle API's is verificatie van toegangstoken vereist. De verzoeken moeten de volgende kopballen plaatsen:
-
Authorization
kopbal met dragerteken, dat het technische rekeningsteken is, dat via JWT uitwisselingvan het project van Adobe Developer Console wordt ontvangen. Het werkingsgebiedwordt hieronder gedocumenteerd. -
x-gw-ims-org-id
met de IMS-organisatie-id. -
x-api-key
met de client-id van het Adobe Developers Console -project.
Segmenten
Verzeker het volgende werkingsgebied voor het toegangstoken:
openid
AdobeID
asset_compute
read_organizations
event_receiver
event_receiver_api
adobeio_api
additional_info.roles
additional_info.projectedProductContext
Voor deze bereiken moet het Adobe Developer Console -project zijn geabonneerd op Asset Compute
, I/O Events
en I/O Management API
-services. De uitsplitsing van individuele scènes is:
-
Basis
- bereik:
openid,AdobeID
- bereik:
-
Asset compute
- metarek:
asset_compute_meta
- bereik:
asset_compute,read_organizations
- metarek:
-
Adobe
I/O Events
- metarek:
event_receiver_api
- bereik:
event_receiver,event_receiver_api
- metarek:
-
Adobe
I/O Management API
- metarek:
ent_adobeio_sdk
- bereik:
adobeio_api,additional_info.roles,additional_info.projectedProductContext
- metarek:
Registratie
Elke cliënt van Asset Compute service - een uniek Adobe Developer Console project dat aan de dienst wordt ingetekend - moet registrerenalvorens verwerkingsverzoeken te maken. De registratiestap retourneert het unieke gebeurtenisjournaal dat vereist is om de asynchrone gebeurtenissen van de uitvoering op te halen.
Aan het eind van zijn levenscyclus, kan een cliënt 🔗 unregister.
Aanvraag registreren
Met deze API-aanroep wordt een Asset Compute -client ingesteld en wordt de URL van het gebeurtenisdagboek weergegeven. Dit proces is een epidemische bewerking en hoeft slechts één keer voor elke client te worden aangeroepen. Het kan opnieuw worden geroepen om het dagboek URL terug te winnen.
POST
/register
Authorization
x-request-id
Reactie registreren
application/json
X-Request-Id
X-Request-Id
of een uniek gegenereerde header. Gebruik voor het identificeren van verzoeken over systemen, of steunverzoeken, of allebei.journal
, ok
of requestId
.De HTTP-statuscodes zijn:
-
200 Succes: Wanneer het verzoek succesvol is. De URL van
journal
ontvangt meldingen over de resultaten van de asynchrone verwerking die via/process
wordt gestart. Er wordt een melding weergegeven vanrendition_created
-gebeurtenissen wanneer het proces is voltooid, ofrendition_failed
-gebeurtenissen als het proces is mislukt.{ "ok": true, "journal": "https://api.adobe.io/events/organizations/xxxxx/integrations/xxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "1234567890" }
-
401 Onbevoegd: komt voor wanneer het verzoek geen geldige authentificatieheeft. Een voorbeeld kan een ongeldige toegangstoken of een ongeldige API-sleutel zijn.
-
403 Verboden: komt voor wanneer het verzoek geen geldige vergunningheeft. Een voorbeeld zou een geldig toegangstoken kunnen zijn, maar het Adobe Developer Console project (technische rekening) wordt niet ingetekend aan alle vereiste diensten.
-
429 Te veel verzoeken: komt voor wanneer deze cliënt of anders het systeem overlaadt. De cliënten zouden met een exponentiële backoffopnieuw moeten proberen. Het lichaam is leeg.
-
4xx fout: Wanneer er een andere cliëntfout en registratie ontbrak. Gewoonlijk wordt een JSON-reactie als deze geretourneerd, hoewel dat niet voor alle fouten wordt gegarandeerd:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx fout: komt voor wanneer er een andere fout van de serverzijde en de registratie ontbrak. Gewoonlijk wordt een JSON-reactie als deze geretourneerd, hoewel dat niet voor alle fouten wordt gegarandeerd:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Aanvraag ongedaan maken
Met deze API-aanroep wordt de registratie van een Asset Compute -client ongedaan gemaakt. Nadat de registratie ongedaan is gemaakt, kan /process
niet meer worden aangeroepen. Als u de API-aanroep voor een niet-geregistreerde client of een nog te registreren client gebruikt, wordt een 404
-fout geretourneerd.
POST
/unregister
Authorization
x-request-id
Reactie ongedaan maken
application/json
X-Request-Id
X-Request-Id
of een uniek gegenereerde header. Gebruik voor het identificeren van verzoeken over systemen of steunverzoeken.ok
- en requestId
-velden.De statuscodes zijn:
-
200 Succes: komt voor wanneer de registratie en het dagboek worden gevonden en verwijderd.
{ "ok": true, "requestId": "1234567890" }
-
401 Onbevoegd: komt voor wanneer het verzoek geen geldige authentificatieheeft. Een voorbeeld kan een ongeldige toegangstoken of een ongeldige API-sleutel zijn.
-
403 Verboden: komt voor wanneer het verzoek geen geldige vergunningheeft. Een voorbeeld zou een geldig toegangstoken kunnen zijn, maar het Adobe Developer Console project (technische rekening) wordt niet ingetekend aan alle vereiste diensten.
-
404 niet gevonden: Deze status verschijnt wanneer de verstrekte geloofsbrieven niet geregistreerd of ongeldig zijn.
{ "ok": true, "requestId": "1234567890" }
-
429 Te veel verzoeken: komt voor wanneer het systeem wordt overbelast. De cliënten zouden met een exponentiële backoffopnieuw moeten proberen. Het lichaam is leeg.
-
4xx fout: komt voor wanneer er een andere cliëntfout was en unregister ontbrak. Gewoonlijk wordt een JSON-reactie als deze geretourneerd, hoewel dat niet voor alle fouten wordt gegarandeerd:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx fout: komt voor wanneer er een andere fout van de serverzijde en de registratie ontbrak. Gewoonlijk wordt een JSON-reactie als deze geretourneerd, hoewel dat niet voor alle fouten wordt gegarandeerd:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
Procesaanvraag
De bewerking process
verzendt een taak die een bronelement transformeert in meerdere uitvoeringen, op basis van de instructies in de aanvraag. Meldingen over een geslaagde voltooiing (gebeurtenistype rendition_created
) of over eventuele fouten (gebeurtenistype rendition_failed
) worden verzonden naar een gebeurtenisvenster dat één keer met /register
moet worden opgehaald voordat een aantal /process
-aanvragen kan worden ingediend. Onjuist gevormde verzoeken ontbreken onmiddellijk met een 400 foutencode.
Er wordt verwezen naar binaire getallen via URL's, zoals vooraf ondertekende URL's voor Amazon AWS S3 of Azure Blob Storage SAS-URL's. Wordt gebruikt voor het lezen van het element source
(GET
URLs) en het schrijven van de vertoningen (PUT
URLs). De klant is verantwoordelijk voor het genereren van deze vooraf ondertekende URL's.
POST
/process
application/json
Authorization
x-request-id
Verzoek om verwerking JSON
De aanvraaghoofdtekst van /process
is een JSON-object met dit schema op hoog niveau:
{
"source": "",
"renditions" : []
}
De beschikbare velden zijn:
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" }]
De source
kan een <string>
zijn die als een URL wordt gezien of een <object>
met een extra veld. De volgende varianten zijn vergelijkbaar:
"source": "http://example.com/image.jpg"
"source": {
"url": "http://example.com/image.jpg"
}
Source-objectvelden
url
string
"http://example.com/image.jpg"
name
string
content-disposition
kopbal van de binaire bron. De standaardwaarde is "file"."image.jpg"
size
number
content-length
header van de binaire resource.10234
mimetype
string
content-type
-header van de binaire bron."image/jpeg"
Een volledig aanvraagvoorbeeld process
{
"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"
}]
}
Procesreactie
De /process
-aanvraag wordt onmiddellijk geretourneerd met succes of als de aanvraag is mislukt op basis van de validatie van de basisaanvraag. De werkelijke verwerking van elementen gebeurt asynchroon.
application/json
X-Request-Id
X-Request-Id
of een uniek gegenereerde header. Gebruik voor het identificeren van verzoeken over systemen of steunverzoeken.ok
- en requestId
-velden.Statuscodes:
-
200 Succes: Als het verzoek met succes werd voorgelegd. Response JSON bevat
"ok": true
:{ "ok": true, "requestId": "1234567890" }
-
400 Ongeldig verzoek: Als het verzoek onjuist gestructureerd is, bijvoorbeeld, als het vereiste gebieden in de nuttige lading JSON mist. Response JSON bevat
"ok": false
:{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
401 onbevoegd: Wanneer het verzoek geen geldige authentificatieheeft. Een voorbeeld kan een ongeldige toegangstoken of een ongeldige API-sleutel zijn.
-
403 Verboden: Wanneer het verzoek geen geldige vergunningheeft. Een voorbeeld zou een geldig toegangstoken kunnen zijn, maar het Adobe Developer Console project (technische rekening) wordt niet ingetekend aan alle vereiste diensten.
-
429 Te veel verzoeken: komt voor wanneer het systeem, of toe te schrijven aan deze bepaalde cliënt of van algemene vraag wordt overweldigd. De cliënten kunnen met een exponentiële backoffopnieuw proberen. Het lichaam is leeg.
-
4xx fout: Wanneer er een andere cliëntfout was. Gewoonlijk wordt een JSON-reactie als deze geretourneerd, hoewel dat niet voor alle fouten wordt gegarandeerd:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
-
5xx fout: Wanneer er een andere fout van de serverzijde was. Gewoonlijk wordt een JSON-reactie als deze geretourneerd, hoewel dat niet voor alle fouten wordt gegarandeerd:
{ "ok": false, "requestId": "1234567890", "message": "error message" }
De meeste cliënten zijn waarschijnlijk geneigd om het zelfde verzoek met exponentiële backoffop om het even welke fout behalve configuratiekwesties zoals 401 of 403, of ongeldige verzoeken zoals 400 opnieuw te proberen. Afgezien van de reguliere tariefbeperking door middel van 429 reacties, kan een uitval of beperking van een tijdelijke dienst leiden tot 5xx fouten. Het zou dan raadzaam zijn om na een bepaalde periode opnieuw te proberen.
Alle JSON-reacties (indien aanwezig) bevatten requestId
. Dit is dezelfde waarde als de X-Request-Id
-header. Adobe raadt aan de koptekst te lezen, omdat deze altijd aanwezig is. requestId
wordt ook geretourneerd in alle gebeurtenissen die betrekking hebben op het verwerken van aanvragen als requestId
. Clients mogen geen aanname maken over de opmaak van deze tekenreeks. Dit is een ondoorzichtige tekenreeks-id.
Aanmelden bij nabewerking
De Asset compute SDKsteunt een reeks basisbeeld naverwerkingsopties. Aangepaste workers kunnen zich expliciet aanmelden bij nabewerking door het veld postProcess
voor het weergaveobject in te stellen op true
.
De ondersteunde gebruiksgevallen zijn:
- Uitsnijden is een uitvoering van een rechthoek waarvan de grenzen door middel van uitsnijden.w, uitsnijden.h, uitsnijden.x en uitsnijden.y zijn gedefinieerd. De uitsnijddetails worden opgegeven in het veld
instructions.crop
van het weergaveobject. - Wijzig de grootte van afbeeldingen met breedte, hoogte of beide. De tekens
instructions.width
eninstructions.height
definiëren deze in het weergaveobject. Als u alleen de breedte of hoogte wilt wijzigen, stelt u slechts één waarde in. Met Compute Service behoudt u de hoogte-breedteverhouding. - Stel de kwaliteit in voor een JPEG-afbeelding.
instructions.quality
definieert deze in het weergaveobject. Een kwaliteitsniveau van 100 staat voor de hoogste kwaliteit, terwijl een lagere waarde een lagere kwaliteit betekent. - Maak geïnterlinieerde afbeeldingen.
instructions.interlace
definieert deze in het weergaveobject. - Stel DPI in om de gerenderde grootte aan te passen voor publicatie op het bureaublad door de schaal aan te passen die op de pixels wordt toegepast. De
instructions.dpi
definieert deze in het weergaveobject om de dpi-resolutie te wijzigen. Als u echter het formaat van de afbeelding wilt wijzigen, zodat deze dezelfde grootte heeft bij een andere resolutie, gebruikt u de instructies vanconvertToDpi
. - Wijzig de grootte van de afbeelding zodanig dat de weergegeven breedte of hoogte gelijk blijft aan het origineel bij de opgegeven doelresolutie (DPI).
instructions.convertToDpi
definieert deze in het weergaveobject.
Watermerkelementen
De Asset compute SDKsteunt het toevoegen van een watermerk aan PNG, JPEG, TIFF, en de dossiers van het GIF beeld. Het watermerk wordt toegevoegd na de vertoningsinstructies in het watermark
-object op de vertoning.
Watermerken worden uitgevoerd tijdens de nabewerking van de vertoning. Om activa van het watermerk te voorzien, opteert de douanearbeider in post-verwerkingdoor het gebied postProcess
op het vertoningsvoorwerp aan true
te plaatsen. Als de worker niet meedoet, wordt er geen watermerken toegepast, zelfs niet als het watermerkobject is ingesteld op het weergaveobject in de aanvraag.
Vertoningsinstructies
Hieronder vindt u de beschikbare opties voor de array renditions
in /process
.
Algemene velden
fmt
string
text
zijn voor tekstextractie en xmp
voor het extraheren van XMP metagegevens als XML. Zie gesteunde formatenpng
worker
string
https://
URL zijn. Als dit veld aanwezig is, maakt een aangepaste toepassing de vertoning. Een ander setveld voor uitvoering wordt vervolgens gebruikt in de aangepaste toepassing."https://1234.adobeioruntime.net
/api/v1/web
/example-custom-worker-master/worker"
target
string
http://w.com/img.jpg
target
object
Vooraf ondertekende URL met meerdere delen uploadgegevens voor de gegenereerde uitvoering. Deze informatie is voor AEM/de Directe Binaire Upload van Oakmet dit multipart uploadgedrag.
Gebieden:
urls
: array van tekenreeksen, één voor elke vooraf ondertekende deel-URLminPartSize
: de minimale grootte die voor één onderdeel moet worden gebruikt = urlmaxPartSize
: de maximale grootte die voor één onderdeel kan worden gebruikt = url
{ "urls": [ "https://part1...", "https://part2..." ], "minPartSize": 10000, "maxPartSize": 100000 }
userData
object
{ ... }
Vertoningsspecifieke velden
Voor een lijst van momenteel gesteunde dossierformaten, zie gesteunde dossierformaten.
embedBinaryLimit
number
in bytesembedBinaryLimit
, wordt deze geplaatst op een locatie in de cloudopslag en wordt deze niet ingesloten in de gebeurtenis.3276
width
number
200
height
number
200
De hoogte-breedteverhouding blijft altijd behouden als:
- Zowel
width
alsheight
worden opgegeven en de afbeelding past op de grootte terwijl de hoogte-breedteverhouding behouden blijft - Als er maar
width
ofheight
wordt opgegeven, gebruikt de resulterende afbeelding de corresponderende dimensie terwijl de hoogte-breedteverhouding behouden blijft - Als
width
ofheight
niet is opgegeven, wordt de oorspronkelijke pixelgrootte van de afbeelding gebruikt. Het hangt van het brontype af. Voor sommige indelingen, zoals PDF-bestanden, wordt een standaardgrootte gebruikt. Er kan een maximumgrootte zijn.
quality
number
1
tot 100
. Alleen van toepassing op afbeeldingsuitvoeringen.90
xmp
string
interlace
bool
true
. Dit heeft geen invloed op andere bestandsindelingen.jpegSize
number
quality
-instellingen worden genegeerd. Dit heeft geen invloed op andere indelingen.dpi
number
of object
96
of { xdpi: 96, ydpi: 96 }
convertToDpi
number
of object
96
of { xdpi: 96, ydpi: 96 }
files
array
Lijst met bestanden die moeten worden opgenomen in het ZIP-archief (fmt=zip
). Elk item kan een URL-tekenreeks zijn of een object met de velden:
url
: URL om bestand te downloadenpath
: Sla het bestand onder dit pad op in het ZIP-bestand
[{ "url": "https://host/asset.jpg", "path": "folder/location/asset.jpg" }]
duplicate
string
fmt=zip
). Standaard wordt een fout gegenereerd bij meerdere bestanden die in het ZIP-bestand onder hetzelfde pad zijn opgeslagen. Als u duplicate
instelt op ignore
, wordt alleen het eerste element opgeslagen en de rest genegeerd.ignore
Watermerkspecifieke velden
De PNG-indeling wordt gebruikt als een watermerk.
scale
number
0.0
en 1.0
. 1.0
betekent dat het watermerk de oorspronkelijke schaal (1:1) heeft en de lagere waarden de grootte van het watermerk verminderen.0.5
betekent de helft van de oorspronkelijke grootte.image
url
Asynchrone gebeurtenissen
Wanneer de verwerking van een vertoning is voltooid of wanneer een fout optreedt, wordt een gebeurtenis verzonden naar een Adobe I/O Events Journal
. Clients moeten luisteren naar de journaal-URL die via /register
wordt geboden. De journaalreactie bevat een array event
die bestaat uit één object voor elke gebeurtenis, waarvan het veld event
de werkelijke gebeurtenislading bevat.
Het type Adobe I/O Events
voor alle gebeurtenissen van Asset Compute Service is asset_compute
. Het tijdschrift wordt alleen automatisch op dit gebeurtenistype geabonneerd en er is geen verdere vereiste om te filteren op basis van het gebeurtenistype Adobe Developer . De service-specifieke gebeurtenistypen zijn beschikbaar in de eigenschap type
van de gebeurtenis.
Gebeurtenistypen
rendition_created
rendition_failed
Gebeurteniskenmerken
date
string
*
requestId
string
*
/process
, gelijk aan X-Request-Id
header.source
object
*
source
van de /process
request.userData
object
*
userData
van de vertoning van de /process
request indien ingesteld.rendition
object
rendition_*
/process
.errorMessage
string
rendition_failed
Metagegevens
repo:size
repo:sha1
dc:format
repo:encoding
tiff:ImageWidth
tiff:ImageLength
Foutredenen
RenditionFormatUnsupported
SourceUnsupported
SourceCorrupt
RenditionTooLarge
target
. De werkelijke weergavegrootte is beschikbaar als metagegevens in repo:size
en wordt door de client gebruikt om deze vertoning opnieuw te verwerken met het juiste aantal vooraf ondertekende URL's.GenericError