Esegui il deployment dei proxy API utilizzando l'API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

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

I metodi dell'API Edge mostrati in questo argomento possono essere utilizzati per integrare il proxy API per semplificare la gestione dei contenuti SDLC della tua organizzazione. Un uso comune di questa API è la scrittura di script o codice che eseguono il deployment di proxy API o che migrano i proxy API da un ambiente all'altro, nell'ambito un processo automatizzato più grande che esegue anche il deployment o la migrazione di altre applicazioni.

L'API Edge non fa ipotesi sul tuo SDLC (o su chiunque altro, in questo caso). Piuttosto, espone funzioni atomiche che possono essere coordinate dal tuo team di sviluppo per automatizzare e ottimizzare il ciclo di vita di sviluppo delle API.

Per informazioni complete, consulta le API Edge.

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

Questo argomento è incentrato 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 passaggi seguenti illustrano semplici interazioni con le API.

Elenco delle API nella tua organizzazione

Per iniziare, elenca tutti i proxy API nella tua organizzazione. Ricorda di sostituire voci per EMAIL:PASSWORD e ORG_NAME. Per istruzioni, vedi Utilizzare l'API Edge.

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

Esempio di risposta:

[ "weatherapi" ]

Ottieni un'API

Puoi chiamare il metodo GET su qualsiasi proxy API nella tua organizzazione. Questa chiamata restituisce un elenco 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 all'oggetto revision, a cui è associato un numero. I proxy API sono costituiti da un bundle di configurazioni . Le revisioni forniscono un meccanismo leggero per gestire gli aggiornamenti della configurazione man mano che esegui l'iterazione. Le revisioni sono numerate in sequenza per consentirti di annullare una modifica mediante il deployment una revisione precedente del proxy API. Inoltre, puoi eseguire il deployment di una revisione di un proxy API di produzione, continuando a creare nuove revisioni del proxy API completamente gestito di Google Cloud. Quando è tutto pronto, puoi promuovere la revisione superiore del tuo proxy API dal di test rispetto alla revisione precedente del proxy API nell'ambiente di produzione.

In questo esempio è presente una sola revisione perché il proxy API è stato appena creato. Come API il proxy si sposta attraverso il ciclo di vita della configurazione e del deployment iterativi, il numero incrementi per numeri interi. Utilizzando le chiamate API dirette per il deployment, puoi facoltativamente incrementare numero di revisione del proxy API. A volte, quando apporti modifiche di minore entità, potresti non volere e incrementare la revisione.

Ottieni revisione API

La versione dell'API (ad esempio api.company.com/v1) dovrebbe cambiare molto con minore frequenza. Quando incrementa la versione dell'API, gli sviluppatori vedono che c'è una modifica significativa nella firma dell'interfaccia esterna esposta dall'API.

La revisione del proxy API è un numero incrementato associato a un proxy API configurazione. I servizi API mantengono le revisioni delle tue configurazioni in modo che tu possa ripristinare un configurazione quando si verifica un problema. Per impostazione predefinita, la revisione di un proxy API viene vengono incrementati ogni volta che importi un proxy API mediante l'API Importa un proxy API. Se non vuoi incrementare la revisione di un proxy API, utilizza il API di revisione proxy API. Se utilizzi Maven per il deployment, usa clean o update, come descritto nel plug-in Maven file Leggimi.

Ad esempio, puoi chiamare il metodo GET sulla revisione 1 del proxy API per avere 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 nella documentazione di riferimento sulla configurazione del proxy API.

Il 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 dei proxy API in test e poi, quando è tutto pronto, promuovi la revisione del proxy API a prod. Spesso, scoprirai che ci sono molti altri revisioni di un proxy API nell'ambiente di test, principalmente perché si farà molto meno iterazione nell'ambiente di produzione.

Un proxy API non può essere richiamato finché non ne viene eseguito il deployment in un ambiente. Dopo aver ottenuto ha eseguito il deployment della revisione del proxy API in produzione, puoi pubblicare l'URL prod in sviluppatori.

Come elencare gli ambienti

Ogni organizzazione in Apigee Edge dispone di almeno due ambienti: test e prod. La una distinzione è arbitraria. L'obiettivo è fornirti un'area per verificare che il tuo proxy API funzioni correttamente prima di renderlo disponibile a sviluppatori esterni.

Ogni ambiente non è altro che un indirizzo di rete, che ti permette di isolare il traffico tra I proxy API su cui stai lavorando e quelli a cui le app possono accedere in fase di runtime.

Inoltre, gli ambienti assicurano la segregazione di dati e risorse. Ad esempio, puoi impostare diverse cache in fase di test e di produzione, a cui è possibile accedere solo tramite proxy API eseguiti in quel completamente gestito di Google Cloud.

Visualizza gli 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 è la revisione di un proxy API di cui è stato eseguito il deployment in un ambiente. Un'API il proxy in stato Deployment eseguito sia accessibile sulla rete, agli indirizzi definiti <VirtualHost> per quell'ambiente.

Deployment dei proxy API

I proxy API non possono essere richiamati fino a quando non ne viene eseguito il deployment. I servizi API espongono le API RESTful che forniscono il controllo sul processo di deployment.

È possibile eseguire il deployment in un ambiente di una sola revisione alla volta di un proxy API. Pertanto, occorre annullare il deployment della revisione di cui è stato eseguito il deployment. Puoi controllare se viene eseguito il deployment del nuovo bundle o se sovrascriva quella esistente.

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

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

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

quindi 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 (nessun tempo di inattività)

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

Non puoi eseguire il deployment di una revisione di un proxy API su un'altra. Il primo deve essere sempre di cui è stato annullato il deployment. Se imposti override su true, indichi che una revisione di un proxy API deve essere implementato nella revisione attualmente sottoposta a deployment. Il risultato è che la sequenza di deployment viene invertita: viene eseguito il deployment della nuova revisione completato, viene annullato il deployment della revisione di cui è già stato eseguito il deployment.

Nell'esempio seguente, il valore override viene impostato 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. La Il parametro delay specifica un intervallo di tempo, in secondi, prima del quale il parametro senza il deployment della revisione. L'effetto è che le transazioni in corso hanno un intervallo di tempo che devono essere completati prima che venga annullato il deployment del proxy API che elabora la transazione. La persona che segue è cosa succede con override=true e il set di parametri delay:

  • La revisione 1 sta gestendo le richieste.
  • Il deployment della revisione 2 è in corso in parallelo.
  • Una volta completato il deployment della revisione 2, il nuovo traffico viene inviato alla revisione 2. Nessun nuovo traffico è inviate alla Revisione 1.
  • Tuttavia, la revisione 1 potrebbe ancora elaborare transazioni esistenti. Impostando il parametro delay (ad esempio 15 secondi), assegni alla Revisione 1 15 secondi per terminare l'elaborazione delle transazioni esistenti.
  • Dopo l'intervallo di ritardo, viene annullato il deployment della revisione 1.
di Gemini Advanced. 
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 normale del deployment: non è stato eseguito il deployment della revisione esistente, successivo al deployment della nuova revisione).

Impostalo su true per eseguire l'override del normale comportamento del deployment e offrire soluzioni senza interruzioni e deployment continuo. Il deployment della revisione esistente rimane in corso mentre viene eseguito anche la nuova revisione di cui è stato eseguito il deployment. Quando viene eseguito il deployment della nuova revisione, viene annullato il deployment della vecchia revisione. Utilizza in in combinazione con il parametro delay per controllare l'annullamento del deployment .
delay

Per consentire il completamento dell'elaborazione delle transazioni sulla revisione esistente prima che sia non implementato ed elimina la possibilità di 502 Bad Gateway o 504 Gateway Timeout errors: imposta questo parametro sul numero di secondi in base al quale vuoi eseguire l'annullamento del deployment in ritardo. Non esiste un limite al numero di secondi che puoi impostare e ramificazioni delle prestazioni per l'impostazione di un numero elevato di secondi. Durante il ritardo, nessun nuovo viene inviato alla revisione precedente.

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

Quando override=true viene utilizzato insieme a delay, HTTP 5XX durante il deployment possono essere eliminate. Il motivo è che entrambe le revisioni del proxy API il deployment della revisione precedente è stato annullato dopo il ritardo.

Visualizza tutti i deployment di un'API Revisione

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

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 precedente contiene molte proprietà specifiche per l'infrastruttura interna di Apigee perimetrali. A meno che non utilizzi Apigee Edge on-premise, non puoi modificare queste impostazioni.

Le proprietà importanti contenute nella risposta sono organization, environment, aPIProxy, name e state. Di esaminando questi valori delle proprietà, puoi confermare che una revisione specifica di un proxy API sia di cui è stato eseguito il deployment in un ambiente.

Visualizza tutti i deployment nel ambiente di test

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

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

Viene restituito lo stesso risultato riportato sopra per ogni API di cui è stato eseguito il deployment nell'ambiente di test.

Visualizza tutti i deployment in organizzazione

Per recuperare un elenco di tutte le revisioni di cui è stato eseguito il deployment di tutti i proxy API 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 riportato 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 file JSON o XML della stessa risorsa per creare un proxy API.

Viene generato un profilo per il proxy API. La rappresentazione predefinita di un proxy API è in JSON (JavaScript Object Notation). Di seguito è riportata la risposta JSON predefinita alla richiesta POST di cui sopra. che ha creato un proxy API chiamato weatherapi. Una descrizione di ogni elemento del profilo che 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 proxy API generato dimostra la struttura completa di un'API proxy:

  • APIProxy revision: l'iterazione numerata in sequenza del proxy API completamente gestita dai servizi API
  • APIProxy name: il nome univoco del proxy API
  • ConfigurationVersion: versione dei servizi API a cui il proxy API la configurazione sia conforme
  • CreatedAt: ora in cui è stato generato il proxy API, formattato in tempo UNIX
  • CreatedBy: indirizzo email dell'utente Apigee Edge che ha creato l'API proxy
  • DisplayName: un nome semplice per il proxy API
  • LastModifiedAt: ora in cui è stato generato il proxy API, formattato in UNIX ora
  • LastModifiedBy: indirizzo email dell'utente Apigee Edge che ha creato l'API proxy
  • Policies: un elenco di criteri che sono stati aggiunti a questo proxy API
  • ProxyEndpoints: un elenco di ProxyEndpoint denominati
  • Resources: un elenco di risorse (JavaScript, Python, Java, Hadoop) disponibili per da eseguire in questo proxy API
  • TargetServers: un elenco di TargetServer denominati (che possono essere creati utilizzando API di gestione dei dati), utilizzato in configurazioni avanzate ai fini del bilanciamento del carico
  • TargetEndpoints: un elenco di TargetEndpoint denominati

Tieni presente che molti degli elementi della configurazione del proxy API creati utilizzando POST semplice sopra sono vuoti. Nei seguenti argomenti, imparerai ad aggiungere e configurare la chiave componenti di un proxy API.

Puoi trovare informazioni su questi elementi di configurazione anche nel Riferimento alla configurazione del proxy API.

Creazione di script sull'API

La sezione Utilizzo dei proxy API di esempio, disponibili su GitHub forniscono script shell che aggregano lo strumento di deployment di Apigee. Se per qualche motivo non puoi usare lo strumento di deployment Python, puoi chiamare direttamente l'API. Entrambi gli approcci illustrato negli script di esempio riportati di seguito.

Wrapping dello strumento di deployment

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

quindi crea un file in cui inserire le tue credenziali. Gli script di deployment che scrivi importeranno queste impostazioni, aiutandoti a gestire centralmente le credenziali del tuo account. Nell'API Esempio di piattaforma, questo file è denominato 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 tue impostazioni per gli script shell che aggregano il deployment lo strumento a riga di comando gcloud.

Ora crea uno script shell che importi queste impostazioni e le utilizza per chiamare lo strumento di deployment. (Per un esempio, vedi Esempi di piattaforme 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 semplificarti la vita, crea anche uno script per richiamare e testare l'API, che 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 il processo di caricamento deployment dei proxy API.

Lo script riportato di seguito richiama direttamente l'API di gestione. Viene annullato il deployment della revisione esistente il proxy API che stai aggiornando crea un file ZIP dalla directory /apiproxy contenente i file di configurazione del proxy e poi carica, importa ed esegue il deployment 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