Riferimento per la configurazione dei proxy API

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza 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 di tutti gli elementi di configurazione a tua disposizione durante la creazione di proxy API.

Se stai imparando a creare proxy API, ti consigliamo di iniziare con l'argomento Creazione di un'API semplice proxy.

Modifica la configurazione del proxy API utilizzando uno dei seguenti metodi:

Struttura della directory di configurazione del proxy API

Di seguito è riportata la struttura della directory di configurazione del proxy API:

Mostra la struttura della directory in cui apiproxy è la directory radice. Direttamente nel apiproxy sono le directory dei criteri, dei proxy, delle risorse e delle destinazioni, nonché meteoapi.xml.

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), richiesta flussi di dati e risposte e allegati ai 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 KML a cui fanno riferimento i criteri per eseguire la 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 devono essere univoci all'interno dell'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 personaggi che puoi utilizzare per il nome sono limitati a quanto segue: 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 può essere verrà utilizzata in futuro per consentire l'evoluzione del formato proxy API. 4.0 No
Description Una descrizione testuale del proxy API. Se fornita, la descrizione verrà visualizzata in la UI di Apigee. N/D No
DisplayName Un nome semplice che potrebbe essere diverso dall'attributo name dell' 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. Tu di solito vedrà questo elemento solo quando il proxy API è stato creato con Apigee nell'interfaccia utente. 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 la UI di Apigee. Si tratta semplicemente di un'impostazione manifest, progettata per forniscono visibilità sui 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. Potrai di solito vedono questo elemento solo quando il proxy API è stato creato con 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. Tu di solito vedrà questo elemento solo quando il proxy API è stato creato utilizzando la UI 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:

Mostra un client che chiama una richiesta HTTP completamente gestito di Google Cloud. La richiesta passa attraverso l&#39;endpoint proxy e poi l&#39;endpoint di destinazione prima di essere elaborati dal servizio HTTP. La risposta passa attraverso l&#39;endpoint di destinazione e quindi l&#39;endpoint proxy prima di essere restituito al client.

/apiproxy/proxies/default.xml

La configurazione ProxyEndpoint definisce l'interfaccia in entrata (rivolta al client) per un'API proxy. 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) vengono 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 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 dell'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 /weather) aggiunto alla URL di base di un proxy API (ad esempio, http://apifactory-test.apigee.net). Il BasePath deve essere univoco all'interno di un ambiente. L'univocità viene convalidata quando un proxy API viene generato o importato.

Utilizzare un carattere jolly nei percorsi di base

Puoi utilizzare uno o più "*" caratteri jolly nei percorsi di base dei proxy API. Ad esempio, una base di /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza che tu debba creare nuovi proxy API per supportare nuovi team. Tieni presente che /**/ non è supportato.

Importante: Apigee NON supporta l'utilizzo di un carattere jolly "*" come primo di un percorso di base. Ad esempio, NON è supportato: /*/search. Il percorso di base inizia con "*" può causare errori imprevisti a causa del modo identifica i percorsi validi.

 / Sì
Properties Un insieme di impostazioni di configurazione HTTP facoltative può essere definito come proprietà di un <ProxyEndpoint>.

Utilizza la proprietà request.queryparams.ignore.content.type.charset per indica al proxy di ignorare il parametro charset dell'intestazione Content-Type durante l'elaborazione dell'URL della richiesta. Per esempio: 

<Property name= \
"request.queryparams.ignore.content.type.charset">true</>

La tabella seguente mostra un output di esempio in base all'impostazione di charset e presenza del parametro charset dell'intestazione Content-Type.

Impostazione proprietà Valore intestazione Output di esempio
charset=false charset parametro non impostato john.doe+test@gmail.com
charset=false charset=utf-8 mario.rossi test@gmail.com
charset=true e nessun parametro charset nell'intestazione. charset parametro non impostato john.doe+test@gmail.com
charset=true charset=utf-8 parametro impostato john.doe+test@gmail.com
N/D No
FaultRules
Definisce la risposta dell'endpoint proxy a un errore. Una regola di errore specifica articoli:
  • Una condizione che specifica l'errore da gestire in base all'impostazione predefinita categoria, sottocategoria o nome del guasto.
  • Uno o più criteri che definiscono il comportamento della regola di errore per Condizione corrispondente

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 del Pipeline di richiesta ProxyEndpoint. Di solito, la RouteRule punta a un endpoint di destinazione denominato, un IntegrationEndpoint o 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._\-$ %. Per 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 /targets).

Denominando 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 questa opzione è facoltativa dell'ambientazione.

Un endpoint proxy può chiamare direttamente un URL. Ad esempio, una risorsa JavaScript o Java, di un client HTTP, può svolgere il compito base di un l'endpoint di destinazione, ovvero l'inoltro delle 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 RouteRule si riferisce 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. La chiamata diretta all'URL ignora qualsiasi denominata configurazione TargetEndpoint in /apiproxy/targets). Per questo motivo, TargetEndpoint è una configurazione facoltativa del proxy API, anche se, in pratica, una chiamata diretta dall'endpoint proxy non è consigliato.

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 route possono essere concatenate per supportare il routing dinamico in fase di runtime. Le richieste in entrata possono essere indirizzato a configurazioni TargetEndpoint denominate, direttamente agli URL o a una combinazione dei due, in base a intestazioni HTTP, contenuto dei messaggi, parametri di ricerca o informazioni contestuali, come l'ora delle giorno, lingua, ecc.

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 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 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>

Route 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 null:

<RouteRule name="GoNowhere"/>

Le route null condizionali possono essere utili. Nell'esempio seguente, una route nulla è configurata su viene 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, le regole RouteRules possono essere concatenate, quindi una Route nulla condizionale di solito è una componente di un insieme di RouteRules progettate per supportare il routing condizionale.

Un uso pratico di una route nulla condizionale potrebbe supportare la 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

Mostra un client che chiama una richiesta HTTP completamente gestito di Google Cloud. La richiesta passa attraverso l&#39;endpoint proxy e poi l&#39;endpoint di destinazione prima di essere elaborati dal servizio HTTP. La risposta passa attraverso l&#39;endpoint di destinazione e quindi l&#39;endpoint proxy prima di essere restituito al client.

Un endpoint di destinazione è l'equivalente in uscita di un endpoint proxy. Un endpoint di destinazione funziona come a un servizio di backend o a un'API: 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 strato Add. 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 endpoint di destinazione

/targets/default.xml

L'endpoint di destinazione definisce la connessione in uscita da Apigee a un altro servizio risorsa.

Ecco una configurazione di TargetEndpoint di esempio:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Configurazione endpoint di destinazione elementi

Un endpoint di destinazione può chiamare una destinazione in uno dei seguenti modi:

  • HTTPTargetConnection per chiamate HTTP o HTTPS
  • LocalTargetConnection per il chaining proxy-proxy locale

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 nella RouteRule ProxyEndpoint per richieste dirette di elaborazione in uscita. 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 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 <Authentication> per effettuare chiamate autenticate ai servizi Google o ai servizi personalizzati in esecuzione. su determinati prodotti Google Cloud, come Cloud Functions e Cloud Run. L'utilizzo dell'elemento <Authentication> richiede i passaggi di configurazione e deployment descritti in Utilizzo dell'autenticazione Google. Con configurazione corretta, il criterio crea per te un token di autenticazione e lo aggiunge alla richiesta di servizio. Vedi anche Utilizzo dell'elemento <Authentication>.
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 altre connessioni.

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 Facoltativamente, definisci le impostazioni TLS/SSL su un endpoint di destinazione per controllare TLS/SSL connessione 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 Chaining API Proxy insieme.

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 target 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 articoli:
  • Una condizione che specifica l'errore da gestire in base all'impostazione predefinita categoria, sottocategoria o nome del guasto.
  • Uno o più criteri che definiscono il comportamento della regola di errore per Condizione corrispondente

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 cui è stato eseguito il deployment in Cloud Run come destinazione utilizzando l'elemento Authentication per generare un token OpenID Connect necessario per l'autenticazione 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 connessione generato a un'intestazione denominata X-Serverless-Authorization inviato al sistema di destinazione. L'intestazione Authorization, se presente, non viene modificato e viene inviato 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 su genera 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 dell'endpoint di destinazione 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 <SSLInfo> può essere utilizzato per TLS/SSL unidirezionale o bidirezionale.
Enabled

Se impostato su true, <Enabled> specifica che deve essere utilizzato il blocco <SSLInfo>. Se impostato su false, il blocco <SSLInfo> viene ignorato.

Il valore predefinito <Enabled> è true se <URL> specifica il protocollo HTTPS. e false se <URL> specifica HTTP.

 true se <URL> specifica HTTPS No
Enforce

Applica il protocollo SSL rigoroso tra Apigee e il backend di destinazione.

Se il criterio viene impostato su true, le connessioni non riusciranno per le destinazioni con certificati non validi, certificati scaduti certificati autofirmati, certificati con nome host non corrispondente e certificati con una radice non attendibile. R viene restituito il codice di errore 4xx o 5xx.

Se il criterio non viene configurato o se viene impostato su false, il risultato delle connessioni ai backend con cui scegliere come target certificati problematici dipendono dall'impostazione di <IgnoreValidationErrors> (vedi di seguito). In determinate condizioni, può verificarsi una risposta di operazione riuscita (2xx) se <IgnoreValidationErrors> è impostato su true.

 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 true, attiva il protocollo TLS bidirezionale (noto anche come TLS reciproca o mTLS) tra Apigee e il peer remoto, il client API o il backend di destinazione.

L'abilitazione del protocollo TLS a due vie in genere richiede la configurazione sia di un archivio attendibilità di archiviazione delle chiavi su Apigee.

 false No
KeyStore Un archivio chiavi contenente chiavi private utilizzate per l'autenticazione del client in uscita N/D Sì (se ClientAuthEnabled è impostato su true)
KeyAlias L'alias della chiave della chiave privata utilizzata per l'autenticazione del client in uscita N/D Sì (se ClientAuthEnabled è impostato su 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) soggetto che non corrisponde al nome host; non c'è modo di ignorare l'errore e la connessione non riesce.

Nota: se <Enforce> è impostato su true, il valore di <IgnoreValidationErrors> viene ignorato.

 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 v1.2 o TLS v1.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

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 variabili di flusso per impostare dinamicamente i valori TLS/SSL

Puoi anche impostare dinamicamente i dettagli TLS/SSL per supportare i 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 AssignMessage. Utilizza qualsiasi variabile di messaggio 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 riferimenti per impostare dinamicamente i valori TLS/SSL

Quando configuri un endpoint di destinazione che utilizza HTTPS, devi considerare il caso quando Il certificato TLS/SSL scade o una modifica alla configurazione di sistema richiede l'aggiornamento del certificato.

Per ulteriori informazioni, vedi Gestione dei 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, quello mostrato di seguito è 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 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.

Il riferimento specifica il nome e il tipo dell'archivio chiavi.

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, vedi Con curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le 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 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, vedi Con curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le 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 carichi algoritmi di bilanciamento.

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 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 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 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 di esempio ProxyEndpoint, Apigee esegue le attività seguenti:

  1. Nel PreFlow, esegue il criterio denominato my-set-integration-request-policy, che imposta l'oggetto richiesta di integrazione e le variabili di flusso di integrazione.
  2. Utilizza my-int-endpoint come endpoint di destinazione, come specificato in RouteRule.
  3. Legge l'oggetto della richiesta di integrazione creato da my-set-integration-request-policy.
  4. Invia la richiesta alla piattaforma di integrazione di Apigee utilizzando l'oggetto di richiesta e le variabili di flusso impostate dal criterio SetIntegrationRequest.
  5. 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 creare 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 IntegrationEndpoint

Nome Descrizione Predefinito Obbligatorio?
IntegrationEndpoint
name Il nome dell'IntegrationEndpoint. I personaggi che puoi utilizzare nel nome sono limitate 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 la sezione 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 le la differenza tra le modalità di esecuzione sincrona e asincrona, consulta &lt;AsyncExecution&gt;.

Utilizza l'elemento <AsyncExecution> all'interno di </IntegrationEndpoint> per e specificare l'esecuzione sincrona o asincrona. Se imposti Da <AsyncExecution> a true, l'integrazione viene eseguita in modo asincrono. E se impostato 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 utilizzabili nel nome sono soggetti a limitazioni a: A-Za-z0-9._\-$ %. Tuttavia, la UI di Apigee applica come la rimozione automatica di caratteri non alfanumerici.

Se vuoi, puoi utilizzare l'elemento <DisplayName> per etichettare il nell'editor proxy della UI di Apigee con un nome diverso in linguaggio naturale.

 N/D Sì
enabled

Imposta il valore su true per applicare il criterio.

Imposta false per disattivare il criterio. Il criterio non verrà applicata anche se rimane collegata a un flusso.

 true No
continueOnError

Imposta il valore su false per restituire un errore quando un criterio non funziona. Questo è comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce.

 false No
async

Se il criterio viene impostato su true, l'esecuzione del criterio viene scaricata in un'altra il thread principale, lasciando libero il thread principale per gestire le richieste aggiuntive. Quando la modalità l'elaborazione è completa, torna il thread principale e termina la gestione del messaggio flusso di lavoro. In alcuni casi, l'impostazione della sincronizzazione su true migliora il proxy API delle prestazioni. Tuttavia, un uso eccessivo di asinc può compromettere le prestazioni con un numero eccessivo di thread passaggio.

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:

mostra un client che chiama un servizio HTTP. La richiesta rileva l&#39;endpoint proxy e l&#39;endpoint di destinazione, ognuno dei quali contiene passaggi che attivano i criteri. Dopo il Il servizio HTTP restituisce la risposta, che viene elaborata dall&#39;endpoint di destinazione e quindi dal ProxyEndpoing prima di essere restituito al client. Come per la richiesta, la risposta viene elaborata in base ai criteri in pochi passaggi.

Come mostrato sopra:

I criteri sono collegati come passaggi di elaborazione ai flussi. Il nome del criterio è utilizzato per riferimento al criterio da applicare come fase di elaborazione. Il formato dell'allegato di un criterio è le seguenti:

<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 questa definizione di 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

Flussi

ProxyEndpoint e TargetEndpoint definiscono una pipeline per i messaggi di richiesta e risposta e l'elaborazione dei dati. Una pipeline di elaborazione è composta da un flusso di richiesta e un flusso di risposta. Ogni richiesta di flusso e di risposta è suddiviso in PreFlow, uno o più condizionali facoltativi named e un PostFlow.

  • PreFlow: viene sempre eseguito. Da eseguire prima di qualsiasi flusso condizionale.
  • PostFlow: viene sempre eseguito. 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 le informazioni che viene calcolato solo dopo che la risposta viene restituita al client, come 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 della 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:

  1. Pre-flusso richiesta proxy
  2. Flussi condizionali delle richieste proxy (facoltativi)
  3. PostFlow richiesta proxy
  4. Pre-flusso richiesta target
  5. Flussi condizionali delle richieste target (facoltativo)
  6. PostFlow richiesta target

Pipeline di risposta:

  1. PreFlow risposta target
  2. Flussi condizionali di risposta target (facoltativi)
  3. Risposta target - PostFlow
  4. Pre-flusso risposta proxy
  5. Flussi condizionali di risposta proxy (facoltativi)
  6. PostFlow risposta proxy
  7. Risposta PostClientFlow (facoltativa)

Solo i flussi con collegamenti di criteri devono essere configurati in ProxyEndpoint o Configurazioni di endpoint di destinazione. 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'ordinamento 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 se viene soddisfatto, le fasi di elaborazione nel flusso condizionale vengono eseguite 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 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 delle richieste o delle risposte definita da un endpoint proxy oppure endpoint di destinazione
Name Il nome univoco del flusso. N/D Sì
Condition Un'istruzione condizionale che valuta su o più variabili da assegnare come valore true o false. Tutti i flussi diversi dai tipi PreFlow e PostFlow predefiniti devono definire un valore per la loro esecuzione. N/D Sì
Request Pipeline associata all'elaborazione dei messaggi di richiesta N/D No
Response Pipeline associata all'elaborazione dei messaggi 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

"Risorse" (file di risorse da utilizzare nei proxy API) sono script, codice e trasformazioni XSL che può essere collegato ai flussi utilizzando i criteri. che vengono visualizzati nella sezione Script dell'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.

I criteri in qualsiasi ambiente possono fare riferimento a una risorsa archiviata a livello di organizzazione. I criteri di quell'ambiente fanno riferimento a una risorsa archiviata a livello di ambiente. R a livello di proxy API possono fare riferimento solo ai criteri in quel proxy API.