Aggiunta della convalida delle richieste alle distribuzioni API

Scopri come impedire l'invio di richieste non valide ai servizi backend, convalidando le richieste in entrata in base a un criterio di richiesta di convalida con Gateway API.

In genere, si desidera evitare di caricare inutilmente i servizi di back-end inviando solo richieste valide a tali servizi. Per impedire l'invio di richieste non valide ai servizi backend, è possibile utilizzare un gateway API per convalidare le richieste in entrata in base a un criterio di richiesta di convalida. Se una richiesta non soddisfa i requisiti dei criteri di convalida, è possibile configurare il gateway API per rifiutare la richiesta anziché trasferirla al servizio backend di destinazione. Al contrario, il gateway API invia una risposta di codice di errore 4xx al client API che ha inviato la richiesta.

Utilizzando un gateway API, è possibile impostare i criteri di richiesta di convalida per verificare che:

la richiesta include intestazioni specifiche
la richiesta include parametri di query specifici
il corpo della richiesta è di un tipo di contenuto specifico

È possibile controllare il modo in cui un gateway API applica un criterio di richiesta di convalida specificando una modalità di convalida per il criterio:

In modalità Applicazione, il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend. Il gateway API non invia richieste che non superano la convalida al servizio backend. Il gateway API invia una risposta di codice di errore 4xx a un client API che invia una richiesta che non supera la convalida. Il gateway API include voci nei log di esecuzione per gli errori di convalida.
In modalità Permissiva, il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida. Le richieste che non superano la convalida vengono comunque inviate al servizio backend. Il gateway API include voci nei log di esecuzione per gli errori di convalida. Utilizzare la modalità Permissiva per valutare il probabile impatto dell'applicazione di un criterio di richiesta di convalida a un sistema già presente nel sistema di produzione, senza influire sui client API che inviano le richieste.
In modalità disabilitata, il gateway API non convalida alcuna richiesta in base al criterio della richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.

Il gateway API applica i criteri di richiesta di convalida dopo i criteri di richiesta CORS e dopo i criteri di autenticazione e di richiesta di autorizzazione, ma prima dei criteri di richiesta di trasformazione.

È possibile aggiungere criteri di richiesta di convalida a una specifica di distribuzione API effettuando le operazioni riportate di seguito.

utilizzo di Console
modifica di un file JSON

Utilizzo della console per aggiungere criteri di richiesta di convalida

Per aggiungere criteri di richiesta di convalida a una specifica di distribuzione API utilizzando la console:

Creare o aggiornare una distribuzione API utilizzando la console, selezionare l'opzione Da zero e immettere i dettagli nella pagina Informazioni di base.

Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.
Fare clic su Avanti e specificare le opzioni di autenticazione nella pagina Autenticazione.

Per ulteriori informazioni sulle opzioni di autenticazione, vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.
Fare clic su Avanti e immettere i dettagli per i singoli instradamenti nella distribuzione API nella pagina Instradamenti.
Nella pagina Cicli selezionare l'instradamento per il quale si desidera specificare i criteri di richiesta di convalida.
Fare clic su Mostra criteri di richiesta instradamento.
Per convalidare le intestazioni incluse in una richiesta al gateway API per l'instradamento corrente, creare un criterio di richiesta di convalida dell'intestazione:
1. Fare clic sul pulsante Aggiungi accanto a Convalide intestazione e specificare i dettagli della prima intestazione nella richiesta da convalidare:
  - Nome intestazione: il nome di un'intestazione nella richiesta da convalidare. Ad esempio, X-Username .
  - Obbligatorio: indica se l'intestazione specificata deve essere presente nella richiesta affinché la richiesta venga considerata valida.
2. (Facoltativo) Fare clic su Altra intestazione e specificare intestazioni aggiuntive nella richiesta da convalidare.
3. Fare clic su Mostra opzioni avanzate e selezionare una modalità per specificare la modalità di applicazione del criterio di richiesta di convalida dell'intestazione.
  - Applicazione: il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
  - Permissivo: il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida.
  - Disabilitato: il gateway API non convalida alcuna richiesta in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.
  Si noti che Applicazione è la modalità di convalida predefinita.
4. Fare clic su Aggiungi convalide.
Per convalidare i parametri di query inclusi in una richiesta al gateway API per l'instradamento corrente, creare un criterio di richiesta di convalida dei parametri di query:
1. Fare clic sul pulsante Aggiungi accanto a Convalide dei parametri di query e specificare i dettagli del primo parametro di query nella richiesta da convalidare:
  - Nome parametro: il nome di un parametro di query nella richiesta da convalidare. Ad esempio, state .
  - Obbligatorio: indica se il parametro di query specificato deve essere presente nella richiesta affinché la richiesta venga considerata valida.
2. (Facoltativo) Fare clic su Altro parametro e specificare ulteriori parametri di query nella richiesta da convalidare.
3. Fare clic su Mostra opzioni avanzate e selezionare una modalità per specificare la modalità di applicazione del criterio di richiesta di convalida dei parametri di query.
  - Applicazione: il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
  - Permissivo: il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida.
  - Disabilitato: il gateway API non convalida alcuna richiesta in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.
  Si noti che Applicazione è la modalità di convalida predefinita.
4. Fare clic su Aggiungi convalide.
Per convalidare il contenuto nel corpo di una richiesta al gateway API per l'instradamento corrente, creare un criterio di richiesta di convalida del corpo:
1. Fare clic sul pulsante Aggiungi accanto a Convalida del corpo e specificare quanto segue.
  - Obbligatorio: indica se il corpo di una richiesta deve essere uno dei tipi di contenuto specificati affinché la richiesta venga considerata valida.
  - Tipo di supporto: un tipo di contenuto valido per il corpo di una richiesta. Ad esempio, application/json, application/xml.
2. (Facoltativo) Fare clic su Altro tipo di supporto e specificare tipi di contenuto validi aggiuntivi per il corpo della richiesta.
  Se si specificano più tipi di contenuto, il corpo della richiesta deve essere uno dei tipi di contenuto consentiti specificati affinché la richiesta venga considerata valida.
3. Fare clic su Mostra opzioni avanzate e selezionare una modalità per specificare la modalità di applicazione del criterio di richiesta di convalida del corpo.
  - Applicazione: il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
  - Permissivo: il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida.
  - Disabilitato: il gateway API non convalida alcuna richiesta in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.
  Si noti che Applicazione è la modalità di convalida predefinita.
4. Fare clic su Aggiungi convalide.
Fare clic su Avanti per esaminare i dettagli immessi per i singoli instradamenti.
Fare clic su Crea o su Salva modifiche per creare o aggiornare la distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Modifica di un file JSON per aggiungere criteri di richiesta di convalida

Per aggiungere criteri di richiesta di convalida a una specifica di distribuzione API in un file JSON, effettuare le operazioni riportate di seguito.

Utilizzando l'editor JSON preferito, modificare la specifica di distribuzione API esistente alla quale si desidera aggiungere criteri di richiesta di convalida o creare una nuova specifica di distribuzione API (vedere Creazione di una specifica di distribuzione API).

Ad esempio, la seguente specifica di distribuzione API di base definisce una semplice funzione serverless Hello World in Funzioni OCI come un singolo backend:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Inserire una sezione requestPolicies dopo la sezione backend per l'instradamento a cui si desidera applicare il criterio di richiesta di convalida. Ad esempio:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

Per convalidare le intestazioni incluse in una richiesta al gateway API per l'instradamento corrente, specificare un criterio di richiesta di convalida headerValidations.
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerValidations": {
          "headers": {
            "name": "<header-name>",
            "required": <true|false>
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
dove:
- "name":"<header-name>" è un'intestazione nella richiesta di convalida. Per il nome specificato non è prevista la distinzione tra casi. Ad esempio, X-Username.
- "required": <true|false> indica se l'intestazione specificata da "name":"<header-name>" deve essere presente nella richiesta affinché la richiesta venga considerata valida.
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indica il modo in cui il gateway API convalida le richieste in base al criterio della richiesta di convalida dell'intestazione, come riportato di seguito.
  - ENFORCING: Il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
  - PERMISSIVE: Il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida.
  - DISABLED: Il gateway API non convalida alcuna richiesta in base al criterio della richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.
  Ad esempio, "validationMode": "PERMISSIVE". Se non si include "validationMode", viene utilizzata la modalità di convalida predefinita ENFORCING.
Ad esempio:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerValidations": {
          "headers": {
            "name": "X-Username",
            "required": true
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
In questo esempio, affinché la richiesta venga considerata valida, la richiesta deve includere l'intestazione X-Username. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
Per convalidare i parametri di query inclusi in una richiesta al gateway API per l'instradamento corrente, specificare un criterio di richiesta di convalida queryParameterValidations.
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterValidations": {
          "parameters": {
            "name": "<query-parameter-name>",
            "required": <true|false>
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
dove:
- "name":"<query-parameter-name>" è un parametro di query nella richiesta da convalidare. Per il nome specificato non è prevista la distinzione tra casi. Ad esempio, state.
- "required": <true|false> indica se il parametro di query specificato da "name":"<query-parameter-name>" deve essere presente nella richiesta affinché la richiesta venga considerata valida.
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indica il modo in cui il gateway API convalida le richieste rispetto al criterio di richiesta di convalida del parametro di query, come indicato di seguito.
  - ENFORCING: Il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
  - PERMISSIVE: Il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida.
  - DISABLED: Il gateway API non convalida alcuna richiesta in base al criterio della richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.
  Ad esempio, "validationMode": "PERMISSIVE". Se non si include "validationMode", viene utilizzata la modalità di convalida predefinita ENFORCING.
Ad esempio:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterValidations": {
          "parameters": {
            "name": "state",
            "required": false
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
In questo esempio, per considerare valida la richiesta, è possibile includere facoltativamente il parametro di query state. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
Per convalidare il contenuto nel corpo di una richiesta al gateway API per l'instradamento corrente, specificare un criterio di richiesta di convalida bodyValidation.
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "bodyValidation": {
          "required": true,
          "content": {
            "<media-type-1>": {
              "validationType": "NONE"
            },
            "<media-type-2>": {
              "validationType": "NONE"
            }            
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
dove:
- "required": true indica che il tipo di contenuto del corpo della richiesta deve essere uno dei tipi di contenuto specificati.
- "content": {"<media-type-1>": {"validationType": "NONE"}, "<media-type-2>": {"validationType": "NONE"}} indica uno o più tipi di contenuto consentiti per il corpo della richiesta. Il corpo della richiesta deve essere uno dei tipi di contenuto specificati. Ad esempio, application/json, application/xml. Attualmente è supportato solo NONE per "validationType".
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indica il modo in cui il gateway API convalida le richieste in base al criterio della richiesta di convalida del corpo, come riportato di seguito.
  - ENFORCING: Il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
  - PERMISSIVE: Il gateway API convalida tutte le richieste in base al criterio di richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend, indipendentemente dal fatto che superino o non superino la convalida.
  - DISABLED: Il gateway API non convalida alcuna richiesta in base al criterio della richiesta di convalida. Il gateway API invia tutte le richieste al servizio backend.
  Ad esempio, "validationMode": "PERMISSIVE". Se non si include "validationMode", viene utilizzata la modalità di convalida predefinita ENFORCING.
Ad esempio:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "bodyValidation": {
          "required": true,
          "content": {
            "application/json": {
              "validationType": "NONE"
            },
            "application/xml": {
              "validationType": "NONE"
            }
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
In questo esempio, per considerare valida la richiesta, il tipo di contenuto del corpo della richiesta deve essere application/json o application/xml. Il gateway API invia solo le richieste che passano la convalida al servizio backend.
Salvare il file JSON contenente la specifica di distribuzione API.
Utilizzare la specifica di distribuzione API quando si crea o si aggiorna una distribuzione API nei modi riportati di seguito.
- specificando il file JSON nella console quando si seleziona l'opzione Carica un'interfaccia API esistente
- specificando il file JSON in una richiesta all'API REST del gateway API
Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Documentazione di Oracle Cloud Infrastructure

Aggiunta della convalida delle richieste alle distribuzioni API

Utilizzo della console per aggiungere criteri di richiesta di convalida

Modifica di un file JSON per aggiungere criteri di richiesta di convalida