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 Gateway API 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, immettendo la specifica di distribuzione API nelle finestre di dialogo della console man mano che si va:

  1. Nella pagina della lista Gateway selezionare il gateway API su cui si desidera distribuire l'interfaccia API. Se hai bisogno di assistenza per trovare la pagina della lista o il gateway API, consulta Elenco dei gateway API.
  2. Nella pagina Dettagli gateway selezionare Distribuzioni dalla lista Risorse, quindi selezionare Crea distribuzione.

  3. Selezionare Da zero e 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.

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

  5. (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.

  6. (Facoltativo) Selezionare 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 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.
  7. Selezionare 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.

  8. Selezionare Avanti per immettere i dettagli degli instradamenti nella distribuzione API.

  9. 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:
  10. (Facoltativo) Selezionare Altro instradamento per immettere i dettagli degli instradamenti aggiuntivi.
  11. Selezionare Avanti per esaminare i dettagli immessi per la nuova distribuzione API.

  12. Selezionare 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, 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.

  13. 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. Selezionare il nome della distribuzione dell'API e selezionare Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione della distribuzione dell'API.
    2. Selezionare l'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.
  14. (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 pagina della lista Gateway selezionare il gateway API su cui si desidera distribuire l'interfaccia API. Se hai bisogno di assistenza per trovare la pagina della lista o il gateway API, consulta Elenco dei gateway API.
  2. Nella pagina Dettagli gateway selezionare Distribuzioni dalla lista Risorse, quindi selezionare Crea distribuzione.
  3. Selezionare Carica un'API esistente.

  4. 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 il file e rilasciandolo oppure selezionando 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.

  5. (Facoltativo) Selezionare 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 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.
  6. Selezionare Avanti per esaminare i dettagli immessi per la nuova distribuzione API.

  7. Selezionare 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, 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 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. Selezionare il nome della distribuzione dell'API e selezionare Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione della distribuzione dell'API.
    2. Selezionare l'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.
  9. (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 pagina della lista API selezionare il nome della risorsa API che si desidera distribuire. Per assistenza nella ricerca della pagina di elenco, vedere Elenco delle risorse API.
  2. (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
  3. Nella pagina Dettagli API, selezionare 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 mostrate nelle finestre di dialogo della console derivano dal file di descrizione dell'API.

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

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

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

  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) Selezionare 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 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.

  9. Selezionare 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.

  10. 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 di servizio backend, come uno dei seguenti:
    • Mostra criteri di richiesta di instradamento: e Mostra criteri di risposta di instradamento: rivedere e, facoltativamente, aggiornare i criteri di richiesta e di risposta applicabili 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.
  11. (Facoltativo) Selezionare Altro instradamento per immettere i dettagli di altri instradamenti, oltre a quelli creati per impostazione predefinita dalla descrizione dell'API.
  12. Selezionare Avanti per esaminare i dettagli immessi per la nuova distribuzione API.

  13. Selezionare 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.

  14. 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. Selezionare il nome della distribuzione dell'API e selezionare Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione della distribuzione dell'API.
    2. Selezionare l'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.
  15. (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 inserire 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.

    • /<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.