Creazione di un piano di utilizzo

Per creare un nuovo piano di utilizzo e una o più abilitazioni mediante la console, effettuare le operazioni riportate di seguito.

1. Nella pagina di elenco Piani di utilizzo selezionare Crea piano di utilizzo. Per ulteriori informazioni sulla ricerca della pagina Elenco, vedere Elenco dei piani di utilizzo.

2. Specificare i seguenti valori per il piano di utilizzo:

   • Nome: il nome del nuovo piano di utilizzo. Ad esempio, Gold-usage-plan. Evitare di fornire informazioni riservate.
   • Compartimento: compartimento a cui deve appartenere il nuovo piano di utilizzo.
3. Facoltativamente, selezionare Opzioni avanzate e specificare:
   • Tag: se si dispone delle autorizzazioni per creare una risorsa, si dispone anche delle autorizzazioni per applicare tag in formato libero a tale risorsa. Per applicare una tag defined, è necessario disporre delle autorizzazioni per utilizzare la tag namespace. Per ulteriori informazioni sull'applicazione di tag, vedere Tag risorsa. Se non sei sicuro di applicare i tag, salta questa opzione o chiedi a un amministratore. È possibile applicare le tag in un secondo momento.

4. Selezionare Successivo per specificare le distribuzioni API a cui i consumer API e i client API sottoscritti al piano di utilizzo hanno diritto di accesso.

   Un piano di utilizzo comprende le abilitazioni. Ogni abilitazione specifica una o più distribuzioni API di destinazione a cui i sottoscrittori del piano di utilizzo hanno il diritto di inviare le richieste, insieme al numero di richieste che hanno il diritto di inviare.

5. Nella pagina Adeguamenti:

   1. Selezionare Crea abilitazione e specificare i dettagli per la prima abilitazione del piano di utilizzo:

      • Nome: il nome della nuova abilitazione. I nomi spettanza devono essere univoci all'interno di un piano di utilizzo. Ad esempio, Entitlement1. Evitare di fornire informazioni riservate.
      • Descrizione: descrizione della nuova abilitazione. Ad esempio, Basic entitlement for all usage plans. Evitare di fornire informazioni riservate.
      • Limite tasso: (facoltativo) selezionare Abilita limite di frequenza per specificare un numero massimo di richieste da consentire al secondo come Richieste al secondo.
      • Quota: (facoltativo) selezionare Abilita quota per specificare un numero massimo di richieste da consentire in un determinato periodo di tempo:
        • Richieste: numero massimo di richieste da consentire.
        • Periodo: periodo di tempo al quale si applica il numero massimo di richieste. Una delle opzioni Minuto, Ora, Giorno, Settimana o Mese.

        • Reimposta criterio: quando si reimposta il conteggio del numero di richieste su zero. Il criterio di reimpostazione del calendario è supportato. Con il criterio di reimpostazione Calendario, il conteggio dei numeri di richiesta viene reimpostato su zero all'inizio di ogni nuovo periodo di tempo, come specificato da Periodo.

          Ad esempio, se Periodo è impostato su Giorno, il conteggio dei numeri di richiesta viene inizialmente impostato su zero alla prima creazione dell'abilitazione. Il conteggio viene quindi reimpostato su zero all'inizio del giorno successivo (ovvero, a mezzanotte UTC). Il conteggio viene reimpostato su zero all'inizio del giorno successivo e così via.

        • Operazione in caso di violazione: cosa accade se viene superato il numero massimo di richieste nel periodo di tempo specificato. Se si specifica Rifiuta, le richieste aggiuntive nel periodo di tempo vengono rifiutate e viene restituita una risposta HTTP-429 Too Many Requests. La risposta include l'intestazione Retry-After, che indica il tempo di attesa prima di effettuare una nuova richiesta. Se si specifica Consenti, sono ancora consentite richieste aggiuntive nel periodo di tempo.
      • Distribuzione mirata: selezionare Aggiungi distribuzione per specificare la prima distribuzione API da includere nell'abilitazione:
        • Gateway: selezionare il gateway API in cui è stata creata la distribuzione API. Il gateway API può appartenere allo stesso compartimento del piano di utilizzo, ma non è necessario.
        • Distribuzione: selezionare la distribuzione API che si desidera includere nell'abilitazione. La distribuzione API può appartenere allo stesso compartimento del piano di utilizzo, ma non è necessario.

          Tenere presente che è necessario aver già reso la distribuzione API idonea per l'inclusione nel piano di utilizzo specificando la posizione di un token client (vedere Come rendere idonea una distribuzione API per l'inclusione in un piano di utilizzo).

        Selezionare Salva per salvare i dettagli della prima distribuzione API inclusa nell'abilitazione. Facoltativamente, selezionare di nuovo Aggiungi distribuzione per specificare ulteriori distribuzioni API da includere nella prima abilitazione del piano di utilizzo.

   2. Selezionare Salva per salvare la prima abilitazione del piano di utilizzo.
   3. Facoltativamente, selezionare di nuovo Crea abilitazione e specificare i dettagli per le abilitazioni aggiuntive da includere nel piano di utilizzo.
6. Selezionare Avanti per esaminare i dettagli immessi per il piano di utilizzo.
7. Selezionare Crea per creare il piano di utilizzo.

   La creazione del nuovo piano di utilizzo può richiedere alcuni minuti. Durante la creazione, il piano di utilizzo viene visualizzato con lo stato Creazione nella pagina Piani di utilizzo. Una volta creato correttamente, il nuovo piano di utilizzo viene visualizzato con lo stato Attivo.

   Inoltre, anziché creare immediatamente il nuovo piano di utilizzo, è possibile crearlo in un secondo momento utilizzando Resource Manager e Terraform, selezionando Salva come stack per salvare la definizione della risorsa come configurazione Terraform. Per ulteriori informazioni sul salvataggio degli stack dalle definizioni delle risorse, vedere Creazione di uno stack da una pagina di creazione delle risorse.

8. Se sono stati attesi più di pochi minuti per la visualizzazione del piano di utilizzo con stato Attivo (o se l'operazione di creazione del piano di utilizzo non è riuscita):

   1. Selezionare il nome del piano di utilizzo e selezionare Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione del piano di utilizzo.
   2. Selezionare l'operazione Crea piano di utilizzo per visualizzare ulteriori informazioni sull'operazione, inclusi i messaggi di errore, i messaggi di log e lo stato delle risorse associate.
   3. Se l'operazione di creazione del piano di utilizzo non è riuscita e non è possibile diagnosticare la causa del problema dalle informazioni sulla richiesta di lavoro, vedere Risoluzione dei problemi del gateway API.

Per creare un nuovo piano di utilizzo e una o più abilitazioni mediante l'interfaccia CLI:

1. Utilizzando l'editor JSON preferito, creare un file di definizione del piano di utilizzo nel formato seguente:

   {
       "displayName": "<usage-plan-name>",
       "entitlements": [{
           "name": "<entitlement-name>",
           "description": "<entitlement-description>",
           "rateLimit": {
               "value": <rate-limit-value>,
               "unit": "<rate-limit-unit>"
           },
           "quota": {
               "value": <quota-value>,
               "unit": "<quota-unit>",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "<REJECT|ALLOW>"
           },
           "targets": [{
               "deploymentId": "<target-deployment-ocid>"
           }]
       }],
       "compartmentId": "<compartment-ocid>",
       "freeformTags": {},
       "definedTags": {}
   }

   dove:

   • "displayName": "<usage-plan-name>" è il nome del nuovo piano di utilizzo. Ad esempio, "displayName": "Gold-usage-plan". Evitare di inserire informazioni riservate.
   • "entitlements": [{...}] specifica i dettagli di una o più abilitazioni, dove:
     • "name": "<entitlement-name>" è il nome di una nuova abilitazione. I nomi di spettanza devono essere univoci all'interno di un piano di utilizzo. Ad esempio, "Entitlement1". Evitare di inserire informazioni riservate.
     • "description": "<entitlement-description>" è una descrizione della nuova abilitazione. Ad esempio, "description": "Basic entitlement for all usage plans". Evitare di inserire informazioni riservate.
     • "rateLimit": {…} specifica facoltativamente un numero massimo di richieste da consentire al secondo. Se si definisce un limite di frequenza, è necessario includere i valori per tutti gli elementi riportati di seguito.
       • "value": <rate-limit-value> è il numero massimo di richieste da consentire. Ad esempio, "value": 100.
       • "unit": "<rate-limit-unit>" è l'unità di tempo del limite di frequenza. Deve essere impostato su "SECOND".
     • "quota": {…} specifica facoltativamente un numero massimo di richieste da consentire in un determinato periodo di tempo. Se si definisce una quota, è necessario includere i valori per tutti gli elementi riportati di seguito.
       • "value": <quota-value> è il numero massimo di richieste da consentire per periodo di tempo. Ad esempio, "value": 1000
       • "unit": "<quota-unit>" è il periodo di tempo a cui si applica il numero massimo di richieste. Deve essere impostata su una delle opzioni MINUTE, HOUR, DAY, WEEK o MONTH. Ad esempio, "unit": "MONTH".
       • "resetPolicy": "CALENDAR" indica quando il conteggio del numero di richieste viene reimpostato su zero. Il criterio di reimpostazione CALENDAR è supportato. Con il criterio di reimpostazione CALENDAR, il conteggio dei numeri di richiesta viene reimpostato su zero all'inizio di ogni nuovo periodo di tempo, come specificato da "unit".

         Ad esempio, se "unit": "DAY", il conteggio dei numeri di richiesta viene inizialmente impostato su zero alla prima creazione dell'abilitazione. Il conteggio viene quindi reimpostato su zero all'inizio del giorno successivo (ovvero, a mezzanotte UTC). Il conteggio viene reimpostato su zero all'inizio del giorno successivo e così via.

       • "operationOnBreach": "<REJECT|ALLOW>" specifica cosa accade se viene superato il numero massimo di richieste nel periodo di tempo della quota. Se si specifica REJECT, le richieste aggiuntive nel periodo di tempo vengono rifiutate e viene restituita una risposta HTTP-429 Too Many Requests. La risposta include l'intestazione Retry-After, che indica il tempo di attesa prima di effettuare una nuova richiesta. Se si specifica ALLOW, sono ancora consentite richieste aggiuntive nel periodo di tempo. Ad esempio, "operationOnBreach": "REJECT"
     • "targets": [{…}] specifica una o più distribuzioni API di destinazione alle quali i sottoscrittori del piano di utilizzo hanno diritto di accedere, dove:
       • "deploymentId": "<target-deployment-ocid>" è l'OCID della distribuzione API che si desidera includere nell'abilitazione. La distribuzione API può appartenere allo stesso compartimento del piano di utilizzo, ma non è necessario. Ad esempio, "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"

         Tenere presente che è necessario aver già reso la distribuzione API idonea per l'inclusione nel piano di utilizzo specificando la posizione di un token client (vedere Come rendere idonea una distribuzione API per l'inclusione in un piano di utilizzo).

   • "compartmentId": "<compartment-ocid>" è l'OCID del compartimento a cui appartiene il nuovo piano di utilizzo. Ad esempio, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

   Ad esempio:

   {
       "displayName": "Gold-usage-plan",
       "entitlements": [{
           "name": "Entitlement1",
           "description": "Basic entitlement for all usage plans",
           "rateLimit": {
               "value": 100,
               "unit": "SECOND"
           },
           "quota": {
               "value": 1000,
               "unit": "MONTH",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "REJECT"
           },
           "targets": [{
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
           }]
       },
       {
           "name": "Entitlement2",
           "description": "Gold plan entitlement",
           "rateLimit": {
               "value": 200,
               "unit": "SECOND"
           },
           "quota": {
               "value": 5000,
               "unit": "WEEK",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "REJECT"
           },
           "targets": [{
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
             },
             {
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaac______nxd"
             }
           ]
         }
       ],
       "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq"
   }

2. Salvare il file di definizione del piano di utilizzo con il nome desiderato. Ad esempio, gold-usageplan.json
3. Utilizzare il file di definizione del piano di utilizzo per creare un piano di utilizzo utilizzando l'interfaccia CLI:
   1. Configurare l'ambiente client per l'uso dell'interfaccia CLI (Configuring Your Client Environment to use the CLI for API Gateway Development).

   2. Aprire un prompt dei comandi ed eseguire oci api-gateway usage-plan create per creare il piano di utilizzo dal file di definizione del piano di utilizzo:

      oci api-gateway usage-plan create --from-json file://<usageplan-definition>.json

      dove:

      • --from-json file://<usageplan-definition>.json è il file che contiene la definizione del piano di utilizzo, incluso un percorso.

      Ad esempio:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json

      La risposta al comando include quanto riportato di seguito.

      • OCID del piano di utilizzo e altri dettagli.
      • Stato del ciclo di vita (ad esempio, ACTIVE, FAILED).
      • ID della richiesta di lavoro per creare il piano di utilizzo (i dettagli delle richieste di lavoro sono disponibili per sette giorni dopo il completamento, l'annullamento o l'errore).

      Se si desidera che il comando attenda la restituzione del controllo fino a quando il piano di utilizzo non è attivo (o la richiesta non è riuscita), includere uno o entrambi i seguenti parametri:

      • --wait-for-state ACTIVE
      • --wait-for-state FAILED

      Ad esempio:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json --wait-for-state ACTIVE

      Tenere presente che non è possibile utilizzare il piano di utilizzo finché la richiesta di lavoro non lo ha creato correttamente e il piano di utilizzo non è attivo.

   3. (Facoltativo) Per visualizzare lo stato del piano di utilizzo, immettere:

      oci api-gateway usage-plan get --usage-plan-id <usage-plan-ocid>

   4. (Facoltativo) Per visualizzare lo stato della richiesta di lavoro che sta creando il piano di utilizzo, immettere:

      oci api-gateway work-request get --work-request-id <work-request-ocid>

   5. (Facoltativo) Per visualizzare i log della richiesta di lavoro che sta creando il piano di utilizzo, immettere:

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>

   6. (Facoltativo) Se la richiesta di lavoro che sta creando il piano di utilizzo non riesce e si desidera esaminare i log degli errori, immettere:

      oci api-gateway work-request-error --work-request-id <work-request-ocid>

   Per ulteriori informazioni sull'uso dell'interfaccia CLI, vedere Command Line Interface (CLI, interfaccia a riga di comando). Per un elenco completo dei flag e delle opzioni disponibili per i comandi della CLI, vedere la Guida della CLI.

Per informazioni sull'uso dell'API e delle richieste di firma, consulta la documentazione dell'API REST e le credenziali di sicurezza. Per informazioni sugli SDK, vedere SDK e l'interfaccia CLI.

Utilizzare l'operazione CreateUsagePlan per creare un piano di utilizzo.