Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Tipi di supporti binari per REST API in Gateway API
In API Gateway, la richiesta e la risposta delle API possono avere un payload binario o di testo. Il payload di testo è una stringa JSON in codifica UTF-8, mentre un payload binario è rappresentato da tutto ciò che non è un payload di testo. Il payload binario può essere, ad esempio, un file JPEG, GZip o XML. La configurazione API necessaria per supportare i supporti binari dipende dal fatto che l'API utilizzi integrazioni proxy o non proxy.
Integrazioni proxy AWS Lambda
Per gestire payload binari per le integrazioni proxy AWS Lambda, è necessario codificare in base64 la risposta della funzione. È inoltre necessario configurare binaryMediaTypes per l'API. La configurazione binaryMediaTypes dell'API è un elenco di tipi di contenuti che l'API considera come dati binari. I tipi di supporti binari di esempio includono image/png o application/octet-stream. È possibile utilizzare il carattere jolly (*) per includere più tipi di file multimediali.
API Gateway utilizza la prima intestazione Accept dai client per determinare se una risposta deve restituire supporti binari. Per restituire un supporto binario quando non è possibile controllare l’ordine dei valori delle intestazioni Accept, ad esempio le richieste da un browser, impostare i tipi di supporti binari dell’API su */*.
Per il codice di esempio, consulta Restituzione di supporti binari da un'integrazione proxy Lambda in Gateway API.
Integrazioni non proxy
Per gestire payload binari per integrazioni non proxy, devi aggiungere i tipi di supporto all'elenco binaryMediaTypes della risorsa RestApi. La configurazione binaryMediaTypes dell'API è un elenco di tipi di contenuti che l'API considera come dati binari. In alternativa, è possibile impostare le proprietà contentHandling nelle risorse Integration e IntegrationResponse. Il valore contentHandling può essere CONVERT_TO_BINARY, CONVERT_TO_TEXT o non definito.
Nota
Per le integrazioni MOCK o private, l’impostazione delle proprietà contentHandling non è supportata nella AWS Management Console. È necessario utilizzare AWS CLI, AWS CloudFormation o un SDK per impostare le proprietà contentHandling.
A seconda del valore contentHandling e se l'intestazione Content-Type della risposta o l'intestazione Accept della richiesta in entrata corrisponde a una voce dell'elenco binaryMediaTypes, API Gateway può codificare i byte binari grezzi come stringa con codifica base64, decodificare una stringa con codifica base64 di nuovo in byte grezzi oppure passare il corpo senza alcuna modifica.
Devi configurare l'API come segue per supportare i payload binari per l'API in API Gateway:
-
Aggiungere i tipi di supporto binari desiderati all'elenco
binaryMediaTypesnella risorsa RestApi. Se questa proprietà e la proprietàcontentHandlingnon sono definite, i payload vengono gestiti come stringhe JSON in codifica UTF-8. -
Indirizzare la proprietà
contentHandlingdella risorsa Integration.-
Per convertire il payload della richiesta da una stringa con codifica base64 nel relativo BLOB binario, impostare la proprietà su
CONVERT_TO_BINARY. -
Per convertire il payload della richiesta da un BLOB binario a una stringa con codifica base64, impostare la proprietà su
CONVERT_TO_TEXT. -
Per passare il payload senza modifiche, lasciare la proprietà indefinita. Per passare un payload binario senza modifiche, è inoltre necessario assicurarsi che
Content-Typecorrisponda a una delle vocibinaryMediaTypese che per l'API siano abilitati i comportamenti passthrough.
-
-
Impostare la proprietà
contentHandlingdella risorsa IntegrationResponse. La proprietàcontentHandling, l'intestazioneAcceptnelle richieste del client e i tipibinaryMediaTypescombinati dell'API determinano il modo in cui API Gateway gestisce le conversioni dei tipi di contenuto. Per informazioni dettagliate, consultare Conversioni dei tipi di contenuto in API Gateway.
Importante
Quando una richiesta contiene più tipi di supporto nell'intestazione Accept, API Gateway mantiene la conformità solo con il primo tipo di supporto Accept. Se non è possibile controllare l'ordine dei tipi di supporto Accept e il tipo di supporto del contenuto binario non è il primo dell'elenco, aggiungere il primo tipo di supporto Accept nell'elenco binaryMediaTypes dell'API. API Gateway gestisce tutti i tipi di contenuto in questo elenco come binari.
Ad esempio, per inviare un file JPEG utilizzando un elemento <img> in un browser, il browser potrebbe inviare Accept:image/webp,image/*,*/*;q=0.8 in una richiesta. Aggiungendo image/webp all'elenco binaryMediaTypes, l'endpoint riceve il file JPEG come binario.
Per informazioni dettagliate su come API Gateway gestisce i payload di testo e binari, consulta Conversioni dei tipi di contenuto in API Gateway.
