Documentazione di Oracle Cloud Infrastructure

Aggiunta di criteri di richiesta e di risposta alle specifiche di distribuzione API

Scopri come controllare il funzionamento delle distribuzioni API aggiungendo criteri di richiesta e risposta alle specifiche API create in precedenza con API Gateway.

È possibile controllare il funzionamento di una distribuzione API creata in un gateway API aggiungendo criteri di richiesta e risposta alla specifica di distribuzione API:

  • un criterio di richiesta descrive le azioni da eseguire su una richiesta in entrata da un client API prima che venga inviata a un backend
  • un criterio di risposta descrive le azioni da eseguire su una risposta restituita da un backend prima di essere inviata a un client API

È possibile utilizzare i criteri di richiesta e/o di risposta per:

  • limitare il numero di richieste inviate ai servizi backend
  • abilitare il supporto CORS (Cross-Origin Resource Sharing)
  • fornire autenticazione e autorizzazione
  • aggiunta supporto mTLS
  • convalidare le richieste prima di inviarle ai servizi backend
  • modificare le richieste in entrata e le risposte in uscita
  • cache delle risposte per migliorare le prestazioni e ridurre il carico sui servizi backend
  • rendere le distribuzioni API idonee per l'inclusione nei piani di utilizzo che monitorano e gestiscono l'accesso degli iscritti

È possibile aggiungere criteri a una specifica di distribuzione API che si applicano a livello globale a tutti gli instradamenti nella specifica di distribuzione API, nonché criteri che si applicano solo a determinati instradamenti.

Tenere presente che i criteri di richiesta e i criteri di risposta del gateway API sono diversi dai criteri IAM che controllano l'accesso alle risorse di Oracle Cloud Infrastructure.

È possibile aggiungere criteri di richiesta e risposta 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 e criteri di risposta

Per aggiungere criteri di richiesta e di risposta a una specifica di distribuzione API utilizzando la console, procedere come segue.

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

  2. Nella sezione Criteri di richiesta API della pagina Informazioni di base specificare i criteri di richiesta che si applicano a livello globale a tutti gli instradamenti nella specifica di distribuzione API.

    • Mutual-TLS: criterio per controllare l'accesso alle API distribuite nei gateway API in base al certificato TLS presentato dal client API che effettua una richiesta. È possibile applicare un criterio mTLS a livello globale solo a tutti gli instradamenti nella specifica di distribuzione API (non a singoli instradamenti). Vedere Aggiunta del supporto mTLS alle distribuzioni API.
    • CORS: un criterio per abilitare il supporto CORS nelle API distribuite nei gateway API. È inoltre possibile specificare i criteri CORS che si applicano ai singoli instradamenti nella specifica di distribuzione API (non è necessario aver prima immesso un criterio CORS globale). Vedere Aggiunta del supporto CORS alle distribuzioni API.
    • Limitazione dei tassi: criterio per limitare la frequenza con cui i client API possono effettuare richieste ai servizi backend. È possibile applicare un criterio che limita la frequenza a livello globale a tutti gli instradamenti nella specifica di distribuzione API (non a singoli instradamenti). Vedere Limitazione del numero di richieste ai backend del gateway API.

  3. Fare clic su Avanti per specificare le opzioni per definire un criterio di richiesta di autenticazione globale nella pagina Autenticazione.

    Il criterio di richiesta di autenticazione controlla l'accesso alle API distribuite nei gateway API. Dopo aver prima specificato un criterio di autenticazione globale, è possibile specificare i criteri di autorizzazione applicabili ai singoli instradamenti nella specifica di distribuzione API. Vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.

  4. Fare clic su Avanti per immettere i dettagli relativi ai singoli instradamenti nella distribuzione API nella pagina Instradamenti.

  5. Per specificare i criteri di richiesta applicabili a un singolo instradamento, fare clic su Mostra criteri di richiesta instradamento e specificare:

  6. Per specificare i criteri di risposta applicabili a un singolo instradamento, fare clic su Mostra criteri di risposta instradamento e specificare:

  7. Fare clic su Successivo per esaminare i dettagli immessi per la distribuzione API.
  8. Fare clic su Crea o su Salva modifiche per creare o aggiornare la distribuzione API.
  9. (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 e criteri di risposta

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

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

    La specifica di distribuzione API includerà almeno una sezione routes contenente:

    • Un percorso. Ad esempio /hello
    • Uno o più metodi. Ad esempio, GET
    • Definizione di un back end. Ad esempio, un URL o l'OCID di una funzione in Funzioni OCI.

    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": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

  2. Per aggiungere un criterio di richiesta applicabile a livello globale a tutti gli instradamenti nella specifica di distribuzione API, effettuare le operazioni riportate di seguito.

    1. Inserire una sezione requestPolicies prima della sezione routes. Ad esempio:

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

    2. Includere un criterio di richiesta nella sezione requestPolicies.

      Ad esempio, per limitare il numero di richieste inviate a tutti gli instradamenti in una specifica di distribuzione API, includere il criterio rateLimiting nella sezione requestPolicies come indicato di seguito.

      {
  "requestPolicies": {
    "rateLimiting": {
      "rateKey": "CLIENT_IP",
      "rateInRequestsPerSecond": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

      Per ulteriori informazioni sul criterio di richiesta rateLimiting, vedere Limitazione del numero di richieste ai backend del gateway API.

  3. Per aggiungere un criterio di richiesta che si applica a un singolo instradamento nella specifica di distribuzione API, effettuare le operazioni riportate di seguito.

    1. Inserisci una sezione requestPolicies dopo la sezione backend dell'instradamento. Ad esempio:

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

    2. Includere un criterio di richiesta nella sezione requestPolicies.

      Ad esempio, per abilitare il supporto CORS in una distribuzione API per un instradamento specifico, includere il criterio cors nella sezione requestPolicies come indicato di seguito.

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": ["*", "https://oracle.com"],
           "allowedMethods": ["*", "GET"],
           "allowedHeaders": [],
           "exposedHeaders": [],
           "isAllowCredentialsEnabled": false,
           "maxAgeInSeconds": 3000
        }
      }
    }
  ]
}

      Per ulteriori informazioni sul criterio di richiesta cors, vedere Aggiunta del supporto CORS alle distribuzioni API.

  4. Per aggiungere un criterio di risposta che si applica a un singolo instradamento nella specifica di distribuzione API, effettuare le operazioni riportate di seguito.

    1. Inserisci una sezione responsePolicies dopo la sezione backend dell'instradamento. Ad esempio:

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

    2. Includere un criterio di risposta nella sezione responsePolicies.

      Ad esempio, per rinominare qualsiasi intestazione X-Username in X-User-ID nella risposta da un instradamento specifico, includere il criterio headerTransformations nella sezione responsePolicies come indicato di seguito.

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "X-Username",
                "to": "X-User-ID"
              }
            ]
          }
        }
      }
    }
  ]
}

      Per ulteriori informazioni sul criterio di risposta headerTransformations, vedere Modifica di un file JSON per aggiungere criteri di risposta di trasformazione dell'intestazione.

  5. Salvare il file JSON contenente la specifica di distribuzione API.

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