Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza la documentazione di Apigee Edge.
In qualità di sviluppatore che lavora con Apigee, le tue attività di sviluppo principali prevedono configurazione di proxy API che fungono da proxy per le API o i servizi di backend. Questo documento è un riferimento a tutti gli elementi di configurazione disponibili durante la creazione di 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 di Apigee API.
- Scarica il bundle di configurazione del proxy API, modificalo manualmente e carica la nuova configurazione in Apigee, come descritto in Download e caricamento di un pacchetto di configurazione di proxy API.
Struttura della directory di configurazione del proxy API
La struttura della directory di configurazione del proxy API è riportata di seguito:
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 (dalle app che effettuano la richiesta ad Apigee), flussi di richiesta e risposta e allegati dei criteri. |
TargetEndpoint | Impostazioni per la connessione HTTP in uscita (da Apigee al servizio di backend), flussi di richiesta e risposta e allegati ai criteri. |
Flussi | Pipeline di richiesta e risposta ProxyEndpoint e TargetEndpoint a cui possono essere in allegato. |
Norme | File di configurazione in formato XML conformi agli schemi dei criteri di Apigee. |
Risorse | Script, file JAR e file XSLT a cui fanno riferimento i criteri per eseguire la logica personalizzata. |
Configurazione di base
/apiproxy/weatherapi.xml
La configurazione di base di 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 ai seguenti:
A-Za-z0-9_- |
N/D | 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 dell'API proxy. | N/D | No |
ConfigurationVersion |
La versione dello schema di configurazione del proxy API a cui è conforme questo proxy API. La al momento solo il valore supportato è mainVersion 4 e minorVersion 0. Questa impostazione potrebbe essere utilizzata in futuro per consentire l'evoluzione del formato del proxy dell'API. | 4.0 | No |
Description |
Una descrizione testuale del proxy API. Se fornita, la descrizione verrà visualizzata nell'interfaccia utente di Apigee. | N/D | No |
DisplayName |
Un nome facile da ricordare che può essere diverso dall'attributo name della configurazione del proxy API. |
N/D | No |
Policies |
Un elenco di criteri nella directory /policies di questo proxy API. Potrai
di solito vedono questo elemento solo quando il proxy API è stato creato utilizzando la UI di Apigee.
Si tratta semplicemente di un'impostazione del file manifest, progettata per fornire visibilità sui contenuti
il proxy API. |
N/D | No |
ProxyEndpoints |
Un elenco di endpoint 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à sul
i contenuti del proxy API. |
N/D | No |
Resources |
Un elenco di risorse (JavaScript, Python, Java, Hadoop) nel /resources
directory di questo proxy API. In genere, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di Apigee. Si tratta semplicemente di un'impostazione del manifest, progettata per fornire visibilità ai contenuti del proxy API. |
N/D | No |
Spec |
Identifica la specifica OpenAPI associata al proxy API. Il valore
sia impostato su un URL o su un percorso nell'archivio delle specifiche. |
N/D | No |
TargetServers |
Un elenco di server di destinazione a cui viene fatto riferimento in eventuali endpoint di destinazione di questo proxy API. In genere, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando Apigee. Si tratta semplicemente di un'impostazione del file manifest, progettata per fornire visibilità sui contenuti il proxy API. | N/D | 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à sul
i contenuti del proxy API. |
N/D | No |
ProxyEndpoint
Nell'immagine seguente viene mostrato il flusso di richiesta/risposta:
/apiproxy/proxies/default.xml
La configurazione di ProxyEndpoint definisce l'interfaccia in entrata (di fronte 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:
Configurazione ProxyEndpoint elementi
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) sono definiti più endpoint proxy. I caratteri che puoi utilizzare
nel nome sono limitate a: A-Za-z0-9._\-$ % . |
N/D | Sì | |||||||||||||||
PreFlow |
Definisce i criteri nel flusso PreFlow di una richiesta o una risposta. | N/D | Sì | |||||||||||||||
Flows |
Definisce i criteri nei flussi condizionali di una richiesta o di una risposta.
|
N/D | Sì | |||||||||||||||
PostFlow |
Definisce i criteri nel flusso PostFlow di una richiesta o risposta.
|
N/D | 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 URI utilizzato da Apigee per instradare i messaggi in arrivo al proxy API corretto. Il BasePath è un frammento URI (ad esempio Utilizzare 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 base di Importante: Apigee NON supporta l'utilizzo di un carattere jolly "*" come primo
di un percorso di base. Ad esempio, questo 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 esempio di output a seconda dell'impostazione della proprietà
|
N/D | No | |||||||||||||||
FaultRules |
Definisce la risposta dell'endpoint proxy a un errore. Una regola di errore specifica
articoli:
Consulta la sezione Gestione degli errori. |
N/D | No | |||||||||||||||
DefaultFaultRule |
Gestisce eventuali errori (sistemi, trasporti, messaggi o norme) che non sono esplicitamente gestite da un'altra regola di errore. Consulta la sezione Gestione degli errori. |
N/D | No | |||||||||||||||
RouteRule |
Definisce la destinazione dei messaggi di richiesta in entrata dopo l'elaborazione da parte della pipeline di richieste ProxyEndpoint. In genere, 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 tuoi personaggi
che possono essere utilizzati nel nome sono limitati a: A-Za-z0-9._\-$ % . Ad esempio, Cat2 %_ è un nome legale. |
N/D | Sì | |||||||||||||||
Condition |
Un'istruzione condizionale facoltativa utilizzata per il routing dinamico in fase di esecuzione. Condizionale Le regole di route sono utili, ad esempio, per abilitare il routing basato sui contenuti per supportare il backend il controllo delle versioni. | N/D | No | |||||||||||||||
TargetEndpoint |
Una stringa facoltativa che identifica una configurazione TargetEndpoint denominata. Un con nome
per endpoint di destinazione si intende qualsiasi endpoint di destinazione definito nello stesso proxy API in
nella directory Assegnando un nome a un endpoint di destinazione, indichi dove devono essere inoltrati i messaggi di richiesta dopo l'elaborazione da parte della pipeline di richiesta ProxyEndpoint. Tieni presente che si tratta di un'impostazione facoltativa. Un endpoint proxy può chiamare direttamente un URL. Ad esempio, una risorsa JavaScript o Java, che agisce nel ruolo di un client HTTP, può svolgere il compito di base di un endpoint di destinazione, ovvero inoltrare le richieste a un servizio di backend. |
N/D | No | |||||||||||||||
URL |
Una stringa facoltativa che definisce un indirizzo di rete in uscita chiamato
l'endpoint proxy, bypassando qualsiasi configurazione TargetEndpoint che potrebbe essere
/targets |
N/D | No |
Come configurare RouteRules
Un endpoint di destinazione denominato si riferisce a un file di configurazione in /apiproxy/targets
per
per cui la RouteRule inoltra una richiesta dopo l'elaborazione da parte dell'endpoint proxy.
Ad esempio, la seguente regola di routing fa riferimento alla configurazione
/apiproxy/targets/myTarget.xml
:
<RouteRule name="default"> <TargetEndpoint>myTarget</TargetEndpoint> </RouteRule>
Chiamata diretta all'URL
Un endpoint proxy può anche richiamare direttamente un servizio di backend. L'invocazione diretta dell'URL aggira qualsiasi configurazione di TargetEndpoint denominata in /apiproxy/targets
. Per questo motivo, TargetEndpoint è una configurazione facoltativa del proxy API, anche se, in pratica, l'invocazione diretta dall'endpoint del proxy non è consigliata.
Ad esempio, la seguente RouteRule effettua una chiamata HTTP a
http://api.mycompany.com/v2
.
<RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Route condizionali
Le regole di routing possono essere collegate in serie per supportare il routing dinamico in fase di esecuzione. Le richieste in entrata possono essere indirizzate a configurazioni di TargetEndpoint denominate, direttamente a URL o a una combinazione di entrambi, in base alle intestazioni HTTP, ai contenuti dei messaggi, ai parametri di query o a informazioni contestuali come l'ora del giorno, le impostazioni internazionali e così via.
Le RouteRules condizionali funzionano come altre istruzioni condizionali su Apigee. Consulta: Riferimento alle condizioni e riferimento alle variabili di flusso.
Ad esempio, la seguente combinazione di RouteRule valuta innanzitutto 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 nominato
TargetEndpoint1
. In caso contrario, la richiesta in entrata viene inoltrata al
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>
Percorsi null
È possibile definire una RouteRule nulla a supporto degli scenari in cui il messaggio di richiesta non devono essere inoltrati all'endpoint di destinazione. Ciò è utile quando l'endpoint proxy esegue tutte le l'elaborazione necessaria, ad esempio utilizzando JavaScript per chiamare un servizio esterno recuperando i dati da una ricerca nell'archivio chiave/valore Apigee.
Ad esempio, quanto segue definisce una Route nulla:
<RouteRule name="GoNowhere"/>
Le route null condizionali possono essere utili. Nell'esempio seguente, una route null è configurata per essere eseguita 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 le regole di routing possono essere concatenate, quindi un percorso nullo condizionale è in genere un componente di un insieme di regole di routing progettate per supportare il routing condizionale.
Un utilizzo pratico di un percorso nullo condizionale è a supporto della memorizzazione nella cache. Utilizzando il valore della variabile impostata dal criterio Cache, è possibile configurare un proxy API per l'esecuzione null Route quando una voce viene fornita 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 funge da client per un servizio o un'API di backend: invia richieste e riceve risposte.
Un proxy API non deve necessariamente avere endpoint di destinazione. Gli endpoint proxy possono essere configurati per chiamare gli URL . Un proxy API senza endpoint di destinazione in genere contiene un endpoint proxy che chiama direttamente un servizio di backend o è configurato per chiamare un servizio utilizzando Java o JavaScript.
Configurazione endpoint di destinazione
/targets/default.xml
L'endpoint di destinazione definisce la connessione in uscita da Apigee a un altro servizio o risorsa.
Ecco un esempio di configurazione di TargetEndpoint:
<TargetEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> <SSLInfo/> <Authentication/> </HTTPTargetConnection> <FaultRules/> <DefaultFaultRule/> <ScriptTarget/> <LocalTargetConnection/> </TargetEndpoint>
Elementi di configurazione di TargetEndpoint
Un endpoint di destinazione può chiamare una destinazione in uno dei seguenti modi:
- HTTPTargetConnection per le chiamate HTTP o HTTPS
- LocalTargetConnection per l'incatenamento di proxy locali
Configurane solo una in un endpoint di destinazione.
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
TargetEndpoint |
|||
name |
Il nome dell'endpoint di destinazione, che deve essere univoco all'interno del proxy API
configurazione. Il nome dell'endpoint di destinazione viene utilizzato in RouteRule di ProxyEndpoint per indirizzare le richieste di elaborazione in uscita. I caratteri che puoi utilizzare nel nome
sono limitati ai seguenti: A-Za-z0-9._\-$ % . |
N/D | Sì |
PreFlow |
Definisce i criteri nel flusso PreFlow di una richiesta o una risposta. | N/D | Sì |
Flows |
Definisce i criteri nei flussi condizionali di una richiesta o di una risposta.
|
N/D | Sì |
PostFlow |
Definisce i criteri nel flusso PostFlow di una richiesta o risposta.
|
N/D | Sì |
HTTPTargetConnection |
Con i suoi 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 di richiesta dei messaggi. | N/D | No |
LoadBalancer |
Definisce una o più configurazioni TargetServer denominate. Server di destinazione denominato possono essere utilizzate per il bilanciamento del carico che definisce due o più configurazioni di endpoint e connessioni a Internet. Puoi anche utilizzare i server di destinazione per disaccoppiare le configurazioni proxy API gli URL degli endpoint dei servizio di backend. |
N/D | No |
Properties |
Un insieme di impostazioni di configurazione HTTP facoltative può essere definito come proprietà di un
<TargetEndpoint> . |
N/D | No |
SSLInfo |
Se vuoi, 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 dell'endpoint di destinazione TLS/SSL. | N/D | No |
LocalTargetConnection |
Con i suoi elementi figlio, specifica una risorsa che deve essere raggiunta localmente, bypassando la rete
come il bilanciamento del carico e i processori di messaggi.
Per specificare la risorsa di destinazione, includi l'elemento secondario APIProxy (con il ProxyEndpoint) o l'elemento secondario Percorso. Per ulteriori informazioni, consulta Concatenare i proxy API. 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 devono trovarsi nella stessa organizzazione e nello stesso ambiente del proxy che invia le richieste. Si tratta di un un'alternativa all'uso dell'elemento Path. | N/D | No |
ProxyEndpoint |
Utilizzato con APIProxy per specificare il nome dell'endpoint proxy del proxy di destinazione. | N/D | No |
Path |
Specifica il percorso 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 del proxy che invia le richieste. Questo è un'alternativa all'uso di APIProxy. | N/D | No |
FaultRules |
Definisce la reazione dell'endpoint di destinazione a un errore. Una regola di errore specifica due
elementi:
Consulta la sezione Gestione degli errori. |
N/D | No |
DefaultFaultRule |
Gestisce eventuali errori (sistemi, trasporti, messaggi o norme) che non sono esplicitamente gestito da un'altra regola Fault. Consulta la sezione Gestione degli errori. |
N/D | No |
Utilizzo dell'elemento <Authentication>
L'utilizzo dell'elemento <Authentication>
in <TargetEndpoint>
è identico all'utilizzo
dell'elemento <Authentication>
nel
ServiceCallout. Sia in <TargetEndpoint>
che in ServiceCallout, <Authentication>
è un elemento secondario
di <HttpTargetConnection>
. Per maggiori dettagli, vedi Elemento di autenticazione
nel riferimento sulle norme relative a ServiceCallout.
Riferimento errore relativo all'elemento <Authentication>
Se utilizzi l'elemento <Authentication>
, puoi trovare i possibili messaggi di errore e la risoluzione dei problemi
suggerimenti per gli errori di deployment e di runtime nella sezione Errori
della documentazione relativa ai criteri ServiceCallout.
Esempi di elementi <Authentication>
L'esempio seguente mostra come chiamare un servizio di destinazione di cui è stato eseguito il deployment su Cloud Run 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 l'autenticazione
la chiamata. L'elemento HeaderName
aggiunge il token di accesso generato a un'intestazione denominata X-Serverless-Authorization
inviata al sistema di destinazione. L'intestazione Authorization
, se presente, viene lasciata invariata e inviata anche 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 TargetService che punta all'account Google Servizio 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
valida, l'URL del target (esclusi i parametri di query) viene utilizzato come segmento di pubblico.
Supponiamo che
il percorso della richiesta è /foobar
e l'URL del server di destinazione è https://xyz.com
,
il pubblico di GoogleIDToken verrà automaticamente impostato 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 di TargetEndpoint TLS/SSL
Gli endpoint di destinazione spesso hanno bisogno di gestire le connessioni HTTPS con backend eterogenei dell'infrastruttura. Per questo motivo, sono supportate diverse impostazioni di configurazione TLS/SSL.
TLS/SSL Elementi di configurazione TargetEndpoint
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
SSLInfo |
Il blocco |
||
Enabled |
Se impostato su Il valore predefinito |
true se <URL> specifica HTTPS |
No |
Enforce |
Applica SSL rigoroso tra Apigee e il backend di destinazione. Se il criterio viene impostato su Se non è impostato o è impostato su |
false |
No |
TrustStore |
Un archivio chiavi contenente certificati dei server radice attendibili. Apigee tratterà il telecomando peer come attendibile se la catena di certificati che invia termina in un certificato è contenuto in questo archivio chiavi. |
N/D | No |
ClientAuthEnabled |
Se impostato su L'attivazione del TLS bidirezionale in genere richiede la configurazione sia di un truststore sia di un keystore su Apigee. |
false |
No |
KeyStore |
Un keystore contenente le chiavi private utilizzate per l'autenticazione dei client in uscita | N/D | Sì (se ClientAuthEnabled è true) |
KeyAlias |
L'alias della chiave privata utilizzata per l'autenticazione del client in uscita | N/D | 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 DN (Distinguished Name) soggetto che non corrisponde al nome host, non è possibile ignorare l'errore e la connessione non va a buon fine. Nota: se |
false |
No |
Ciphers |
Crittografia supportate per TLS/SSL in uscita. Se non viene specificata alcuna crittografia, verranno utilizzate tutte le crittografie per la 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/D | No |
Protocols |
Protocolli supportati per TLS/SSL in uscita. Se non vengono specificati protocolli, i protocolli disponibili per la JVM. Per limitare i protocolli, specificali in modo esplicito. Ad esempio, per consentire solo TLS 1.2 o TLS 1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols> |
N/D | No |
CommonName |
Apigee controlla questo valore qui rispetto al nome comune (CN) o alle SAN (Nomi alternativi del soggetto) sul certificato peer remoto. |
N/D | No |
Endpoint di destinazione di esempio 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 dinamicamente i valori TLS/SSL
Puoi anche impostare dinamicamente i dettagli TLS/SSL per supportare requisiti di runtime flessibili. Ad esempio, se il proxy si connette a due target potenzialmente diversi (un target di test e un produzione target), puoi fare in modo che il proxy API rilevi in modo programmatico di quale ambiente e impostare dinamicamente i riferimenti all'archivio chiavi e all'archivio chiavi appropriati. La SSLInfo dinamiche per TargetEndpoint utilizzando il riferimento alle variabili L'articolo della community Apigee spiega questo scenario in modo più dettagliato e fornisce un'API di cui è possibile eseguire il deployment di proxy di esempio.
Nel seguente esempio di come verrà impostato il tag <SSLInfo>
in una
Configurazione di TargetEndpoint, i valori possono essere forniti in fase di runtime, ad esempio, da un
Callout, JavaScript o criterioAssignMessage. Utilizza le variabili messaggio che contengono i valori da 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 riferimenti per impostare dinamicamente i valori TLS/SSL
Quando configuri un endpoint di destinazione che utilizza HTTPS, devi considerare il caso in cui il certificato TLS/SSL scada o una modifica alla configurazione di sistema richieda l'aggiornamento del certificato.
Per ulteriori informazioni, consulta la sezione Gestire i certificati scaduti.
Tuttavia, puoi facoltativamente configurare l'endpoint di destinazione in modo che utilizzi un riferimento all'endpoint un archivio chiavi o un archivio attendibilità. Il vantaggio di usare un riferimento è che consente di aggiornare riferimento per puntare a un altro archivio chiavi o truststore per aggiornare il certificato TLS/SSL senza dover riavviare i processori di messaggi.
Ad esempio, di seguito è riportato un endpoint di destinazione che utilizza un riferimento al keystore:
<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 tuo 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 dell'API Apigee.
Il riferimento specifica il nome del keystore e il relativo tipo.
Utilizza la seguente chiamata API GET per visualizzare il riferimento:
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -H "Authorization: Bearer $TOKEN"
Dove $TOKEN
è impostato sul tuo 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 dell'API Apigee.
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -H "Authorization: Bearer $TOKEN"
dove $TOKEN
è impostato sul tuo 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, vedi
Con curl. Per una descrizione delle variabili di ambiente utilizzate,
consulta Impostare le 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 lo stesso nome, utilizza 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 tuo 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 dell'API Apigee.
TargetEndpoint con bilanciamento del carico di destinazione
Gli endpoint target supportano il bilanciamento del carico su più server target 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 in modo specifico le integrazioni Apigee. Se hai configurato un IntegrationEndpoint, Apigee invia l'oggetto request sulla piattaforma di integrazione di Apigee per l'esecuzione. Per eseguire l'integrazione, oltre a configurare il IntegrationEndpoint, devi anche aggiungere il criterio SetIntegrationRequest nel tuo flusso proxy.
Puoi configurare l'integrazione in modo che venga eseguita in modo sincrono o asincrono impostando l'elemento <AsyncExecution>
nella configurazione di IntegrationEndpoint. Per ulteriori informazioni, consulta la sezione 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 IntegrationEndpoint alla configurazione di ProxyEndpoint. Di seguito è riportato un esempio di configurazione di ProxyEndpoint:
<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 attività seguenti:
- In 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. - Utilizza
my-int-endpoint
come endpoint di destinazione, come specificato inRouteRule
. - Legge l'oggetto della richiesta di integrazione creato da
my-set-integration-request-policy
. - Invia la richiesta alla piattaforma di integrazione di Apigee utilizzando l'oggetto 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 in
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 l'endpoint XML di integrazione dall'interfaccia utente, 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 IntegrationEndpoint
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
IntegrationEndpoint |
|||
name |
Il nome dell'IntegrationEndpoint. I caratteri
che puoi utilizzare nel nome sono limitati a:
A-Za-z0-9._\-$ % |
N/D | Sì |
AsyncExecution |
Un valore booleano che specifica se l'integrazione deve essere eseguita in modalità sincrona o asincrona. Per ulteriori informazioni, consulta Esecuzione sincrona e asincrona. | falso | 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 imposta su false
, l'integrazione viene eseguita in modo sincrono.
Nell'esempio seguente, AsyncExecution
viene impostato 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
collegato ai flussi nel proxy API.
Elementi di configurazione dei criteri
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
Policy |
|||
name |
Il nome interno del criterio. I caratteri che puoi utilizzare nel nome sono limitati
a: Se vuoi, utilizza l'elemento |
N/D | Sì |
enabled |
Imposta il valore su Imposta su |
true |
No |
continueOnError |
Imposta il valore su Imposta su |
false |
No |
async |
Se il criterio viene impostato su Per utilizzare il comportamento asincrono nei proxy API, consulta la pagina sul modello a oggetti JavaScript. |
false |
No |
Allegato criterio
L'immagine seguente mostra la sequenza di esecuzione dei flussi proxy API:
Come mostrato sopra:
I criteri vengono collegati come passaggi di elaborazione ai flussi. Il nome del criterio è utilizzato per riferimento al criterio da applicare come fase di elaborazione. Il formato di un allegato delle norme è 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>
Configurazione del collegamento dei criteri elementi
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
Step |
|||
Name |
Il nome del criterio da eseguire in base a questa definizione del passaggio. | N/D | Sì |
Condition |
Un'istruzione condizionale che determina se il criterio viene applicato o meno. Se ha una condizione associata, il criterio viene eseguito solo se la condizione condizionale restituisce true. | N/D | No |
Flusso
ProxyEndpoint e TargetEndpoint definiscono una pipeline per l'elaborazione dei messaggi di richiesta e risposta. Una pipeline di elaborazione è composta da un flusso di richiesta e un flusso di risposta. Ogni flusso di richiesta e flusso di risposta è suddiviso in un PreFlow, uno o più flussi facoltativi condizionali o nominati e un PostFlow.
- PreFlow: viene eseguito sempre. Viene eseguito prima di qualsiasi flusso condizionale.
- PostFlow: viene eseguito sempre. Viene eseguito dopo eventuali flussi condizionali.
Inoltre, puoi aggiungere un PostClientFlow all'endpoint proxy, che viene eseguito dopo
viene restituita all'app client richiedente. È possibile collegare solo il criterio MessageLogging
a questo flusso. PostClientFlow riduce la latenza del proxy API e rende disponibili per il logging informazioni che non vengono calcolate fino a quando 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 collegato.
... <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 della richiesta proxy
- (Facoltativo) Flussi condizionali delle richieste proxy
- PostFlow richiesta proxy
- Pre-flusso richiesta target
- Flussi condizionali delle richieste target (facoltativo)
- PostFlow richiesta target
Pipeline di risposta:
- PreFlow risposta target
- Flussi condizionali di risposta target (facoltativi)
- PostFlow di risposta target
- Pre-flusso risposta proxy
- Flussi condizionali di risposta proxy (facoltativi)
- PostFlow risposta proxy
- PostClientFlow Response (facoltativo)
Solo i flussi con allegati di criteri devono essere configurati nelle configurazioni ProxyEndpoint o TargetEndpoint. PreFlow e PostFlow devono essere specificati solo in un ProxyEndpoint o Configurazione dell'endpoint di destinazione quando è necessario applicare un criterio durante PreFlow o PostFlow e l'elaborazione dei dati.
A differenza dei flussi condizionali, l'ordine degli elementi PreFlow e PostFlow non è importante: il proxy API verrà sempre eseguito nel punto appropriato della pipeline, indipendentemente da dove vengono visualizzate nella configurazione degli endpoint.
Flussi condizionali
Gli endpoint proxy e di destinazione supportano un numero illimitato di flussi condizionali (anche noti 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 non è soddisfatta, le fasi di elaborazione nel flusso condizionale vengono bypassate. Condizionale vengono valutati nell'ordine definito nel proxy API e il primo la cui condizione è di cui è responsabile l'esecuzione.
Definendo 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 di modulo
- Molti altri tipi di condizioni
Ad esempio, il seguente flusso condizionale specifica che viene eseguito solo quando
il percorso della risorsa di richiesta è /accesstoken
. Qualsiasi richiesta in entrata con
il percorso /accesstoken
causa l'esecuzione di questo flusso insieme a eventuali criteri
collegate al flusso. Se il percorso della richiesta non include il suffisso
/accesstoken
, il flusso non viene eseguito (sebbene un altro flusso condizionale
potrebbe)
<Flows> <Flow name="TokenEndpoint"> <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition> <Request> <Step> <Name>GenerateAccessToken</Name> </Step> </Request> </Flow> </Flows>
Elementi di configurazione del flusso
Nome | Descrizione | Predefinito | Obbligatorio? |
---|---|---|---|
Flow |
Una pipeline di elaborazione di richieste o risposte definita da un endpoint proxy o da un endpoint target | ||
Name |
Il nome univoco del flusso. | N/D | Sì |
Condition |
Un'istruzione condizionale che valuta una o più variabili in modo che restituiscano true o false. Tutti i flussi diversi dai tipi PreFlow e PostFlow predefiniti devono definire una condizione per la loro esecuzione. Tuttavia, se includi un singolo flusso senza una condizione alla fine di una sequenza di flussi, questo agirà come l'istruzione "Else" alla fine della sequenza di flussi. | N/D | Sì |
Request |
La pipeline associata all'elaborazione dei messaggi di richiesta | N/D | No |
Response |
La pipeline associata all'elaborazione del messaggio di risposta | N/D | No |
Elaborazione dei passaggi
L'ordine sequenziale dei flussi condizionali viene applicato da Apigee. Flussi condizionali
vengono eseguiti dall'alto verso il basso. Il primo flusso condizionale la cui condizione valuta
Viene eseguito true
e viene eseguito un solo flusso condizionale.
Ad esempio, nella seguente configurazione del flusso, qualsiasi richiesta in entrata che non includa
il suffisso del percorso /first
o /second
causerà l'errore ThirdFlow
da eseguire, 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 associate ai flussi utilizzando i criteri. Questi vengono visualizzati nella sezione Script dell'editor proxy API nell'interfaccia utente di Apigee.
Consulta Gestione delle risorse per le risorse tipi di risorse.
Le risorse possono essere archiviate in un proxy API, in un ambiente o in un'organizzazione. In ogni caso, in un criterio fa riferimento al nome di una risorsa. Apigee risolve il nome spostandosi dall'API tra proxy, ambiente e livello organizzazione.
Una risorsa archiviata a livello di organizzazione può essere richiamata dai criteri in qualsiasi ambiente. I criteri di quell'ambiente fanno riferimento a una risorsa archiviata a livello di ambiente. È possibile fare riferimento a una risorsa archiviata a livello di proxy API solo dai criteri in quel proxy API.