Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Ogni organizzazione ha un ciclo di vita di sviluppo software (SDLC) unico. Spesso è necessario sincronizzare e allineare il deployment del proxy API con i processi utilizzati per i servizi di backend.
I metodi dell'API Edge dimostrati in questo argomento possono essere utilizzati per integrare la gestione dei proxy API nell'SDLC della tua organizzazione. Un utilizzo comune di questa API è scrivere script o codice che eseguono il deployment dei proxy API o che migrano i proxy API da un ambiente all'altro, come parte di un processo automatizzato più ampio che esegue anche il deployment o la migrazione di altre applicazioni.
L'API Edge non fa supposizioni in merito al tuo SDLC (o a quello di chiunque altro). Piuttosto, espone 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 la sezione API Edge.
Per utilizzare l'API Edge, devi autenticarti nelle chiamate. Puoi farlo con uno dei seguenti metodi:
- OAuth2 (solo cloud pubblico)
- SAML (cloud pubblico e privato)
- Autenticazione di base (non consigliata; cloud pubblico e privato)
Questo argomento è incentrato sull'insieme di API utilizzate 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.
Elenca le API nella tua organizzazione
Puoi iniziare elencando tutti i proxy API nella tua organizzazione. (Ricorda di sostituire le voci con 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" ]
Ottieni 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. Le revisioni forniscono un meccanismo leggero per gestire gli aggiornamenti della configurazione durante l'iterazione. Le revisioni sono numerate in sequenza, consentendoti 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 di quel proxy API nell'ambiente di test. Quando è tutto pronto, puoi promuovere la revisione superiore del proxy API dall'ambiente di test rispetto alla revisione precedente del proxy API nell'ambiente di produzione.
In questo esempio, c'è solo una revisione perché il proxy API è stato appena creato. Man mano che un proxy API si sposta nel ciclo di vita della configurazione e del deployment iterativi, il numero di revisione viene incrementato di numeri interi. Utilizzando le chiamate API dirette per il deployment, puoi facoltativamente incrementare il numero di revisione del proxy API. A volte, quando apporti modifiche di minore entità, potresti non voler incrementare la revisione.
Ottieni revisione API
La versione dell'API (ad esempio, api.company.com/v1) dovrebbe cambiare molto
raramente. Se aumenti la versione dell'API, significa agli sviluppatori che c'è stato un cambiamento significativo nella firma dell'interfaccia esterna esposta dall'API.
La revisione del proxy API è un numero incrementato associato alla configurazione di un proxy API. I servizi API conservano le revisioni delle tue configurazioni in modo che tu possa ripristinarne una
se si verifica un problema. Per impostazione predefinita, la revisione di un proxy API viene incrementata automaticamente ogni volta che importi un proxy API utilizzando l'API Importa un proxy API. Se non vuoi incrementare la revisione di un proxy API, utilizza l'API Update API proxy revisione. Se utilizzi Maven per il deployment, usa le opzioni clean o update, come descritto nel Leggimi del plug-in Maven.
Ad esempio, puoi chiamare il metodo GET sulla revisione del proxy API 1 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 alla configurazione del proxy API.
Deployment di un'API in un ambiente
Dopo aver configurato il proxy API per ricevere e inoltrare correttamente le richieste, puoi eseguirne il deployment in uno o più ambienti. Di solito esegui l'iterazione dei proxy API in test e, quando è tutto pronto, promuovi la revisione dei proxy API a prod. Spesso ti accorgerai di avere molte più revisioni di un proxy API nell'ambiente di test, principalmente perché eseguirai molte meno iterazioni nell'ambiente di produzione.
Un proxy API non può essere richiamato fino a quando 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 a sviluppatori esterni.
Ogni ambiente è semplicemente un indirizzo di rete, che ti consente di isolare il traffico tra i proxy API su cui stai lavorando e quelli a cui le app accedono in fase di runtime.
Gli ambienti forniscono inoltre segregazione tra dati e risorse. Ad esempio, puoi configurare cache diverse nei test e in produzione, a cui sono accessibili solo i proxy API in esecuzione in quell'ambiente.
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 è una revisione di un proxy API di cui è stato eseguito il deployment in un ambiente. Un proxy API in stato Deployment è accessibile sulla rete, agli indirizzi definiti nell'elemento <VirtualHost> per l'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 sul processo di deployment.
È possibile eseguire il deployment di una sola revisione di un proxy API alla volta in un ambiente. Di conseguenza, è necessario annullare il deployment della revisione di cui è stato eseguito il deployment. Puoi controllare se viene eseguito il deployment del nuovo bundle come nuova revisione o se sovrascrive la revisione esistente.
Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Annulla prima il deployment della revisione esistente. Specifica il nome dell'ambiente e il numero di revisione del 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 esistere già:
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 potenziale di inattività durante il deployment, utilizza il parametro override
nel metodo di deployment e impostalo su true.
Non puoi eseguire il deployment di una revisione di un proxy API sopra un'altra. Deve sempre essere annullato il deployment del primo. Se imposti override su true, indichi che deve essere eseguito il deployment di una revisione di un proxy API sulla revisione attualmente sottoposta a deployment. Il risultato è che la sequenza di deployment viene invertita: viene eseguito il deployment della nuova revisione e, una volta completato il deployment, viene annullato il deployment della revisione di cui è già stato eseguito il deployment.
Nell'esempio seguente viene impostato 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 parametro delay specifica un intervallo di tempo, in secondi, prima del quale deve essere annullato il deployment della revisione precedente. Di conseguenza, le transazioni in corso hanno un intervallo di tempo da completare prima che venga annullato il deployment del proxy API che elabora la transazione. Di seguito
è riportato ciò che accade con override=true e il set di parametri delay:
- La revisione 1 sta gestendo le richieste.
- È in corso il deployment della revisione 2 in parallelo.
- Quando il deployment della revisione 2 è stato completato, il nuovo traffico viene inviato alla revisione 2. Nessun nuovo traffico viene inviato alla revisione 1.
- Tuttavia, la revisione 1 potrebbe ancora elaborare le transazioni esistenti. Se imposti il parametro
delay(ad esempio, 15 secondi), concedi alla revisione 1 15 secondi per completare l'elaborazione delle transazioni esistenti. - Dopo l'intervallo di ritardo, il deployment della revisione 1 viene annullato.
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 è Impostalo su |
delay |
Per consentire il completamento dell'elaborazione delle transazioni sulla revisione esistente prima dell'annullamento del deployment ed eliminare la possibilità di Il valore predefinito è 0 (zero) secondi. Se |
Quando override=true viene utilizzato insieme a un delay, è possibile eliminare le risposte HTTP 5XX durante il deployment. Il motivo è che il deployment di entrambe le revisioni del proxy API verrà eseguito contemporaneamente, mentre il deployment della revisione precedente verrà annullato dopo il ritardo.
Visualizza tutti i deployment di una revisione API
A volte è necessario recuperare un elenco di tutte le revisioni attualmente di cui è stato eseguito il deployment di un proxy API.
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 riportata 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 questi valori delle proprietà, puoi confermare che in un ambiente è stato eseguito il deployment di una revisione specifica di un proxy API.
Visualizza 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 attualmente di cui è stato eseguito il deployment) utilizzando la chiamata seguente:
curl -u EMAIL:PASSWORD https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments
Questo restituisce lo stesso risultato di cui sopra per ogni API di cui è stato eseguito il deployment nell'ambiente di test
Visualizza tutti i deployment nella tua organizzazione
Per recuperare un elenco di tutte le revisioni attualmente 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 di cui sopra per tutti i proxy API di cui è stato eseguito il deployment in tutti gli ambienti.
Poiché l'API è RESTful, per creare un proxy API puoi semplicemente utilizzare il metodo POST, insieme a un payload JSON o XML
nella stessa risorsa.
Viene generato un profilo per il proxy API. La rappresentazione predefinita di un proxy API è in formato JSON (JavaScript Object notation). Di seguito è riportata la risposta JSON predefinita alla richiesta POST riportata sopra,
che ha creato un proxy API chiamato weatherapi. Segue una descrizione di ogni elemento del profilo:
{
"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 che viene generato dimostra la struttura completa di un proxy API:
APIProxy revision: l'iterazione numerata in sequenza della configurazione del proxy API, come mantenuta dai servizi APIAPIProxy name: il nome univoco del proxy APIConfigurationVersion: versione dei servizi API a cui è conforme la configurazione del proxy APICreatedAt: ora in cui è stato generato il proxy API, nel formato ora UNIXCreatedBy: indirizzo email dell'utente Apigee Edge che ha creato il proxy APIDisplayName: un nome facile da usare per il proxy APILastModifiedAt: ora in cui è stato generato il proxy API, nel formato ora UNIXLastModifiedBy: indirizzo email dell'utente Apigee Edge che ha creato il proxy APIPolicies: un elenco di criteri che sono stati aggiunti a questo proxy APIProxyEndpoints: un elenco di ProxyEndpoint denominatiResources: un elenco di risorse (JavaScript, Python, Java, NoSQL) disponibili per l'esecuzione in questo proxy APITargetServers: un elenco di TargetServers denominati (che possono essere creati utilizzando l'API di gestione), utilizzato in configurazioni avanzate per il bilanciamento del caricoTargetEndpoints: un elenco di TargetEndpoints denominati
Tieni presente che molti degli elementi della configurazione proxy API creati utilizzando il semplice metodo POST riportato sopra sono vuoti. Negli argomenti seguenti imparerai ad aggiungere e configurare i componenti chiave di un proxy API.
Per ulteriori informazioni su questi elementi di configurazione, consulta il Riferimento per la configurazione del proxy API.
Creazione di script rispetto all'API
Gli script Con i proxy API di esempio, disponibili in GitHub, forniscono 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 dimostrati negli script di esempio riportati di seguito.
Aggregazione dello strumento di deployment
Innanzitutto, assicurati che lo strumento di deployment di Python sia disponibile nel tuo ambiente locale.
Quindi, crea un file con le tue credenziali. Gli script di deployment che scrivi importeranno queste impostazioni, consentendoti di gestire centralmente le credenziali del tuo account. Nell'esempio di API Platform, 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 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, 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 semplificare le cose, 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}"
Richiamare direttamente l'API
Può essere utile scrivere script shell semplici che automatizzano il processo di caricamento e deployment dei proxy API.
Lo script seguente richiama direttamente l'API di gestione. Annulla il deployment della revisione esistente del 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 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