Esegui il deployment dei proxy API utilizzando l'API

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Ogni organizzazione ha un ciclo di vita dello sviluppo software (SDLC) univoco. Spesso è necessario sincronizzare e allineare il deployment dei proxy API con i processi utilizzati per i servizi di backend.

I metodi dell'API Edge illustrati in questo argomento possono essere utilizzati per integrare la gestione dei proxy API nell'SDLC della tua organizzazione. Un utilizzo comune di questa API è la scrittura di script o codice che esegue il deployment dei proxy API o che esegue la migrazione dei proxy API da un ambiente a un altro, nell'ambito di un processo automatizzato più ampio che esegue anche il deployment o la migrazione di altre applicazioni.

L'API Edge non fa ipotesi sul tuo SDLC (o su quello di chiunque altro, per quanto riguarda la questione). Espone invece funzioni atomiche che possono essere coordinate dal tuo team di sviluppo per automatizzare e ottimizzare il ciclo di vita dello sviluppo delle API.

Per informazioni complete, consulta API Edge.

Per utilizzare l'API Edge, devi autenticarti nelle chiamate. Puoi farlo con uno dei seguenti metodi:

Questo argomento si concentra sull'insieme di API per la gestione dei proxy API.

Video: guarda questo breve video per scoprire come eseguire il deployment di un'API.

Interazione con l'API

I seguenti passaggi ti guideranno attraverso semplici interazioni con le API.

Elenco delle API nella tua organizzazione

Puoi iniziare elencando tutti i proxy API nella tua organizzazione. (Ricorda di sostituire le voci per EMAIL:PASSWORD e ORG_NAME. Per le istruzioni, consulta Utilizzare l'API Edge.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Esempio di risposta:

[ "weatherapi" ]

Recupero di un'API

Puoi chiamare il metodo GET su qualsiasi proxy API nella tua organizzazione. Questa chiamata restituisce un elenco di tutte le revisioni disponibili del proxy API.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Esempio di risposta:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

L'unico dettaglio restituito da questo metodo è il nome del proxy API insieme alla revisione associata, a cui è associato un numero. I proxy API sono costituiti da un bundle di file di configurazione file. Le revisioni forniscono un meccanismo leggero per gestire gli aggiornamenti della configurazione durante l'iterazione. Le revisioni sono numerate in sequenza, il che ti consente di annullare una modifica eseguendo il deployment di una revisione precedente del proxy API. Inoltre, puoi eseguire il deployment di una revisione di un proxy API nell'ambiente di produzione, continuando a creare nuove revisioni dello stesso proxy API nell'ambiente di test. Quando è tutto pronto, puoi promuovere la revisione più recente del proxy API dall' ambiente di test alla revisione precedente del proxy API nell'ambiente di produzione.

In questo esempio, è presente una sola revisione perché il proxy API è stato appena creato. Man mano che un proxy API passa attraverso il ciclo di vita della configurazione e del deployment iterativi, il numero di revisione aumenta di numeri interi. Utilizzando le chiamate API dirette per il deployment, puoi aumentare facoltativamente il numero di revisione del proxy API. A volte, quando apporti modifiche secondarie, potresti non voler aumentare la revisione.

Recupero della revisione dell'API

La versione dell'API (ad esempio, api.company.com/v1) dovrebbe cambiare molto raramente. Quando aumenti la versione dell'API, indichi agli sviluppatori che è stato apportato una modifica significativa alla firma dell'interfaccia esterna esposta dall'API.

La revisione del proxy API è un numero incrementato associato a una configurazione del proxy API. I servizi API mantengono le revisioni delle configurazioni in modo che tu possa ripristinare una configurazione in caso di problemi. Per impostazione predefinita, la revisione di un proxy API viene aumentata automaticamente ogni volta che importi un proxy API utilizzando l'API Importa un proxy API. Se non vuoi aumentare la revisione di un proxy API, utilizza l'API Aggiorna la revisione del proxy API. Se utilizzi Maven per il deployment, utilizza le clean o update opzioni, come descritto nel file README del plug-in Maven.

Ad esempio, puoi chiamare il metodo GET sulla revisione 1 del proxy API per ottenere una visualizzazione dettagliata.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Esempio di risposta

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Questi elementi di configurazione del proxy API sono documentati in dettaglio nel riferimento per la configurazione del proxy API.

Deployment di un'API in un ambiente

Una volta configurato il proxy API per ricevere e inoltrare correttamente le richieste, puoi eseguirne il deployment in uno o più ambienti. In genere, esegui l'iterazione sui proxy API in test e poi, quando è tutto pronto, promuovi la revisione del proxy API in prod. Spesso, noterai che hai molte più revisioni di un proxy API nell'ambiente di test, principalmente perché esegui molte meno iterazioni nell'ambiente di produzione.

Un proxy API non può essere richiamato finché non è stato eseguito il deployment in un ambiente. Dopo aver eseguito il deployment della revisione del proxy API in produzione, puoi pubblicare l'URL prod per gli sviluppatori esterni.

Come elencare gli ambienti

Ogni organizzazione in Apigee Edge ha almeno due ambienti: test e prod. La distinzione è arbitraria. L'obiettivo è fornirti un'area in cui verificare che il proxy API funzioni correttamente prima di aprirlo agli sviluppatori esterni.

Ogni ambiente è in realtà solo un indirizzo di rete, che ti consente di separare il traffico tra i proxy API su cui stai lavorando e quelli a cui accedono le app in fase di runtime.

Gli ambienti forniscono anche la separazione di dati e risorse. Ad esempio, puoi configurare cache diverse in test e produzione, a cui possono accedere solo i proxy API in esecuzione in quell' ambiente.

Visualizzazione degli ambienti in un organizzazione

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Esempio di risposta

[ "test", "prod" ]

Esplora i deployment

Un deployment è una revisione di un proxy API di cui è stato eseguito il deployment in un ambiente. Un proxy API nello stato deployed è accessibile tramite la rete, agli indirizzi definiti in l'elemento <VirtualHost> per quell'ambiente.

Deployment dei proxy API

I proxy API non possono essere richiamati finché non è stato eseguito il deployment. I servizi API espongono API RESTful che forniscono il controllo sulla procedura di deployment.

In un determinato momento, è possibile eseguire il deployment di una sola revisione di un proxy API in un ambiente. Pertanto è necessario annullare il deployment della revisione di cui è stato eseguito il deployment. Puoi controllare se il nuovo bundle viene eseguito il deployment come nuova revisione o se sovrascrive la revisione esistente.

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Annulla innanzitutto il deployment della revisione esistente. Specifica il nome dell'ambiente e il numero di revisione di cui vuoi annullare il deployment del proxy API:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Poi esegui il deployment della nuova revisione. La nuova revisione del proxy API deve già esistere: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Deployment senza interruzioni (zero tempi di inattività)

Per ridurre al minimo la possibilità di tempi di inattività durante il deployment, utilizza il override parametro nel metodo di deployment e impostalo su true.

Non puoi eseguire il deployment di una revisione di un proxy API sopra un'altra. Il primo deve sempre essere annullato il deployment. Impostando override su true, indichi che deve essere eseguito il deployment di una revisione di un proxy API sulla revisione di cui è stato eseguito il deployment. Il risultato è che la sequenza di deployment viene invertita: viene eseguito il deployment della nuova revisione e, al termine del deployment, viene annullato il deployment della revisione di cui è stato eseguito il deployment.

L'esempio seguente imposta il valore override passandolo come parametro del modulo: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

Puoi ottimizzare ulteriormente il deployment impostando il parametro delay. Il delay parametro specifica un intervallo di tempo, in secondi, prima del quale deve essere annullato il deployment della revisione precedente. L'effetto è che le transazioni in corso hanno un intervallo di tempo in cui essere completate prima che venga annullato il deployment del proxy API che le elabora. Di seguito è riportato ciò che accade con override=true e il parametro delay impostato:

  • La revisione 1 gestisce le richieste.
  • La revisione 2 viene eseguita il deployment in parallelo.
  • Quando il deployment della revisione 2 è completo, il nuovo traffico viene inviato alla revisione 2. Non viene inviato nuovo traffico alla revisione 1.
  • Tuttavia, la revisione 1 potrebbe ancora elaborare le transazioni esistenti. Impostando il delay parametro (ad esempio, 15 secondi), dai alla revisione 1 15 secondi per completare l'elaborazione delle transazioni esistenti.
  • Dopo l'intervallo di ritardo, viene annullato il deployment della revisione 1.
questa operazione può interrompere altri plug-in e wrapper che utilizzano l'API di deployment senza interruzioni. 
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Parametro di ricerca Descrizione
override

Il valore predefinito è false (comportamento di deployment normale: viene annullato il deployment della revisione esistente, quindi viene eseguito il deployment della nuova revisione).

Imposta su true per sostituire il comportamento di deployment normale e fornire un deployment senza interruzioni. La revisione esistente rimane di cui è stato eseguito il deployment mentre viene eseguito il deployment anche della nuova revisione. Quando viene eseguito il deployment della nuova revisione, viene annullato il deployment della revisione precedente. Utilizza questo parametro insieme al parametro delay per controllare quando si verifica l'annullamento del deployment.
delay

Per consentire il completamento dell'elaborazione delle transazioni nella revisione esistente prima che venga annullato il deployment ed eliminare la possibilità di 502 Bad Gateway o 504 Gateway Timeout errors—imposta questo parametro sul numero di secondi per cui vuoi ritardare l'annullamento del deployment. Non esiste un limite al numero di secondi che puoi impostare e non ci sono ripercussioni sulle prestazioni per l'impostazione di un numero elevato di secondi. Durante il ritardo, non viene inviato nuovo traffico alla revisione precedente.

Il valore predefinito è 0 (zero) secondi. Quando override è impostato su true e delay è 0, viene annullato il deployment della revisione esistente immediatamente dopo il deployment della nuova revisione. I valori negativi vengono trattati come 0 (zero) secondi.

Quando override=true viene utilizzato insieme a un delay, è possibile eliminare le risposte HTTP 5XX durante il deployment. Questo perché verrà eseguito il deployment di entrambe le revisioni del proxy API contemporaneamente, con la revisione precedente annullata dopo il ritardo.

Visualizzazione di tutti i deployment di una revisione dell'API

A volte è necessario recuperare un elenco di tutte le revisioni di un proxy API di cui è stato eseguito il deployment.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

La risposta sopra contiene molte proprietà specifiche dell'infrastruttura interna di Apigee Edge. A meno che tu non utilizzi Apigee Edge on-premise, non puoi modificare queste impostazioni.

Le proprietà importanti contenute nella risposta sono organization, environment, aPIProxy, name e state. Esaminando i valori di queste proprietà, puoi verificare che sia stato eseguito il deployment di una revisione specifica di un proxy API in un ambiente.

Visualizzazione di tutti i deployment nell' ambiente di test

Puoi anche recuperare lo stato del deployment per un ambiente specifico (incluso il numero di revisione del proxy API di cui è stato eseguito il deployment) utilizzando la seguente chiamata:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Questo restituisce lo stesso risultato di sopra per ogni API di cui è stato eseguito il deployment nell'ambiente di test

Visualizzazione di tutti i deployment nella tua organizzazione

Per recuperare un elenco di tutte le revisioni di tutti i proxy API di cui è stato eseguito il deployment in tutti gli ambienti, utilizza il seguente metodo API:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Questo restituisce lo stesso risultato di sopra per tutti i proxy API di cui è stato eseguito il deployment in tutti gli ambienti.

Poiché l'API è RESTful, puoi semplicemente utilizzare il metodo POST, insieme a un payload JSON o XML, sulla stessa risorsa per creare un proxy API.

Viene generato un profilo per il proxy API. La rappresentazione predefinita di un proxy API è in JavaScript Object Notation (JSON). Di seguito è riportata la risposta JSON predefinita alla richiesta POST riportata sopra, che ha creato un proxy API denominato weatherapi. Di seguito è riportata una descrizione di ogni elemento del profilo segue:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Il profilo del proxy API generato mostra la struttura completa di un proxy API:

  • APIProxy revision: l'iterazione numerata in sequenza della configurazione del proxy API, gestita dai servizi API
  • APIProxy name: il nome univoco del proxy API
  • ConfigurationVersion: la versione dei servizi API a cui è conforme la configurazione del proxy API
  • CreatedAt: l'ora in cui è stato generato il proxy API, formattata in formato UNIX
  • CreatedBy: l'indirizzo email dell'utente Apigee Edge che ha creato il proxy API
  • DisplayName: un nome descrittivo per il proxy API
  • LastModifiedAt: l'ora in cui è stato generato il proxy API, formattata in formato UNIX ora
  • LastModifiedBy: l'indirizzo email dell'utente Apigee Edge che ha creato il proxy API
  • Policies: un elenco di policy aggiunte a questo proxy API
  • ProxyEndpoints: un elenco di ProxyEndpoint denominati
  • Resources: un elenco di risorse (JavaScript, Python, Java, XSLT) disponibili per l'esecuzione in questo proxy API
  • TargetServers: un elenco di TargetServer denominati (che possono essere creati utilizzando l'API Management), utilizzati nelle configurazioni avanzate per il bilanciamento del carico
  • TargetEndpoints: un elenco di TargetEndpoint denominati

Tieni presente che molti degli elementi della configurazione del proxy API creati utilizzando il semplice POST metodo riportato sopra sono vuoti. Nei seguenti argomenti imparerai come aggiungere e configurare i componenti chiave di un proxy API.

Puoi anche leggere questi elementi di configurazione nel riferimento per la configurazione del proxy API.

Scripting sull'API

L'articolo Utilizzo dei proxy API di esempio, disponibile su GitHub, fornisce script shell che eseguono il wrapping dello strumento di deployment di Apigee. Se per qualche motivo non puoi utilizzare lo strumento di deployment Python, puoi chiamare direttamente l'API. Entrambi gli approcci sono illustrati negli script di esempio riportati di seguito.

Wrapping dello strumento di deployment

Innanzitutto, assicurati che lo strumento di deployment Python sia disponibile nel tuo ambiente locale.

Poi crea un file in cui inserire le credenziali. Gli script di deployment che scrivi importeranno queste impostazioni, aiutandoti a gestire centralmente le credenziali del tuo account. Nell'esempio della piattaforma API, questo file si chiama setenv.sh.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

Il file riportato sopra rende disponibili tutte le impostazioni per gli script shell che eseguono il wrapping dello strumento di deployment.

Ora crea uno script shell che importi queste impostazioni e le utilizzi per chiamare lo strumento di deployment. (Per un esempio, consulta Esempi della piattaforma API Apigee.)

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

Per semplificare la procedura, crea anche uno script per richiamare e testare l'API, come segue:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Richiamo diretto dell'API

Può essere utile scrivere semplici script shell che automatizzano la procedura di caricamento ed esecuzione del deployment dei proxy API.

Lo script riportato di seguito richiama direttamente l'API Management. Annulla il deployment della revisione esistente di quel proxy API che stai aggiornando, crea un file ZIP dalla directory /apiproxy contenente i file di configurazione del proxy, quindi carica, importa ed esegue il deployment della configurazione.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST