Riferimento per la configurazione dei proxy API

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

In qualità di sviluppatore che lavora con Apigee Edge, 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 Crea un'API semplice proxy.

I modi più comuni per modificare le configurazioni proxy sono:

• Utilizzando all'editor XML della UI Edge
• Scarica la configurazione e modificala localmente, come descritto in Locale sviluppo di configurazioni proxy.

Sviluppo locale di configurazioni proxy

Puoi scaricare le configurazioni proxy in modo da poterle modificare su un computer locale. Quando al termine, poi caricherai i risultati su Edge. Questo approccio ti consente di integrare per il controllo del codice sorgente, il controllo delle versioni e altri flussi di lavoro condivisi. Inoltre, se lavori a livello locale sulla configurazione del proxy, puoi usare il tuo editor XML i nostri strumenti.

Questa sezione descrive come utilizzare l'interfaccia utente per scaricare una configurazione proxy esistente, modificarla, e poi caricarlo nuovamente su Edge per il deployment. Puoi anche utilizzare apigeetool per scaricare ed eseguire il deployment di una nuova configurazione proxy (utilizzando fetchproxy e deployproxy, rispettivamente.

Per modificare una configurazione proxy in locale utilizzando l'UI:

1. Scarica la configurazione attuale del proxy nella UI Edge. (nei proxy API vista, seleziona Progetto > Scarica revisione.)
2. Sul computer locale, crea una nuova directory ed espandi il file ZIP scaricato in li annotino.

   Per espandere il file ZIP, puoi utilizzare un'utilità come unzip, come la seguente un esempio mostra:

   mkdir myappdir
   unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

   I contenuti espansi del file ZIP devono essere simili alla struttura descritta in Struttura del proxy API.

3. Modifica i file di origine in base alle tue esigenze. Per una descrizione dei file di origine in un proxy per la configurazione, consulta I file di configurazione struttura di directory di un proxy API.

   Ad esempio, per abilitare monitoraggio dello stato di salute in del proxy API, modifica il file di configurazione di Directory /apiproxy/targets/. Il file predefinito in questa directory è default.xml, anche se potrebbero esserci file con nomi diversi se usi target condizionali.

   In questo caso, se il file di configurazione TargetEndpoint e la relativa directory non esistono, crearle.

4. Dopo aver completato la modifica dei file di configurazione del proxy, assicurati di salvare le modifiche.
5. Passa alla nuova directory che hai creato quando hai espanso i file ZIP (la directory principale file di configurazione espansi).

   Ad esempio, se hai espanso i file nella directory /myappdir, modifica in quella directory, come illustrato nell'esempio seguente:

   cd myappdir

   Devi passare a questa directory prima di archiviare nuovamente i file di configurazione del proxy perché non vuoi che la directory /myappdir venga inclusa nel file ZIP. La directory di primo livello nel file ZIP deve essere /apiproxy.

6. Archivia nuovamente i file di configurazione del proxy, inclusi i file nuovi o modificati. Puoi utilizzare uno dei seguenti un'utilità comune come zip, come illustrato nell'esempio seguente:

   zip my-new-proxy.zip -r .

   La directory di primo livello nel file ZIP deve essere /apiproxy.

   Non sono previsti requisiti speciali per il nome del file ZIP. Ad esempio, non è necessario incrementare il numero di revisione o specificare la data nel nome del file, ma questa operazione può utile per il debug o il controllo del codice sorgente.

   Edge incrementa il numero di revisione della nuova configurazione proxy quando esegui il caricamento li annotino.

7. Carica la nuova configurazione del proxy utilizzando la UI Edge. (Nei proxy API vista, seleziona Progetto > Carica una nuova revisione.)

   Se visualizzi un messaggio di errore come Bundle is invalid. Empty bundle., assicurati la directory di primo livello del tuo file ZIP è /apiproxy. In caso contrario, archivia nuovamente di configurazione proxy dalla directory principale della directory espansa.

   Dopo aver caricato la nuova configurazione proxy, Edge incrementa il numero di revisione e lo vedrai nella visualizzazione Riepilogo delle revisioni.

   Edge non esegue automaticamente il deployment della nuova revisione dopo averla caricata con la UI.

8. Esegui il deployment della nuova revisione.

Per ulteriori informazioni, vedi Tutorial: come scaricare un proxy utilizzando l'interfaccia utente e l'API di gestione nell' Community Apigee.

Struttura del proxy API

Un proxy API è costituito dalla seguente configurazione:

Struttura della directory del proxy API e contenuti

I componenti della tabella precedente sono definiti dai file di configurazione struttura della directory:

File di configurazione e directory struttura di un proxy API

Questa sezione illustra i file di configurazione e la struttura di directory di un proxy API.

• Configurazione di base
• ProxyEndpoint
• TargetEndpoint
  .
  • Configurazione dell'endpoint di destinazione TLS/SSL
• Norme
• Flussi
• Risorse

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

ProxyEndpoint

Nell'immagine seguente viene mostrato il flusso di richiesta/risposta:

/apiproxy/proxies/default.xml

La configurazione ProxyEndpoint definisce l'interfaccia in entrata (rivolta al client) per un'API proxy. Quando si configura un ProxyEndpoint, si imposta una configurazione di rete 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>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Gli elementi di configurazione richiesti in un ProxyEndpoint di base sono:

Configurazione endpoint proxy Elements

Come configurare RouteRules

Un TargetEndpoint denominato si riferisce a un file di configurazione in /apiproxy/targets per per cui la RouteRule inoltra una richiesta dopo l'elaborazione da parte del ProxyEndpoint.

Ad esempio, la seguente RouteRule si riferisce alla configurazione /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Chiamata URL diretta

Un ProxyEndpoint può anche richiamare direttamente un servizio di backend. La chiamata diretta all'URL ignora qualsiasi denominata TargetEndpoint in /apiproxy/targets). Per questo motivo, TargetEndpoint è una configurazione facoltativa del proxy API, anche se, in pratica, una chiamata diretta dal ProxyEndpoint 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 Edge. Consulta le sezioni Riferimento condizioni e Riferimento delle variabili.

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 al TargetEndpoint 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 nulla a supporto degli scenari in cui il messaggio di richiesta non devono essere inoltrati al TargetEndpoint. Ciò è utile quando ProxyEndpoint esegue l'elaborazione necessaria, ad esempio utilizzando JavaScript per chiamare un servizio esterno il recupero dei dati da una ricerca nei servizi API di archiviazione di coppie chiave/valore.

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

Un TargetEndpoint è l'equivalente in uscita di un ProxyEndpoint. Un TargetEndpoint funziona come a un servizio di backend o a un'API. Invia richieste e riceve risposte.

Un proxy API non deve necessariamente avere TargetEndpoint. ProxyEndpoint può essere configurato per chiamare URL strato Add. Un proxy API senza TargetEndpoint di solito contiene un ProxyEndpoint 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

TargetEndpoint definisce la connessione in uscita da Apigee Edge 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/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Configurazione endpoint di destinazione Elements

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

• HTTPTargetConnection per chiamate HTTP(S)
• LocalTargetConnection per il chaining proxy-proxy locale
• ScriptTarget per le chiamate a un cluster Edge-hosted Script Node.js

Configurane solo una in un TargetEndpoint.

Configurazione dell'endpoint di destinazione TLS/SSL

TargetEndpoint spesso devono 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 di TargetEndpoint

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

TargetEndpoint di esempio con autenticazione client in uscita abilitata

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

Per istruzioni dettagliate, vedi Configurare TLS da perimetro al backend (cloud e cloud privato).

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. Le seguenti L'articolo della community Apigee spiega questo scenario in modo più dettagliato e fornisce un'API di cui è possibile eseguire il deployment esempi di proxy: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

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 Assegna messaggio. 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 TargetEndpoint che utilizza HTTPS, devi considerare il caso Il certificato TLS/SSL scade o una modifica alla configurazione di sistema richiede l'aggiornamento del certificato. Nella un'installazione Edge per il cloud privato, durante la configurazione di TLS/SSL utilizzando valori statici o usando le variabili di flusso, c'è la possibilità che sia necessario riavviare i processori di messaggi.

Per ulteriori informazioni, consulta Aggiornamento di un protocollo TLS certificato.

Tuttavia, puoi facoltativamente configurare il TargetEndpoint in modo che utilizzi un riferimento alla 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 è mostrato un TargetEndpoint 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 -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

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

Utilizza la seguente chiamata API GET per visualizzare il riferimento:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

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 -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

TargetEndpoint con bilanciamento del carico di destinazione

TargetEndpoint supporta il bilanciamento del carico tra più TargetServer denominati utilizzando tre algoritmi di bilanciamento.

Per istruzioni dettagliate, consulta Bilanciamento del carico tra i backend server web.

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

Allegato alle norme

L'immagine seguente mostra la sequenza di esecuzione dei flussi proxy API:

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 allegato ai criteri Elements

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 un flusso PreFlow, uno o più flussi "condizionali" facoltativi o 'named' (con nome) 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 al ProxyEndpoint, che viene eseguito dopo viene restituita all'app client richiedente. Solo il criterio MessageLogging e Puoi collegare l'estensione Google Stackdriver Logging 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 .

Guarda un breve video dimostrativo

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

ProxyEndpoint e TargetEndpoint 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 hai bisogno.

Definendo i flussi condizionali, puoi applicare i passaggi di elaborazione in un proxy API in base a:

• URI della 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

Elaborazione dei passaggi

L'ordine sequenziale dei flussi condizionali è applicato da Apigee Edge. 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. Questi vengono visualizzati nello script dell'API nell'interfaccia utente di gestione.

Consulta File di risorse per le 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. I servizi API risolvono 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.