Note importanti Amazon API Gateway - Amazon API Gateway
Note importanti di Gateway Amazon API per le REST APINote importanti su Gateway Amazon API per le API HTTP e WebSocketNote importanti per le REST API e le API WebSocketNote importanti per le API WebSocketNote importanti per REST API

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à.

Note importanti Amazon API Gateway

La sezione seguente descrive in dettaglio le note che possono riguardare l'utilizzo di Gateway API.

Note importanti di Gateway Amazon API per le REST API

  • Le API HTTP traducono le intestazioni X-Forwarded-* in entrata in un'intestazione Forwarded standard e aggiungono l'IP di uscita, l'host e il protocollo.

  • Gateway API aggiunge l’intestazione Content-type alla richiesta se non è presente alcun payload e Content-Length è pari a 0.

Note importanti su Gateway Amazon API per le API HTTP e WebSocket

  • Il protocollo Signature Version 4a non è ufficialmente supportato da Gateway Amazon API per le API HTTP e WebSocket.

Note importanti Amazon API Gateway per le API REST e WebSocket

  • API Gateway non supporta la condivisione di un nome di dominio personalizzato nelle REST API e WebSocket.

  • I nomi di fasi possono contenere solo caratteri alfanumerici, trattini e caratteri di sottolineatura. La lunghezza massima è 128 caratteri.

  • I percorsi di /ping e /sping sono riservati al controllo dello stato del servizio. Se questi percorsi vengono utilizzati per le risorse API al livello di root con domini personalizzati, non sarà possibile ottenere il risultato previsto.

  • Attualmente API Gateway limita gli eventi di log a 1024 byte. Il registro di eventi superiori a 1024 byte, come i corpi di testo delle richieste e delle risposte, verranno troncati da API Gateway prima dell'invio a CloudWatch Logs.

  • I parametri CloudWatch attualmente limitano i nomi e i valori di dimensione a un massimo di 255 caratteri XML validi. Per ulteriori informazioni, consulta la Guida per l'utente di CloudWatch. I valori di dimensione sono una funzione di nomi definiti dall'utente, tra cui nome dell'API, nome dell'etichetta (fase) e nome della risorsa. Quando si scelgono questi nomi, è importante non superare i limiti dei parametri di CloudWatch.

  • La dimensione massima di un modello di mappatura è 300 KB.

Note importanti Amazon API Gateway per le API WebSocket

  • API Gateway supporta payload dei messaggi fino a 128 KB con dimensione del frame massima di 32 KB. Se un messaggio supera i 32 KB, occorre suddividerlo in più frame, ciascuno di 32 KB o più piccolo. Se si riceve un messaggio di dimensioni maggiori, la connessione viene chiusa con codice 1009.

Note importanti Amazon API Gateway per le REST API

  • Il carattere barra verticale di testo semplice (|) e il carattere parentesi graffa ({ o }) non sono supportati per le stringhe di query dell'URL della richiesta e devono presentare la codifica URL.

  • Il punto e virgola (;) non è supportato per qualsiasi URL di richiesta della stringa di query e i risultati dei dati del frazionamento.

  • In generale, le REST API decodificano i parametri di richiesta con codifica URL prima di passarli alle integrazioni backend. Per i parametri di richiesta UTF-8, le REST API decodificano i parametri e poi li passano come Unicode alle integrazioni backend. Il carattere percentuale (%) con codifica URL delle REST API prima di passarlo alle integrazioni backend.

  • Se effettui il test di un'API tramite la console API Gateway, potresti ricevere la risposta "unknown endpoint errors" (errori endpoint sconosciuti) se un certificato autofirmato viene inviato al back-end, se il certificato intermedio manca nella catena dei certificati o se viene rilevata dal back-end qualsiasi altra eccezione relativa a un certificato non riconoscibile.

  • È consigliabile eliminare un'entità API Resource o Method con un'integrazione privata, dopo aver rimosso eventuali riferimenti hardcoded di un VpcLink. In caso contrario, l'integrazione verrà sospesa e riceverai un errore che ti informerà che il collegamento VPC è ancora in uso anche in seguito all'eliminazione dell'entità Resource o Method. Questo comportamento non si applica quando l'integrazione privata fa riferimento a VpcLink tramite una variabile di fase.

  • I back-end seguenti potrebbero non supportare l'autenticazione client SSL in un modo che sia compatibile con API Gateway:

  • API Gateway supporta in gran parte la specifica OpenAPI 2.0 e la specifica OpenAPI 3.0, con le seguenti eccezioni:

    • I segmenti di percorso possono contenere solo caratteri alfanumerici, trattini, punti, virgole, due punti e parentesi graffe. I parametri di percorso devono essere segmenti di percorso separati. Ad esempio, "risorsa/{nome_parametro_percorso}" è valido, mentre "risorsa{nome_parametro_percorso}" no.

    • I nomi di modelli possono contenere solo caratteri alfanumerici.

    • Per i parametri di input, sono supportati solo i seguenti attributi: name, in, required, type, description. Altri attributi vengono ignorati.

    • Il tipo securitySchemes, se utilizzato, deve essere apiKey. Tuttavia, l'autenticazione OAuth 2 e l'autenticazione di base HTTP sono supportate tramite provider di autorizzazioni Lambda. La configurazione OpenAPI viene ottenuta tramite estensioni dei fornitori.

    • Il campo deprecated non è supportato e viene eliminato nelle API esportate.

    • I modelli di API Gateway sono definiti tramite la bozza 4 dello schema JSON, anziché lo schema JSON utilizzato da OpenAPI.

    • Il parametro discriminator non è supportato in nessun oggetto dello schema.

    • Il tag example non è supportato.

    • Il campo nullable non è supportato.

    • exclusiveMinimum non è supportato da API Gateway.

    • I tag maxItems e minItems non sono inclusi nella convalida della richiesta semplice. Come soluzione alternativa, aggiorna il modello in seguito all'importazione e prima di procedere con la convalida.

    • Per OpenAPI 3.0, non è possibile specificare una parola chiave oneOf, anyOf o allOf che utilizza $ref per una definizione all’interno dello stesso schema. È possibile immettere direttamente lo schema o definire una risorsa separata del modello Gateway API. Per ulteriori informazioni, consulta Creazione di modelli più complessi.

    • oneOf non è supportato per OpenAPI 2.0 o la generazione di SDK.

    • Il campo readOnly non è supportato.

    • $ref non può essere utilizzato per fare riferimento ad altri file.

    • Le definizioni di risposta del modulo "500": {"$ref": "#/responses/UnexpectedError"} non sono supportate nella root del documento di OpenAPI. Come soluzione alternativa, sostituisci i riferimenti con lo schema inline.

    • I numeri del tipo Int32 o Int64 non sono supportati. Di seguito viene riportato un esempio:

      "elementId": {
    "description": "Working Element Id",
    "format": "int32",
    "type": "number"
}

    • Il tipo di formato con numeri decimali ("format": "decimal") non è supportato nelle definizioni dello schema.

    • Nelle risposte del metodo, la definizione dello schema deve essere di tipo oggetto e non di tipo di base. Ad esempio, "schema": { "type": "string"} non è supportato. Tuttavia, puoi trovare una soluzione alternativa al problema utilizzando il tipo di oggetto seguente:

      "schema": {
     "$ref": "#/definitions/StringResponse"
            }

 "definitions": {
    "StringResponse": {
      "type": "string"
    }
  }

    • API Gateway non utilizza la sicurezza a livello di radice definita nella specifica di OpenAPI. Pertanto, la sicurezza deve essere definita a livello di operazione per essere applicata in modo appropriato.

    • La parola chiave default non è supportata.

  • In API Gateway vengono applicate le seguenti restrizioni e limitazioni per la gestione dei metodi con l'integrazione Lambda o HTTP.

    • I nomi delle intestazioni e i parametri di query vengono elaborati tenendo presente la distinzione tra lettere maiuscole e minuscole.

    • La tabella seguente elenca le intestazioni che potrebbero venire interrotte, rimappate o modificate quando vengono inviate all'endpoint dell'integrazione o reinviate dall'endpoint dell'integrazione: In questa tabella:

      • Remapped significa che il nome dell'intestazione è cambiato da <string> a X-Amzn-Remapped-<string>.

        Remapped Overwritten significa che il nome dell'intestazione è cambiato da <string> a X-Amzn-Remapped-<string> e il valore viene sovrascritto.

      Nome intestazione Richiesta (http/http_proxy/lambda) Risposta (http/http_proxy/lambda)
      Age Transito Transito
      Accept Transito Interrotta/Transito/Transito
      Accept-Charset Transito Transito
      Accept-Encoding Transito Transito
      Authorization Transito * Rimappata
      Connection Transito/Transito/Interrotta Rimappata
      Content-Encoding Transito/Interrotta/Transito Transito
      Content-Length Transito (generato in base al corpo) Transito
      Content-MD5 Interrotta Rimappata
      Content-Type Transito Transito
      Date Transito Rimappata Sovrascritta
      Expect Interrotta Interrotta
      Host Sovrascritto nell'endpoint di integrazione Interrotta
      Max-Forwards Interrotta Rimappata
      Pragma Transito Transito
      Proxy-Authenticate Interrotta Interrotta
      Range Transito Transito
      Referer Transito Transito
      Server Interrotta Rimappata Sovrascritta
      TE Interrotta Interrotta
      Transfer-Encoding Interrotta/Interrotta/Eccezione Interrotta
      Trailer Interrotta Interrotta
      Upgrade Interrotta Interrotta
      User-Agent Transito Rimappata
      Via Interrotta/Interrotta/Transito Transito/Interrotta/Interrotta
      Warn Transito Transito
      WWW-Authenticate Interrotta Rimappata

      * L'intestazione Authorization viene eliminata se contiene una firma Signature Version 4 o viene usata un’autorizzazione AWS_IAM.

  • L'SDK Android di un'API generata da API Gateway utilizza la classe java.net.HttpURLConnection. Questa classe genererà un'eccezione non gestita, sui dispositivi con Android 4.4 e versioni precedenti, per la risposta 401 derivante dalla rimappatura dell'intestazione WWW-Authenticate su X-Amzn-Remapped-WWW-Authenticate.

  • A differenza degli SDK Java, Android e iOS generati da API Gateway di un'API, l'SDK JavaScript di un'API generata da API Gateway non supporta i tentativi degli errori di livello 500.

  • La chiamata di test di un metodo utilizza il tipo di contenuto predefinito di application/json e ignora le specifiche di altri tipi di contenuto.

  • Quando invii richieste a un'API passando l'intestazione X-HTTP-Method-Override, API Gateway sostituisce il metodo. Per passare l'intestazione al back-end, è necessario aggiungere l'intestazione all'integrazione richiesta.

  • Quando una richiesta contiene più tipi di supporto nell'intestazione Accept, API Gateway mantiene la conformità solo al primo tipo di supporto Accept. Nella situazione in cui non puoi controllare l'ordine dei tipi di supporto Accept e il tipo di supporto del tuo contenuto binario non è il primo dell'elenco, puoi aggiungere il primo tipo di supporto Accept nell'elenco binaryMediaTypes della tua API e API Gateway restituirà il tuo contenuto come binario. 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 riceverà il file JPEG come binario.

  • La personalizzazione della risposta del gateway predefinito per 413 REQUEST_TOO_LARGE non è attualmente supportata.

  • API Gateway include un'intestazione Content-Type per tutte le risposte di integrazione. Per impostazione predefinita, il tipo di contenuto è application/json.