Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
In qualità di sviluppatore che lavora con Apigee, le tue attività di sviluppo principali prevedono la configurazione di proxy API che fungono da proxy per le API o i servizi di backend. Questo documento è un riferimento di tutti gli elementi di configurazione disponibili durante la creazione dei proxy API.
Se stai imparando a creare proxy API, ti consigliamo di iniziare con l'argomento Creazione di un proxy API semplice.
Modifica la configurazione del proxy API utilizzando uno dei seguenti metodi:
- Utilizza l'interfaccia utente o l'API di Apigee.
- Scarica il bundle di configurazione del proxy API, modificalo manualmente e carica la nuova configurazione su Apigee, come descritto in Scaricare e caricare un bundle di configurazione proxy API.
Struttura della directory di configurazione del proxy API
Di seguito è riportata la struttura della directory di configurazione del proxy API:
Una configurazione di proxy API è costituita dai seguenti contenuti:
Configurazione di base | Impostazioni di configurazione principali per un proxy API. |
ProxyEndpoint | Impostazioni per la connessione HTTP in entrata (dalla richiesta di app ad Apigee), i flussi di richiesta e risposta e gli allegati dei criteri. |
TargetEndpoint | Impostazioni per la connessione HTTP in uscita (da Apigee al servizio di backend), i flussi di richiesta e risposta e gli allegati dei criteri. |
Flussi | Pipeline di richiesta e risposta ProxyEndpoint e TargetEndpoint a cui è possibile associare i criteri. |
Norme | File di configurazione in formato XML conformi agli schemi dei criteri di Apigee. |
Risorse | Script, file JAR e file YAML a cui fanno riferimento i criteri per eseguire logica personalizzata. |
Configurazione di base
/apiproxy/weatherapi.xml
La configurazione di base per un proxy API, che definisce il nome del proxy API. Il nome deve essere univoco all'interno di un'organizzazione.
Configurazione di esempio:
<APIProxy name="weatherapi"> </APIProxy>
Elementi di configurazione di base
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
APIProxy |
|||
name |
Il nome del proxy API, che deve essere univoco all'interno di un'organizzazione. I caratteri
che puoi utilizzare nel nome sono limitati a quanto segue:
A-Za-z0-9_- |
N/A | Sì |
revision |
Il numero di revisione della configurazione del proxy API. Non è necessario impostare esplicitamente il numero di revisione, poiché Apigee monitora automaticamente la revisione corrente del proxy API. | N/A | No |
ConfigurationVersion |
La versione dello schema di configurazione del proxy API a cui è conforme il proxy API. L'unico valore attualmente supportato è mainVersion 4 e minorVersion 0. Questa impostazione può essere utilizzata in futuro per consentire l'evoluzione del formato del proxy API. | 4.0 | No |
Description |
Una descrizione testuale del proxy API. Se fornita, la descrizione verrà visualizzata nell'interfaccia utente di Apigee. | N/A | No |
DisplayName |
Un nome facile da usare che può essere diverso dall'attributo name della configurazione del proxy API. |
N/A | No |
Policies |
Un elenco di criteri nella directory /policies di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di Apigee.
Si tratta semplicemente di un'impostazione manifest progettata per fornire visibilità sui contenuti del proxy API. |
N/A | No |
ProxyEndpoints |
Un elenco di endpoint del proxy nella directory /proxies di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di Apigee. Si tratta semplicemente di un'impostazione manifest progettata per fornire visibilità sui contenuti del proxy API. |
N/A | No |
Resources |
Un elenco di risorse (JavaScript, Python, Java, YAML) nella directory /resources di questo proxy API. Normalmente viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di Apigee. Si tratta semplicemente di un'impostazione manifest progettata per fornire visibilità sui contenuti del proxy API. |
N/A | No |
Spec |
Identifica la specifica OpenAPI associata al proxy API. Il valore è impostato su un URL o su un percorso nell'archivio delle specifiche. |
N/A | No |
TargetServers |
Un elenco di server di destinazione a cui viene fatto riferimento in qualsiasi endpoint di destinazione di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando Apigee. Si tratta semplicemente di un'impostazione manifest progettata per fornire visibilità sui contenuti del proxy API. | N/A | No |
TargetEndpoints |
Un elenco di endpoint di destinazione nella directory /targets di questo proxy API. Normalmente,
questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di Apigee. Si tratta semplicemente di un'impostazione manifest progettata per fornire visibilità sui contenuti del proxy API. |
N/A | No |
ProxyEndpoint
La seguente immagine mostra il flusso di richiesta/risposta:
/apiproxy/proxies/default.xml
La configurazione di ProxyEndpoint definisce l'interfaccia in entrata (rivolta al client) per un proxy API. Quando configuri un endpoint proxy, imposti una configurazione di rete che definisce in che modo le applicazioni client (app) devono richiamare l'API inviata tramite proxy.
La seguente configurazione ProxyEndpoint di esempio verrà archiviata in /apiproxy/proxies
:
<ProxyEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPProxyConnection> <BasePath>/weather</BasePath> <Properties/> </HTTPProxyConnection> <FaultRules/> <DefaultFaultRule/> <RouteRule name="default"> <TargetEndpoint>default</TargetEndpoint> </RouteRule> </ProxyEndpoint>
Gli elementi di configurazione richiesti in un endpoint proxy di base sono:
Elementi di configurazione ProxyEndpoint
Nome | Descrizione | Predefinito | Obbligatorio? | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ProxyEndpoint |
||||||||||||||||||
name |
Il nome dell'endpoint proxy. Deve essere univoco all'interno della configurazione del proxy API quando (in rari casi) vengono definiti più endpoint proxy. I caratteri che puoi utilizzare nel nome sono limitati a quanto segue: A-Za-z0-9._\-$ % . |
N/A | Sì | |||||||||||||||
PreFlow |
Definisce i criteri nel flusso PreFlow di una richiesta o risposta. | N/A | Sì | |||||||||||||||
Flows |
Definisce i criteri nei flussi condizionali di una richiesta o risposta.
|
N/A | Sì | |||||||||||||||
PostFlow |
Definisce i criteri nel flusso PostFlow di una richiesta o risposta.
|
N/A | Sì | |||||||||||||||
HTTPProxyConnection |
Definisce l'indirizzo di rete e il percorso URI associati al proxy API. | |||||||||||||||||
BasePath |
Una stringa obbligatoria che identifica in modo univoco il percorso dell'URI utilizzato da Apigee per instradare i messaggi in entrata al proxy API appropriato. Il BasePath è un frammento URI (ad esempio Utilizzo di un carattere jolly nei percorsi di base Puoi utilizzare uno o più caratteri jolly "*" nei percorsi di base del proxy API. Ad esempio, un percorso di base di Importante: Apigee NON supporta l'utilizzo di un carattere jolly "*" come primo elemento di un percorso di base. Ad esempio, questo elemento NON è supportato: |
/ | Sì | |||||||||||||||
Properties |
Un insieme di impostazioni di configurazione HTTP facoltative può essere definito come proprietà di un
<ProxyEndpoint> .
Utilizza la proprietà <Property name= \ "request.queryparams.ignore.content.type.charset">true</>
La tabella seguente mostra un output di esempio in base all'impostazione della proprietà
|
N/A | No | |||||||||||||||
FaultRules |
Definisce in che modo l'endpoint del proxy reagisce a un errore. Una regola di errore specifica due elementi:
Consulta la sezione Gestione degli errori. |
N/A | No | |||||||||||||||
DefaultFaultRule |
Gestisce tutti gli errori (sistema, trasporto, messaggi o criteri) che non sono gestiti esplicitamente da un'altra regola di errore. Consulta la sezione Gestione degli errori. |
N/A | No | |||||||||||||||
RouteRule |
Definisce la destinazione dei messaggi di richiesta in entrata dopo l'elaborazione da parte della pipeline di richieste ProxyEndpoint. Di solito, RouteRule punta a un endpoint di destinazione denominato, a un IntegrationEndpoint o a un URL. | |||||||||||||||||
Name |
Attributo obbligatorio, che fornisce un nome per la RouteRule. I caratteri che puoi utilizzare nel nome sono limitati a quanto segue: A-Za-z0-9._\-$ % . Ad
esempio, Cat2 %_ è un nome legale. |
N/A | Sì | |||||||||||||||
Condition |
Un'istruzione condizionale facoltativa utilizzata per il routing dinamico in fase di runtime. Le RouteRules condizionali sono utili, ad esempio, per abilitare il routing basato sui contenuti al fine di supportare il controllo delle versioni del backend. | N/A | No | |||||||||||||||
TargetEndpoint |
Una stringa facoltativa che identifica una configurazione TargetEndpoint denominata. Un endpoint di destinazione denominato è qualsiasi endpoint di destinazione definito nello stesso proxy API nella directory Denominando un endpoint di destinazione, indichi dove inoltrare i messaggi di richiesta dopo l'elaborazione da parte della pipeline delle richieste ProxyEndpoint. Tieni presente che si tratta di un'impostazione facoltativa. Un endpoint del proxy può chiamare direttamente un URL. Ad esempio, una risorsa JavaScript o Java, con il ruolo di client HTTP, potrebbe eseguire il compito di base di un endpoint di destinazione, ovvero inoltrare le richieste a un servizio di backend. |
N/A | No | |||||||||||||||
URL |
Una stringa facoltativa che definisce un indirizzo di rete in uscita chiamato dall'endpoint proxy, bypassando qualsiasi configurazione TargetEndpoint che potrebbe essere archiviata in /targets |
N/A | No |
Come configurare RouteRules
Un endpoint di destinazione denominato fa riferimento a un file di configurazione in /apiproxy/targets
a cui RouteRule inoltra una richiesta dopo l'elaborazione da parte dell'endpoint proxy.
Ad esempio, la seguente RouteRule fa riferimento alla configurazione
/apiproxy/targets/myTarget.xml
:
<RouteRule name="default"> <TargetEndpoint>myTarget</TargetEndpoint> </RouteRule>
Chiamata URL diretta
Un endpoint proxy può anche richiamare direttamente un servizio di backend. La chiamata di un URL diretto ignora qualsiasi configurazione TargetEndpoint denominata in /apiproxy/targets
). Per questo motivo, TargetEndpoint è una configurazione facoltativa del proxy API, anche se, in pratica, non è consigliata la chiamata diretta dall'endpoint proxy.
Ad esempio, la seguente RouteRule esegue una chiamata HTTP a
http://api.mycompany.com/v2
.
<RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Route condizionali
RouteRules può essere concatenata per supportare il routing dinamico in fase di runtime. Le richieste in entrata possono essere instradate a configurazioni TargetEndpoint denominate, direttamente agli URL o a una combinazione delle due, in base a intestazioni HTTP, contenuto dei messaggi, parametri di ricerca o informazioni contestuali come ora del giorno, impostazioni internazionali e così via.
Le regole di route condizionali funzionano come altre istruzioni condizionali su Apigee. Consulta le sezioni Riferimento alle condizioni e Riferimento per le variabili di flusso.
Ad esempio, la seguente combinazione RouteRule valuta prima la richiesta in entrata per verificare il valore di un'intestazione HTTP. Se l'intestazione HTTP routeTo
ha il valore
TargetEndpoint1
, la richiesta viene inoltrata all'endpoint di destinazione denominato
TargetEndpoint1
. In caso contrario, la richiesta in entrata viene inoltrata a
http://api.mycompany.com/v2
.
<RouteRule name="MyRoute"> <Condition>request.header.routeTo = "TargetEndpoint1"</Condition> <TargetEndpoint>TargetEndpoint1</TargetEndpoint> </RouteRule> <RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Route null
È possibile definire una RouteRule null per supportare scenari in cui il messaggio della richiesta non deve essere inoltrato all'endpoint di destinazione. Questo è utile quando l'endpoint proxy esegue tutte le elaborazioni necessarie, ad esempio utilizzando JavaScript per chiamare un servizio esterno o recuperando dati da una ricerca nell'archivio chiavi/valore Apigee.
Ad esempio, quanto segue definisce una route nulla:
<RouteRule name="GoNowhere"/>
Le route null condizionali possono essere utili. Nell'esempio seguente, è configurata una route nulla per l'esecuzione
quando un'intestazione HTTP request.header.X-DoNothing
ha un valore diverso da
null
.
<RouteRule name="DoNothingOnDemand"> <Condition>request.header.X-DoNothing != null</Condition> </RouteRule>
Ricorda che RouteRules può essere concatenata, quindi una route nulla condizionale è in genere un componente di un insieme di RouteRules progettato per supportare il routing condizionale.
Un uso pratico di una route null condizionale supporta la memorizzazione nella cache. Utilizzando il valore della variabile impostato dal criterio Cache, puoi configurare un proxy API per eseguire la route null quando viene fornita una voce dalla cache.
<RouteRule name="DoNothingUnlessTheCacheIsStale"> <Condition>lookupcache.LookupCache-1.cachehit is true</Condition> </RouteRule>
TargetEndpoint
Un endpoint di destinazione è l'equivalente in uscita di un endpoint proxy. Un endpoint di destinazione funziona come client per un'API o un servizio di backend: invia richieste e riceve risposte.
Un proxy API non deve avere endpoint di destinazione. Gli endpoint proxy possono essere configurati per chiamare direttamente gli URL. Un proxy API senza endpoint di destinazione di solito contiene un endpoint proxy che chiama direttamente un servizio di backend o che è configurato per chiamare un servizio utilizzando Java o JavaScript.
Configurazione TargetEndpoint
/targets/default.xml
L'endpoint di destinazione definisce la connessione in uscita da Apigee a un altro servizio o risorsa.
Ecco una configurazione TargetEndpoint di esempio:
<TargetEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> <SSLInfo/> <Authentication/> </HTTPTargetConnection> <FaultRules/> <DefaultFaultRule/> <ScriptTarget/> <LocalTargetConnection/> </TargetEndpoint>
Elementi di configurazione TargetEndpoint
Un endpoint di destinazione può chiamare un target in uno dei seguenti modi:
- HTTPTargetConnection per chiamate HTTP o HTTPS
- LocalTargetConnection per il concatenamento da proxy a proxy locale
Configurane solo uno in un endpoint di destinazione.
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
TargetEndpoint |
|||
name |
Il nome dell'endpoint di destinazione, che deve essere univoco all'interno della configurazione del proxy API. Il nome dell'endpoint di destinazione viene utilizzato nella RouteRule ProxyEndpoint per indirizzare le richieste per l'elaborazione in uscita. I caratteri che puoi utilizzare nel nome
sono limitati a quanto segue: A-Za-z0-9._\-$ % . |
N/A | Sì |
PreFlow |
Definisce i criteri nel flusso PreFlow di una richiesta o risposta. | N/A | Sì |
Flows |
Definisce i criteri nei flussi condizionali di una richiesta o risposta.
|
N/A | Sì |
PostFlow |
Definisce i criteri nel flusso PostFlow di una richiesta o risposta.
|
N/A | Sì |
HTTPTargetConnection |
Con gli elementi figlio, specifica una risorsa di backend raggiunta tramite HTTP. Se utilizzi HTTPTargetConnection, non configurare altri tipi di connessioni di destinazione (ScriptTarget o LocalTargetConnection).
Puoi utilizzare l'elemento secondario |
||
URL |
Definisce l'indirizzo di rete del servizio di backend a cui l'endpoint di destinazione inoltra i messaggi di richiesta. | N/A | No |
LoadBalancer |
Definisce una o più configurazioni TargetServer denominate. Le configurazioni TargetServer denominate possono essere utilizzate per il bilanciamento del carico che definisce due o più connessioni di configurazione degli endpoint. Puoi anche utilizzare i server di destinazione per disaccoppiare le configurazioni proxy API dagli URL concreti degli endpoint del servizio di backend. |
N/A | No |
Properties |
Un insieme di impostazioni di configurazione HTTP facoltative può essere definito come proprietà di un
<TargetEndpoint> . |
N/A | No |
SSLInfo |
Facoltativamente, definisci le impostazioni TLS/SSL su un endpoint di destinazione per controllare la connessione TLS/SSL tra il proxy API e il servizio di destinazione. Vedi Configurazione degli endpoint di destinazione TLS/SSL. | N/A | No |
LocalTargetConnection |
Con gli elementi figlio, specifica una risorsa da raggiungere localmente, bypassando le caratteristiche di rete come il bilanciamento del carico e i processori di messaggi.
Per specificare la risorsa di destinazione, includi l'elemento secondario APIProxy (con l'elemento ProxyEndpoint) o l'elemento figlio Percorso. Per maggiori informazioni, consulta la sezione Utilizzare insieme i proxy API di Cahaining. Se utilizzi LocalTargetConnection, non configurare altri tipi di connessioni di destinazione (HTTPTargetConnection o ScriptTarget). |
||
APIProxy |
Specifica il nome di un proxy API da utilizzare come target per le richieste. Il proxy di destinazione deve trovarsi nella stessa organizzazione e nello stesso ambiente delle richieste di invio del proxy. Si tratta di un'alternativa all'utilizzo dell'elemento Path. | N/A | No |
ProxyEndpoint |
Utilizzato con APIProxy per specificare il nome dell'endpoint proxy del proxy di destinazione. | N/A | No |
Path |
Specifica il percorso dell'endpoint di un proxy API da utilizzare come destinazione per le richieste. Il proxy di destinazione deve trovarsi nella stessa organizzazione e nello stesso ambiente delle richieste di invio del proxy. Questa è un'alternativa all'utilizzo di APIProxy. | N/A | No |
FaultRules |
Definisce in che modo l'endpoint di destinazione reagisce a un errore. Una regola di errore specifica due elementi:
Consulta la sezione Gestione degli errori. |
N/A | No |
DefaultFaultRule |
Gestisce tutti gli errori (sistema, trasporto, messaggi o criteri) che non sono gestiti esplicitamente da un'altra FaultRule. Consulta la sezione Gestione degli errori. |
N/A | No |
Utilizzo di <Authentication>
elementi
L'utilizzo dell'elemento <Authentication>
in <TargetEndpoint>
è identico a quello
dell'elemento <Authentication>
nelle
norme di ServiceCallout. Sia in <TargetEndpoint>
che in Callout di servizio, <Authentication>
è un elemento secondario di <HttpTargetConnection>
. Per i dettagli, consulta Elemento di autenticazione nel riferimento delle norme di Callout di servizio.
Riferimento all'errore dell'elemento <Authentication>
Se utilizzi l'elemento <Authentication>
, puoi trovare possibili messaggi di errore e suggerimenti per la risoluzione degli errori di deployment e runtime nella sezione Errori della documentazione relativa ai criteri ServiceCallout.
Esempi di elementi <Authentication>
L'esempio seguente mostra come chiamare un servizio di cui è stato eseguito il deployment in Cloud Run come destinazione utilizzando l'elemento Authentication
per generare un token OpenID Connect necessario per autenticare la chiamata:
<TargetEndpoint name="TargetEndpoint-1"> <HTTPTargetConnection> <Properties/> <URL>https://cloudrun-hostname.a.run.app/test</URL> <Authentication> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app/test</Audience> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </TargetEndpoint>
L'esempio seguente mostra come chiamare un TargetService che punta a Cloud Run utilizzando l'elemento Authentication
per generare un token OpenID Connect necessario per autenticare la chiamata. L'elemento HeaderName
aggiunge il token di connessione generato a un'intestazione denominata X-Serverless-Authorization
che viene inviata al sistema di destinazione. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata nella richiesta.
<TargetEndpoint name="TargetEndpoint-1"> <HTTPTargetConnection> <Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication> <LoadBalancer> <Server name="cloud-run-target" /> </LoadBalancer> </HTTPTargetConnection> </TargetEndpoint>
L'esempio seguente mostra come chiamare un servizio TargetService che punta al servizio Google Secret Manager. In questo esempio, l'elemento GoogleAccessToken è configurato per generare un token di autenticazione Google per autenticare la richiesta di destinazione:
<HTTPTargetConnection> <Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication> <URL> https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id </URL> </HTTPTargetConnection>
L'esempio seguente mostra come impostare automaticamente il pubblico di GoogleIDToken. Quando
useTargetUrl
è true
e la variabile di riferimento non si risolve in
una variabile valida, come segmento di pubblico viene utilizzato l'URL del target (esclusi i parametri di query).
Supponiamo che il percorso della richiesta sia /foobar
e l'URL del server di destinazione sia https://xyz.com
. Il pubblico di GoogleIDToken verrà impostato automaticamente su https://xyz.com/foobar
.
<TargetEndpoint name="TargetEndpoint-1"> <HTTPTargetConnection> <Authentication> <GoogleIDToken> <Audience ref='myvariable' useTargetUrl="true"/> </GoogleIDToken> </Authentication> <LoadBalancer> <Server name="TS" /> </LoadBalancer> </HTTPTargetConnection> </TargetEndpoint>
Configurazione dell'endpoint di destinazione TLS/SSL
Gli endpoint di destinazione spesso devono gestire le connessioni HTTPS con un'infrastruttura di backend eterogenea. Per questo motivo, sono supportate diverse impostazioni di configurazione TLS/SSL.
Elementi di configurazione di TargetEndpoint TLS/SSL
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
SSLInfo |
|||
Enabled |
Il blocco <SSLInfo> può essere utilizzato per TLS/SSL sia a una che a due vie.
Se impostato su Il valore predefinito di |
true se <URL> specifica HTTPS |
No |
Enforce |
Applica il livello di conformità SSL tra Apigee e il backend di destinazione. Se il criterio viene impostato su Se il criterio non viene configurato o se viene impostato su |
false |
No |
TrustStore |
Un archivio chiavi contenente certificati server attendibili. | N/A | No |
ClientAuthEnabled |
Abilita il protocollo TLS a due vie (noto anche come TLS reciproco o mTLS) tra Apigee e il client API o tra Apigee e il backend di destinazione. L'abilitazione del TLS bidirezionale richiede in genere la configurazione di un archivio attendibilità su Apigee e un archivio attendibilità. |
false |
No |
KeyStore |
Un archivio chiavi contenente chiavi private utilizzate per l'autenticazione client in uscita | N/A | Sì (se ClientAuthEnabled è true) |
KeyAlias |
L'alias di chiave della chiave privata utilizzata per l'autenticazione client in uscita | N/A | Sì (se ClientAuthEnabled è true) |
IgnoreValidationErrors |
Indica se gli errori di convalida vengono ignorati. Se il sistema di backend utilizza SNI e restituisce un certificato con un nome distinto (DN) del soggetto che non corrisponde al nome host, non è possibile ignorare l'errore e la connessione non riesce. Nota: se |
false |
No |
Ciphers |
Crittografia supportate per TLS/SSL in uscita. Se non vengono specificate crittografie, saranno consentite tutte le crittografie disponibili per JVM. Per limitare le crittografie, aggiungi i seguenti elementi che elencano le crittografie supportate: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers> |
N/A | No |
Protocols |
Protocolli supportati per TLS/SSL in uscita. Se non viene specificato alcun protocollo, saranno consentiti tutti i protocolli disponibili per la JVM. Per limitare i protocolli, specificali esplicitamente. Ad esempio, per consentire solo TLS v1.2 o TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols> |
N/A | No |
CommonName |
Il nome comune TLS del certificato | N/A | No |
Esempio di endpoint di destinazione con autenticazione client in uscita abilitata
<TargetEndpoint name="default"> <HttpTargetConnection> <URL>https://myservice.com</URL> <SSLInfo> <Enabled>true</Enabled> <Enforce>true</Enforce> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>myKeystore</KeyStore> <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> </SSLInfo> </HttpTargetConnection> </TargetEndpoint>
Per istruzioni dettagliate, vedi Opzioni per la configurazione di TLS.
Utilizzo delle variabili di flusso per impostare i valori TLS/SSL in modo dinamico
Puoi anche impostare dinamicamente i dettagli TLS/SSL per supportare requisiti di runtime flessibili. Ad esempio, se il proxy si connette a due destinazioni potenzialmente diverse (una destinazione di test e una di produzione), puoi fare in modo che il proxy API rilevi in modo programmatico l'ambiente che sta chiamando e imposti dinamicamente i riferimenti all'archivio chiavi e all'archivio di attendibilità appropriati. L'articolo della SSLInfo dinamiche per TargetEndpoint utilizzando il riferimento variabile L'articolo della community Apigee spiega questo scenario in modo più dettagliato e fornisce esempi di proxy API di cui è possibile eseguire il deployment.
Nell'esempio seguente di come il tag <SSLInfo>
verrebbe impostato in una configurazione TargetEndpoint, i valori possono essere forniti in fase di runtime, ad esempio da un callout Java, un criterio JavaScript o un criterioAssignMessage. Utilizza le variabili del messaggio che contengono i valori che vuoi impostare.
Le variabili sono consentite solo nei seguenti elementi.
<SSLInfo> <Enabled>{myvars.ssl.enabled}</Enabled> <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled> <KeyStore>{myvars.ssl.keystore}</KeyStore> <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias> <TrustStore>{myvars.ssl.trustStore}</TrustStore> </SSLInfo>
Utilizzo dei riferimenti per impostare i valori TLS/SSL in modo dinamico
Quando configuri un endpoint di destinazione che utilizza HTTPS, devi considerare se il certificato TLS/SSL scade o se una modifica alla configurazione di sistema richiede l'aggiornamento del certificato.
Per maggiori informazioni, consulta Gestione dei certificati scaduti.
Tuttavia, se vuoi, puoi configurare l'endpoint di destinazione in modo da utilizzare invece un riferimento all'archivio chiavi o all'archivio di attendibilità. Il vantaggio dell'utilizzo di un riferimento è che puoi aggiornare il riferimento in modo che punti a un archivio chiavi o a un altro archivio di attendibilità per aggiornare il certificato TLS/SSL senza dover riavviare i processori di messaggi.
Ad esempio, nell'esempio seguente è riportato un endpoint di destinazione che utilizza un riferimento all'archivio chiavi:
<SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://keystoreref</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo>
Utilizza la seguente chiamata API POST per creare il riferimento denominato
keystoreref
:
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -d '<ResourceReference name="keystoreref"> <Refers>myTestKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>'
Dove $TOKEN
è impostato sul token di accesso OAuth 2.0, come descritto in
Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl
utilizzate in questo esempio, consulta
Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.
Il riferimento specifica il nome e il tipo dell'archivio chiavi.
Per visualizzare il riferimento, utilizza la seguente chiamata API GET:
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -H "Authorization: Bearer $TOKEN"
Dove $TOKEN
è impostato sul token di accesso OAuth 2.0, come descritto in
Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl
utilizzate in questo esempio, consulta
Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -H "Authorization: Bearer $TOKEN"
Dove $TOKEN
è impostato sul token di accesso OAuth 2.0, come descritto in
Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl
utilizzate in questo esempio, consulta
Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.
Per modificare in un secondo momento il riferimento in modo che punti a un archivio chiavi diverso, assicurandoti che l'alias abbia lo stesso nome, usa la seguente chiamata PUT:
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -X PUT \ -H "Authorization: Bearer $TOKEN" \ -d '<ResourceReference name="keystoreref"> <Refers>myNewKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>'
Dove $TOKEN
è impostato sul token di accesso OAuth 2.0, come descritto in
Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl
utilizzate in questo esempio, consulta
Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.
TargetEndpoint con bilanciamento del carico di destinazione
Gli endpoint di destinazione supportano il bilanciamento del carico tra più server di destinazione denominati utilizzando tre algoritmi di bilanciamento del carico.
Per istruzioni dettagliate, consulta Bilanciamento del carico tra server di backend.
IntegrationEndpoint
Un IntegrationEndpoint è un endpoint di destinazione che esegue specificamente le integrazioni Apigee. Se hai configurato un IntegrationEndpoint, Apigee invia l'oggetto request alla piattaforma di integrazione di Apigee per l'esecuzione. Per eseguire l'integrazione, oltre a configurare IntegrationEndpoint, devi aggiungere anche il criterio SetIntegrationRequest nel flusso del proxy.
Puoi configurare l'integrazione in modo che venga eseguita in modo sincrono o asincrono impostando l'elemento <AsyncExecution>
nella configurazione di IntegrationEndpoint. Per saperne di più, consulta Esecuzione sincrona e asincrona.
Dopo aver eseguito l'integrazione, Apigee salva la risposta nel messaggio di risposta.
Configurazione di IntegrationEndpoint
Per configurare un endpoint di integrazione come endpoint di destinazione, aggiungi l'elemento IntegrationEndpoint alla configurazione ProxyEndpoint. Di seguito è riportata una configurazione di ProxyEndpoint di esempio:
<ProxyEndpoint name="default"> <Description/> <FaultRules/> <PreFlow name="PreFlow"> <Request> <Step> <Name>my-set-integration-request-policy</Name> </Step> </Request> </PreFlow> <Flows/> <PostFlow name="PostFlow"/> <HTTPProxyConnection> <BasePath>/integration-endpoint-test</BasePath> <Properties/> </HTTPProxyConnection> <RouteRule name="default"> <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint> </RouteRule> </ProxyEndpoint>
Nella configurazione ProxyEndpoint di esempio, Apigee esegue le seguenti attività:
- Nel preFlow esegue il criterio denominato
my-set-integration-request-policy
, che imposta l'oggetto della richiesta di integrazione e le variabili del flusso di integrazione. - Usa
my-int-endpoint
come endpoint di destinazione, come specificato inRouteRule
. - Legge l'oggetto richiesta di integrazione creato da
my-set-integration-request-policy
. - Invia la richiesta alla piattaforma di integrazione di Apigee utilizzando l'oggetto di richiesta e le variabili di flusso impostate dal criterio SetIntegrationRequest.
- Salva la risposta dell'integrazione nel messaggio di risposta.
Il file XML contenente la dichiarazione <IntegrationEndpoint>
sarà disponibile nella directory APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/
. Se crei il proxy API utilizzando l'opzione Develop > API Proxies > CREATE NEW > Integration target
, Apigee archivia la dichiarazione nel file /apiproxy/integration-endpoints/default.xml
. Se crei il file XML dell'endpoint di integrazione dalla UI, puoi fornire un nome personalizzato per il file XML.
L'esempio seguente mostra la dichiarazione dell'elemento <IntegrationEndpoint>
nel file XML:
<IntegrationEndpoint name="my-int-endpoint"> <AsyncExecution>false</AsyncExecution> </IntegrationEndpoint>
Elementi di configurazione di IntegrationEndpoint
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
IntegrationEndpoint |
|||
name |
Il nome di IntegrationEndpoint. I caratteri
che puoi usare nel nome sono limitati a:
A-Za-z0-9._\-$ % |
N/A | Sì |
AsyncExecution |
Un valore booleano che specifica se l'integrazione deve essere eseguita in modalità sincrona o asincrona. Per saperne di più, consulta Esecuzione sincrona e asincrona. | false | No |
Esecuzione sincrona e asincrona
Puoi configurare l'integrazione in modo che venga eseguita in modalità sincrona o asincrona. Per comprendere la differenza tra le modalità di esecuzione sincrona e asincrona, consulta <AsyncExecution>.
Utilizza l'elemento <AsyncExecution>
all'interno di </IntegrationEndpoint>
per specificare l'esecuzione sincrona o asincrona. Se imposti
<AsyncExecution>
su true
, l'integrazione viene eseguita in modo asincrono. E se lo imposti su false
, l'integrazione viene eseguita in modo sincrono.
Nell'esempio seguente viene impostato il valore AsyncExecution
su true
:
<IntegrationEndpoint name="my-int-endpoint"> <AsyncExecution>true</AsyncExecution> </IntegrationEndpoint>
Norme
La directory /policies
in un proxy API contiene tutti i criteri disponibili per il collegamento a Flows nel proxy API.
Elementi di configurazione dei criteri
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
Policy |
|||
name |
Il nome interno del criterio. I caratteri che puoi usare nel nome sono limitati a: Facoltativamente, utilizza l'elemento |
N/A | Sì |
enabled |
Imposta il criterio su Imposta su |
true |
No |
continueOnError |
Imposta il criterio su Impostalo su |
false |
No |
async |
Se il criterio viene impostato su Per utilizzare il comportamento asincrono nei proxy API, consulta Modello a oggetti JavaScript. |
false |
No |
Allegato criterio
La seguente immagine mostra la sequenza di esecuzione dei flussi del proxy API:
Come mostrato sopra:
I criteri sono allegati ai Flussi come passaggi di elaborazione. Il nome del criterio viene utilizzato per fare riferimento al criterio da applicare come passaggio di elaborazione. Il formato dell'allegato del criterio è il seguente:
<Step><Name>MyPolicy</Name></Step>
I criteri vengono applicati nell'ordine in cui sono associati a un flusso. Ad esempio:
<Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step>
Elementi di configurazione degli allegati dei criteri
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
Step |
|||
Name |
Il nome del criterio che deve essere eseguito da questa definizione di passaggio. | N/A | Sì |
Condition |
Un'istruzione condizionale che determina se il criterio viene applicato o meno. Se a un criterio è associata una condizione, questo viene eseguito solo se l'istruzione condizionale restituisce true. | N/A | No |
Flussi
ProxyEndpoint e TargetEndpoint definiscono una pipeline per l'elaborazione dei messaggi di richieste e risposte. Una pipeline di elaborazione è composta da un flusso di richiesta e un flusso di risposta. Ogni flusso di richieste e flusso di risposta è suddiviso in un flusso preFlow, uno o più flussi conditional o conditional facoltativi e un flusso PostFlow.
- PreFlow: viene eseguito sempre. Viene eseguita prima di qualsiasi flusso condizionale.
- PostFlow: viene eseguito sempre. Viene eseguita dopo qualsiasi flusso condizionale.
Inoltre, puoi aggiungere un PostClientFlow all'endpoint proxy, che viene eseguito dopo che la risposta viene restituita all'app client richiedente. A questo flusso è possibile associare solo il criterio MessageLogging. PostClientFlow riduce la latenza del proxy API e rende disponibili informazioni per il logging che non vengono calcolate finché la risposta non viene restituita al client, ad esempio client.sent.start.timestamp
e client.sent.end.timestamp
.Il flusso viene utilizzato principalmente per misurare l'intervallo di tempo tra i timestamp di inizio e di fine del messaggio di risposta.
Ecco un esempio di PostClientFlow con un criterio di logging dei messaggi allegato.
... <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow> <Request/> <Response> <Step> <Name>Message-Logging-1</Name> </Step> </Response> </PostClientFlow> ...
La pipeline di elaborazione del proxy API esegue i flussi nella seguente sequenza:
Pipeline di richiesta:
- PreFlow richiesta proxy
- Flussi condizionali delle richieste proxy (facoltativi)
- PostFlow richiesta proxy
- Preflusso richiesta target
- Flussi condizionali delle richieste target (facoltativi)
- PostFlow richiesta target
Pipeline di risposta:
- Preflusso risposta target
- Flussi condizionali di risposta target (facoltativi)
- Risposta target post-flusso
- Preflusso risposta proxy
- Flussi condizionali di risposta proxy (facoltativi)
- PostFlow risposta proxy
- Risposta PostClientFlow (facoltativa)
Solo i flussi con collegamenti ai criteri devono essere configurati nelle configurazioni ProxyEndpoint o TargetEndpoint. PreFlow e PostFlow devono essere specificati solo in una configurazione ProxyEndpoint o TargetEndpoint quando è necessario applicare un criterio durante l'elaborazione PreFlow o PostFlow.
A differenza dei flussi condizionali, l'ordine degli elementi PreFlow e PostFlow non è importante: il proxy API eseguirà sempre ciascun elemento nel punto appropriato della pipeline, indipendentemente da dove appaiono nella configurazione dell'endpoint.
Flussi condizionali
Gli endpoint proxy e gli endpoint di destinazione supportano un numero illimitato di flussi condizionali (noti anche come flussi con nome).
Il proxy API verifica la condizione specificata nel flusso condizionale e, se la condizione è soddisfatta, i passaggi di elaborazione nel flusso condizionale vengono eseguiti dal proxy API. Se la condizione non è soddisfatta, i passaggi di elaborazione nel flusso condizionale vengono ignorati. I flussi condizionali vengono valutati nell'ordine definito nel proxy API e viene eseguito il primo la cui condizione è soddisfatta.
Se definisci i flussi condizionali, puoi applicare i passaggi di elaborazione in un proxy API in base a:
- URI di richiesta
- Verbo HTTP (
GET
/PUT
/POST
/DELETE
) - Valore di un parametro di query, di un'intestazione e di un parametro modulo
- Molti altri tipi di condizioni
Ad esempio, il seguente flusso condizionale specifica che viene eseguito solo quando il
percorso della richiesta della risorsa è /accesstoken
. Qualsiasi richiesta in entrata con il percorso /accesstoken
determina l'esecuzione di questo flusso, insieme a tutti i criteri associati al flusso. Se il percorso di richiesta non include il suffisso
/accesstoken
, il flusso non viene eseguito (anche se potrebbe verificarsi
un altro flusso condizionale).
<Flows> <Flow name="TokenEndpoint"> <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition> <Request> <Step> <Name>GenerateAccessToken</Name> </Step> </Request> </Flow> </Flows>
Elementi di configurazione dei flussi
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
Flow |
Una pipeline di elaborazione di richieste o risposte definita da un endpoint proxy o un endpoint di destinazione | ||
Name |
Il nome univoco del flusso. | N/A | Sì |
Condition |
Un'istruzione condizionale che valuta o più variabili per restituire vero o falso. Tutti i flussi diversi dai tipi predefiniti PreFlow e PostFlow devono definire una condizione per la loro esecuzione. | N/A | Sì |
Request |
La pipeline associata all'elaborazione della richiesta dei messaggi | N/A | No |
Response |
La pipeline associata all'elaborazione del messaggio di risposta | N/A | No |
Elaborazione del passaggio
L'ordine sequenziale dei flussi condizionali viene applicato da Apigee. I flussi condizionali vengono eseguiti dall'alto verso il basso. Viene eseguito il primo flusso condizionale la cui condizione valuta true
e ne viene eseguito un solo.
Ad esempio, nella seguente configurazione di Flow, qualsiasi richiesta in entrata che non include il suffisso del percorso /first
o /second
comporterà l'esecuzione di ThirdFlow
, applicando il criterio denominato Return404
.
<Flows> <Flow name="FirstFlow"> <Condition>proxy.pathsuffix MatchesPath "/first"</Condition> <Request> <Step><Name>FirstPolicy</Name></Step> </Request> </Flow> <Flow name="SecondFlow"> <Condition>proxy.pathsuffix MatchesPath "/second"</Condition> <Request> <Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step> </Request> </Flow> <Flow name="ThirdFlow"> <Request> <Step><Name>Return404</Name></Step> </Request> </Flow> </Flows>
Risorse
Le "risorse" (file di risorse da utilizzare nei proxy API) sono script, codice e trasformazioni XSL che possono essere associati a Flows utilizzando i criteri. Questi vengono visualizzati nella sezione Script dell'editor proxy API nell'interfaccia utente di Apigee.
Consulta Gestione delle risorse per conoscere i tipi di risorse supportati.
Le risorse possono essere archiviate in un proxy API, in un ambiente o in un'organizzazione. In ogni caso, in un criterio viene fatto riferimento a una risorsa in base al nome. Apigee risolve il nome passando dal proxy API all'ambiente, al livello organizzazione.
I criteri possono fare riferimento a una risorsa archiviata a livello di organizzazione in qualsiasi ambiente. I criteri in quell'ambiente possono fare riferimento a una risorsa archiviata a livello di ambiente. I criteri nel proxy API possono fare riferimento a una risorsa archiviata a livello di proxy API.