Documentazione di Oracle Cloud Infrastructure

Distribuzione di un'API in un gateway API mediante la creazione di una distribuzione API

Scopri come distribuire un'interfaccia API su un gateway API creando una distribuzione API con il servizio API Gateway.

Dopo aver creato un gateway API, puoi distribuire un'API nel gateway API creando una distribuzione API. Quando si crea una distribuzione API, si include una specifica di distribuzione API che definisce l'API. Il servizio API Gateway ispeziona la specifica di distribuzione API per verificare che sia valida.

Puoi utilizzare un singolo gateway API come frontend per più servizi backend:

  • Creazione di una singola distribuzione API nel gateway API, con una specifica di distribuzione API che definisce più servizi backend.
  • Creazione di più distribuzioni API sullo stesso gateway API, ognuna con una specifica di distribuzione API che definisce uno o più servizi backend.

Utilizzo della console per creare una distribuzione API senza problemi

Per utilizzare la console per creare una distribuzione API, immettere la specifica di distribuzione API nelle finestre di dialogo della console.

  1. Nella console aprire il menu di navigazione e fare clic su Servizi per sviluppatori. In Gestione API, fare clic su Gateway.
  2. Scegliere un compartimento in cui si dispone dell'autorizzazione per lavorare.
  3. Nella pagina Gateway fare clic sul nome del gateway API in cui si desidera distribuire l'interfaccia API per visualizzare la pagina Dettagli gateway.
  4. Nella pagina Dettagli gateway selezionare Distribuzioni dalla lista Risorse, quindi fare clic su Crea distribuzione.

  5. Fare clic su Da zero e nella sezione Informazioni di base specificare quanto segue.

    • Nome: il nome della nuova distribuzione API. Evitare di fornire informazioni riservate.

    • Prefisso percorso: percorso in cui distribuire tutti gli instradamenti contenuti nella specifica di distribuzione API. Ad esempio:

      • /v1
      • /v2
      • /test/20191122

      Tenere presente che il prefisso del percorso di distribuzione specificato è il seguente:

      • deve essere preceduta da una barra (/) e può essere solo la singola barra
      • può contenere più barre in avanti (a condizione che non siano adiacenti), ma non deve terminare con una barra in avanti
      • può includere caratteri alfanumerici maiuscoli e minuscoli
      • può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
      • impossibile includere parametri e caratteri jolly

      Inoltre, se una distribuzione API ha una singola barra come prefisso del percorso di distribuzione, questa è l'unica distribuzione API consentita su un determinato gateway API. Non è possibile creare una distribuzione API con una singola barra come prefisso del percorso di distribuzione se esiste già un'altra distribuzione API nello stesso gateway API.

    • Compartimento: compartimento in cui creare la nuova distribuzione API.

  6. (Facoltativo) Nella sezione Criteri di richiesta API, facoltativamente specificare i dettagli dei criteri di richiesta per fornire supporto per:

  7. (Facoltativo) Nella sezione Criteri di log API, facoltativamente specificare un livello di log di esecuzione per registrare le informazioni sull'elaborazione all'interno del gateway API. Vedere Aggiunta di log alle distribuzioni API.

  8. (Facoltativo) Fare clic su Mostra opzioni avanzate e, facoltativamente, 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 definita, è necessario disporre delle autorizzazioni per utilizzare lo spazio di nomi tag. Per ulteriori informazioni sull'applicazione di tag, vedere Tag delle risorse. Se non si è certi di applicare le tag, saltare questa opzione o chiedere a un amministratore. È possibile applicare le tag in un secondo momento.
  9. Fare clic su Avanti per visualizzare la pagina Autenticazione e immettere i dettagli per un criterio di richiesta di autenticazione.

    Per ulteriori informazioni, vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.

  10. Fare clic su Avanti per immettere i dettagli degli instradamenti nella distribuzione dell'API.

  11. Nella sezione Route 1 specificare il primo instradamento nella distribuzione API che esegue il mapping di un percorso e di uno o più metodi a un servizio backend:

    • Percorso: un percorso per le chiamate API che utilizzano i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato è il seguente:

      • è relativo al prefisso del percorso di distribuzione
      • deve essere preceduta da una barra ( / ) e può essere solo la singola barra
      • può contenere più barre in avanti (a condizione che non siano adiacenti) e può terminare con una barra in avanti
      • può includere caratteri alfanumerici maiuscoli e minuscoli
      • può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
      • può includere parametri e caratteri jolly (vedere Aggiunta di parametri di percorso e caratteri jolly ai percorsi di instradamento)
    • Metodi: uno o più metodi accettati dal servizio backend, separati da virgole. Ad esempio, GET, PUT.

    • Aggiungere un backend singolo o Aggiungere più backend: indica se instradare tutte le richieste allo stesso backend o instradare le richieste a backend diversi in base alla variabile di contesto e alle regole immesse.

      Queste istruzioni presuppongono di voler utilizzare un singolo backend, quindi selezionare Aggiungi un backend singolo. In alternativa, se si desidera utilizzare backend diversi, selezionare Aggiungi più backend e seguire le istruzioni in Utilizzo della console per aggiungere la selezione backend dinamica a una specifica di distribuzione API.

    • Tipo backend: il tipo di servizio backend, ovvero uno dei seguenti:
  12. (Facoltativo) Fare clic su Altro instradamento per immettere i dettagli degli instradamenti aggiuntivi.
  13. Fare clic su Avanti per esaminare i dettagli immessi per la nuova distribuzione API.

  14. Fare clic su Crea per creare la nuova distribuzione API.

    La creazione della nuova distribuzione API può richiedere alcuni minuti. Durante la creazione, la distribuzione API viene visualizzata con lo stato Creazione nella pagina Dettagli gateway. Una volta creata correttamente, la nuova distribuzione API viene visualizzata con lo stato Attivo.

    Inoltre, anziché creare immediatamente la nuova distribuzione API, è possibile crearla in un secondo momento utilizzando Resource Manager e Terraform, facendo clic su 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.

  15. Se la distribuzione dell'API è stata visualizzata con stato Attivo per più di alcuni minuti (o se l'operazione di creazione della distribuzione dell'API non è riuscita):

    1. Fare clic sul nome della distribuzione API e fare clic su Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione della distribuzione API.
    2. Fare clic sull'operazione Crea distribuzione 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 della distribuzione API non è riuscita e non è possibile diagnosticare la causa del problema dalle informazioni sulla richiesta di lavoro, vedere Risoluzione dei problemi del gateway API.
  16. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Uso della console per creare una distribuzione API da un file JSON

Per utilizzare la console per creare una distribuzione API, caricare la specifica di distribuzione API da un file JSON:

  1. Nella console aprire il menu di navigazione e fare clic su Servizi per sviluppatori. In Gestione API, fare clic su Gateway.
  2. Scegliere un compartimento in cui si dispone dell'autorizzazione per lavorare.
  3. Nella pagina Gateway fare clic sul nome del gateway API in cui si desidera distribuire l'interfaccia API per visualizzare la pagina Dettagli gateway.
  4. Nella pagina Dettagli gateway selezionare Distribuzioni dalla lista Risorse, quindi fare clic su Crea distribuzione.
  5. Fare clic su Carica un'interfaccia API esistente.

  6. Nella sezione Carica informazioni specificare:

    • Nome: il nome della nuova distribuzione API. Evitare di fornire informazioni riservate.

    • Prefisso percorso: percorso in cui distribuire tutti gli instradamenti contenuti nella specifica di distribuzione API. Ad esempio:

      • /v1
      • /v2
      • /test/20191122

      Tenere presente che il prefisso del percorso di distribuzione specificato è il seguente:

      • deve essere preceduta da una barra (/) e può essere solo la singola barra
      • può contenere più barre in avanti (a condizione che non siano adiacenti), ma non deve terminare con una barra in avanti
      • può includere caratteri alfanumerici maiuscoli e minuscoli
      • può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
      • impossibile includere parametri e caratteri jolly
    • Compartimento: compartimento in cui creare la nuova distribuzione API.
    • Specifica: il file JSON contenente la specifica di distribuzione API, trascinando e rilasciando il file oppure facendo clic su selezionandone uno. Vedere Creazione di una specifica di distribuzione API.

    Inoltre, se una distribuzione API ha una singola barra come prefisso del percorso di distribuzione, questa è l'unica distribuzione API consentita su un determinato gateway API. Non è possibile creare una distribuzione API con una singola barra come prefisso del percorso di distribuzione se esiste già un'altra distribuzione API nello stesso gateway API.

  7. (Facoltativo) Fare clic su Mostra opzioni avanzate e, facoltativamente, 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 definita, è necessario disporre delle autorizzazioni per utilizzare lo spazio di nomi tag. Per ulteriori informazioni sull'applicazione di tag, vedere Tag delle risorse. Se non si è certi di applicare le tag, saltare questa opzione o chiedere a un amministratore. È possibile applicare le tag in un secondo momento.
  8. Fare clic su Avanti per esaminare i dettagli immessi per la nuova distribuzione API.

  9. Fare clic su Crea per creare la nuova distribuzione API.

    La creazione della nuova distribuzione API può richiedere alcuni minuti. Durante la creazione, la distribuzione API viene visualizzata con lo stato Creazione nella pagina Dettagli gateway. Una volta creata correttamente, la nuova distribuzione API viene visualizzata con lo stato Attivo.

    Inoltre, anziché creare immediatamente la nuova distribuzione API, è possibile crearla in un secondo momento utilizzando Resource Manager e Terraform, facendo clic su 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.

  10. Se la distribuzione dell'API è stata visualizzata con stato Attivo per più di alcuni minuti (o se l'operazione di creazione della distribuzione dell'API non è riuscita):

    1. Fare clic sul nome della distribuzione API e fare clic su Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione della distribuzione API.
    2. Fare clic sull'operazione Crea distribuzione 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 della distribuzione API non è riuscita e non è possibile diagnosticare la causa del problema dalle informazioni sulla richiesta di lavoro, vedere Risoluzione dei problemi del gateway API.
  11. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Uso della console per creare una distribuzione API da una risorsa API

È possibile creare una distribuzione API da una risorsa API esistente utilizzando la descrizione API della risorsa API. In questo caso, la descrizione dell'API si basa su un file di descrizione dell'API caricato per la risorsa API (vedere Creazione di una risorsa API con una descrizione dell'API). Il file di descrizione API fornisce alcuni valori iniziali per la specifica di distribuzione API, che è possibile modificare ed estendere durante la creazione della distribuzione API. In particolare, viene creato un instradamento predefinito per ogni percorso e metodo associato nella descrizione dell'API.

Per utilizzare la console per creare una distribuzione API da una risorsa API esistente, utilizzare una specifica di distribuzione API derivata da un file di descrizione API:

  1. Nella console aprire il menu di navigazione e fare clic su Servizi per sviluppatori. In Gestione API, fare clic su Gateway.
  2. Scegliere un compartimento in cui si dispone dell'autorizzazione per lavorare.
  3. Nella pagina API fare clic sul nome della risorsa API che si desidera distribuire.
  4. (Facoltativo) Nella pagina Dettagli API, selezionare Specifica distribuzione API dall'elenco Risorse per confermare la creazione di una specifica di distribuzione API valida per la risorsa API da un file di descrizione API caricato. Se non è disponibile alcuna specifica di distribuzione API, vedere Creazione di una risorsa API con una descrizione API
  5. Nella pagina Dettagli API fare clic su Distribuisci gateway API per utilizzare le finestre di dialogo Console per creare una distribuzione API.

    Alcuni valori iniziali per le proprietà della specifica di distribuzione API, visualizzati nelle finestre di dialogo Console, derivano dal file di descrizione dell'API.

    La sezione Informazioni API mostra i dettagli sulla risorsa API da cui creare la distribuzione API.

  6. Nella sezione Gateway selezionare il gateway API su cui creare la distribuzione API. Se non esiste già un gateway API adatto, fare clic su Crea gateway per crearne uno (vedere Creazione di un gateway API).

  7. Nella sezione Informazioni di base specificare:

    • Nome: il nome della nuova distribuzione API. Evitare di fornire informazioni riservate.

    • Prefisso percorso: percorso in cui distribuire tutti gli instradamenti contenuti nella specifica di distribuzione API.

      Ad esempio:

      • /v1
      • /v2
      • /test/20191122

      Tenere presente che il prefisso del percorso di distribuzione specificato è il seguente:

      • deve essere preceduta da una barra (/) e può essere solo la singola barra
      • può contenere più barre in avanti (a condizione che non siano adiacenti), ma non deve terminare con una barra in avanti
      • può includere caratteri alfanumerici maiuscoli e minuscoli
      • può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
      • impossibile includere parametri e caratteri jolly

      Inoltre, se una distribuzione API ha una singola barra come prefisso del percorso di distribuzione, questa è l'unica distribuzione API consentita su un determinato gateway API. Non è possibile creare una distribuzione API con una singola barra come prefisso del percorso di distribuzione se esiste già un'altra distribuzione API nello stesso gateway API.

    • Compartimento: compartimento in cui creare la nuova distribuzione API.

  8. (Facoltativo) Nella sezione Criteri di richiesta API, facoltativamente specificare i dettagli dei criteri di richiesta per fornire supporto per:

  9. (Facoltativo) Nella sezione Criteri di log API, facoltativamente specificare un livello di log di esecuzione per registrare le informazioni sull'elaborazione all'interno del gateway API. Vedere Aggiunta di log alle distribuzioni API.

  10. (Facoltativo) Fare clic su Mostra opzioni avanzate e, facoltativamente, 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 definita, è necessario disporre delle autorizzazioni per utilizzare lo spazio di nomi tag. Per ulteriori informazioni sull'applicazione di tag, vedere Tag delle risorse. Se non si è certi di applicare le tag, saltare questa opzione o chiedere a un amministratore. È possibile applicare le tag in un secondo momento.

  11. Fare clic su Avanti per esaminare e immettere i dettagli degli instradamenti nella distribuzione API.

    Per impostazione predefinita, viene creato un instradamento per ogni percorso e metodo associato presente nella descrizione dell'API. Inizialmente, ciascuno di questi instradamenti predefiniti viene creato con un back-end di risposta stock. Il codice di stato HTTP, il contenuto nel corpo del contenuto del corpo della risposta e l'intestazione vengono ottenuti dai dettagli nella descrizione dell'API. Se la descrizione dell'API non include informazioni di risposta per un determinato percorso e un metodo associato, viene creato un back-end predefinito di risposta stock per l'instradamento con 501 come codice di stato HTTP.

  12. Esaminare a turno ogni instradamento predefinito, modificandone la configurazione se necessario per soddisfare le proprie esigenze e aggiungendo criteri di richiesta, risposta e log:

    • Percorso: un percorso per le chiamate API che utilizzano i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato è il seguente:

      • è relativo al prefisso del percorso di distribuzione
      • deve essere preceduta da una barra ( / ) e può essere solo la singola barra
      • può contenere più barre in avanti (a condizione che non siano adiacenti) e può terminare con una barra in avanti
      • può includere caratteri alfanumerici maiuscoli e minuscoli
      • può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
      • può includere parametri e caratteri jolly (vedere Aggiunta di parametri di percorso e caratteri jolly ai percorsi di instradamento)
    • Metodi: uno o più metodi accettati dal servizio backend, separati da virgole. Ad esempio, GET, PUT.
    • Tipo: il tipo del servizio backend, come uno dei seguenti:
    • Mostra criteri di richiesta instradamento: e Mostra criteri di risposta instradamento: rivedere e, facoltativamente, aggiornare i criteri di richiesta e di risposta che si applicano all'instradamento. Vedere Aggiunta di criteri di richiesta e di risposta alle specifiche di distribuzione API.
    • Mostra criteri di log degli instradamenti: rivedere e, facoltativamente, aggiornare il criterio di log applicabile all'instradamento. Vedere Aggiunta di log alle distribuzioni API.
  13. (Facoltativo) Fare clic su Altro instradamento per immettere i dettagli di altri instradamenti, oltre a quelli creati per impostazione predefinita dalla descrizione dell'API.
  14. Fare clic su Avanti per esaminare i dettagli immessi per la nuova distribuzione API.

  15. Fare clic su Crea per creare la nuova distribuzione API.

    La creazione della nuova distribuzione API può richiedere alcuni minuti. Durante la creazione, la distribuzione API viene visualizzata con lo stato Creazione nella pagina Dettagli gateway. Una volta creata correttamente, la nuova distribuzione API viene visualizzata con lo stato Attivo.

  16. Se la distribuzione dell'API è stata visualizzata con stato Attivo per più di alcuni minuti (o se l'operazione di creazione della distribuzione dell'API non è riuscita):

    1. Fare clic sul nome della distribuzione API e fare clic su Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione della distribuzione API.
    2. Fare clic sull'operazione Crea distribuzione 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 della distribuzione API non è riuscita e non è possibile diagnosticare la causa del problema dalle informazioni sulla richiesta di lavoro, vedere Risoluzione dei problemi del gateway API.
  17. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Uso dell'interfaccia CLI

Per creare una nuova distribuzione API 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 deployment create per creare la distribuzione:

    oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name> --gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification file:///<filename>

    dove:

    • <compartment-ocid> è l'OCID del compartimento in cui creare la nuova distribuzione API.
    • <api-name> è il nome della nuova distribuzione API. Evitare di fornire informazioni riservate.
    • <gateway-ocid> è l'OCID del gateway esistente su cui distribuire l'API. Per informazioni sull'OCID del gateway API, vedere Elenco dei gateway API e delle distribuzioni API.

    • /<deployment-path-prefix> è un percorso in cui distribuire tutti gli instradamenti contenuti nella specifica di distribuzione API.

      Tenere presente che il prefisso del percorso di distribuzione specificato è il seguente:

      • deve essere preceduta da una barra ( / ) nel file JSON e può essere solo una barra singola
      • può contenere più barre in avanti (a condizione che non siano adiacenti), ma non deve terminare con una barra in avanti
      • può includere caratteri alfanumerici maiuscoli e minuscoli
      • può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
      • impossibile includere parametri e caratteri jolly

      Inoltre, se una distribuzione API ha una singola barra come prefisso del percorso di distribuzione, questa è l'unica distribuzione API consentita su un determinato gateway API. Non è possibile creare una distribuzione API con una singola barra come prefisso del percorso di distribuzione se esiste già un'altra distribuzione API nello stesso gateway API.

    • <filename> è la specifica di distribuzione API, che include un percorso, uno o più metodi e una definizione backend. Vedere Creazione di una specifica di distribuzione API.

    Ad esempio:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json

    La risposta al comando include quanto riportato di seguito.

    • OCID della distribuzione API.

    • Nome host sul quale è stata creata la distribuzione API, sotto forma di nome dominio nel formato <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.com, dove:

      • <gateway-identifier> è la stringa di caratteri che identifica il gateway API. Ad esempio, lak...sjd (abbreviato per leggibilità).
      • <region-identifier> è l'identificativo dell'area in cui è stata creata la distribuzione API. Vedere Disponibilità per area.

      Ad esempio, lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com.

      Il nome host sarà il nome di dominio da utilizzare quando si richiama un'interfaccia API distribuita nel gateway API.

    • Stato del ciclo di vita (ad esempio, ACTIVE, FAILED).
    • ID della richiesta di lavoro per creare la distribuzione dell'API (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 la distribuzione dell'API non è attiva (o la richiesta non è riuscita), includere uno o entrambi i parametri riportati di seguito.

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

    Ad esempio:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state ACTIVE

    Tenere presente che non è possibile utilizzare la distribuzione API finché la richiesta di lavoro non la ha creata correttamente e la distribuzione API non è attiva.

  3. (Facoltativo) Per visualizzare lo stato della distribuzione dell'API, immettere:

    oci api-gateway deployment get --deployment-id <deployment-ocid>

  4. (Facoltativo) Per visualizzare lo stato della richiesta di lavoro che sta creando la distribuzione dell'API, 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 la distribuzione dell'API, immettere:

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

  6. (Facoltativo) Se la richiesta di lavoro che sta creando la distribuzione dell'API 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.