Riferimento per la configurazione dei proxy API

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

In qualità di sviluppatore che lavora con Apigee Edge, le tue attività di sviluppo principali riguardano la configurazione di proxy API che fungono da proxy per API o servizi di backend. Questo documento è un riferimento di 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 Crea un proxy API semplice.

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

• Utilizzo dell'editor XML all'interno dell'interfaccia utente di Edge
• Scarica la configurazione e modificala localmente, come descritto in Sviluppo locale delle configurazioni proxy.

Sviluppo locale delle configurazioni proxy

Puoi scaricare le configurazioni proxy per modificarle su una macchina locale. Al termine, carica i risultati su Edge. Questo approccio ti consente di integrare le configurazioni del proxy nel controllo del codice sorgente, nel controllo delle versioni e in altri flussi di lavoro condivisi. Inoltre, se lavori su una configurazione proxy in locale, puoi utilizzare i tuoi strumenti di convalida ed editor XML.

Questa sezione descrive come utilizzare l'interfaccia utente per scaricare una configurazione proxy esistente, modificarla e poi caricarla di nuovo in Edge per il deployment. Puoi anche utilizzare apigeetool per scaricare ed eseguire il deployment di una nuova configurazione proxy (utilizzando rispettivamente i comandi fetchproxy e deployproxy).

Per modificare una configurazione proxy localmente utilizzando la UI:

1. Scarica la configurazione proxy attuale nell'interfaccia utente Edge. (Nella visualizzazione Proxy API, seleziona Progetto > Scarica revisione.)
2. Sulla tua macchina locale, crea una nuova directory ed estrai il file ZIP scaricato al suo interno.

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

   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 necessità. Per una descrizione dei file di origine in una configurazione proxy, vedi File di configurazione e struttura delle directory di un proxy API.

   Ad esempio, per attivare il monitoraggio dell'integrità nel proxy API, modifica il file di configurazione TargetEndpoint nella directory /apiproxy/targets/. Il file predefinito in questa directory è default.xml, anche se potrebbero esserci file con nomi diversi se utilizzi target condizionali.

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

4. Dopo aver terminato la modifica dei file di configurazione del proxy, assicurati di salvare le modifiche.
5. Passa alla nuova directory creata quando hai estratto i file ZIP (la radice dei file di configurazione estratti).

   Ad esempio, se hai estratto i file nella directory /myappdir, passa a questa directory, come mostrato 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 di nuovo i file di configurazione del proxy, inclusi i file nuovi o modificati. Puoi utilizzare un utilità come zip, come mostrato nell'esempio seguente:

   zip my-new-proxy.zip -r .

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

   Non esistono 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ò essere utile per il debug o il controllo del codice sorgente.

   Edge incrementa automaticamente il numero di revisione della nuova configurazione proxy quando la carichi.

7. Carica la nuova configurazione proxy utilizzando la UI di Edge. (Nella visualizzazione Proxy API, seleziona Progetto > Carica una nuova revisione.)

   Se ricevi un errore come Bundle is invalid. Empty bundle., assicurati che la directory di primo livello del file ZIP sia /apiproxy. In caso contrario, archivia nuovamente i file di configurazione del proxy dalla radice della directory espansa.

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

   Edge non esegue il deployment della nuova revisione dopo il caricamento con la UI.

8. Esegui il deployment della nuova revisione.

Per saperne di più, consulta Tutorial: How to download a proxy using the UI and the management API nella community Apigee.

Struttura del proxy API

Un proxy API è costituito dalla seguente configurazione:

Struttura e contenuti della directory del proxy API

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

File di configurazione e struttura della directory di un proxy API

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

• Configurazione di base
• ProxyEndpoint
• TargetEndpoint
  • Configurazione TargetEndpoint 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 deve essere univoco all'interno di un'organizzazione.

Configurazione di esempio:

<APIProxy name="weatherapi">
</APIProxy>

Elementi di configurazione di base

ProxyEndpoint

L'immagine seguente mostra il flusso di richiesta/risposta:

/apiproxy/proxies/default.xml

La configurazione di ProxyEndpoint definisce l'interfaccia in entrata (rivolta al client) per un proxy API. Quando configuri un ProxyEndpoint, imposti una configurazione di rete che definisce in che modo le applicazioni client ("app") devono richiamare l'API sottoposta a proxy.

La seguente configurazione di esempio di ProxyEndpoint verrà memorizzata 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 obbligatori in un ProxyEndpoint di base sono:

Configurazione di ProxyEndpoint Elementi

Come configurare RouteRules

Un TargetEndpoint denominato fa riferimento a un file di configurazione in /apiproxy/targets a cui RouteRule inoltra una richiesta dopo l'elaborazione da parte di ProxyEndpoint.

Ad esempio, la seguente RouteRule fa riferimento alla configurazione /apiproxy/targets/myTarget.xml:

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

Chiamata diretta dell'URL

Un ProxyEndpoint può anche richiamare direttamente un servizio di backend. L'invocazione diretta dell'URL ignora qualsiasi configurazione TargetEndpoints denominata in /apiproxy/targets. Per questo motivo, TargetEndpoint è una configurazione del proxy API facoltativa, anche se, in pratica, l'invocazione diretta da ProxyEndpoint non è consigliata.

Ad esempio, la seguente RouteRule esegue una chiamata HTTP a http://api.mycompany.com/v2.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Route condizionali

RouteRules può essere concatenato per supportare il routing dinamico in fase di runtime. Le richieste in entrata possono essere indirizzate a configurazioni TargetEndpoint denominate, direttamente agli URL o a una combinazione dei due, in base alle intestazioni HTTP, al contenuto del messaggio, ai parametri di query o a informazioni contestuali come l'ora del giorno, le impostazioni internazionali e così via.

Le RouteRule condizionali funzionano come altre istruzioni condizionali su Apigee Edge. Consulta Riferimento per le condizioni e Riferimento per le variabili.

Ad esempio, la seguente combinazione 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 a 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 null per supportare scenari in cui il messaggio di richiesta non deve essere inoltrato a TargetEndpoint. Ciò è utile quando ProxyEndpoint esegue tutta l'elaborazione necessaria, ad esempio utilizzando JavaScript per chiamare un servizio esterno o recuperando dati da una ricerca nell'archivio chiave/valore dei servizi API.

Ad esempio, il seguente codice definisce una route null:

<RouteRule name="GoNowhere"/>

Le route nulle condizionali possono essere utili. Nell'esempio seguente, una route null è configurata per l'esecuzione quando un'intestazione HTTP request.header.X-DoNothing ha un valore diverso da null.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Ricorda che le RouteRules possono essere concatenate, quindi una Route nulla condizionale sarebbe in genere un componente di un insieme di RouteRules progettate per supportare il routing condizionale.

Un utilizzo pratico di una route nulla condizionale è il supporto della memorizzazione nella cache. Utilizzando il valore della variabile impostata dalla policy di cache, puoi configurare un proxy API per eseguire la route null quando una voce viene pubblicata 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 funge da client per un servizio o un'API di backend: invia richieste e riceve risposte.

Un proxy API non deve avere TargetEndpoints. ProxyEndpoint può essere configurato per chiamare direttamente gli URL. Un proxy API senza TargetEndpoints in genere contiene un ProxyEndpoint che chiama direttamente un servizio di backend o che è configurato per chiamare un servizio utilizzando Java o JavaScript.

Configurazione di TargetEndpoint

/targets/default.xml

TargetEndpoint definisce la connessione in uscita da Apigee Edge a un altro servizio o risorsa.

Ecco una configurazione di esempio di TargetEndpoint:

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

Elementi di configurazione di TargetEndpoint

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

• HTTPTargetConnection per chiamate HTTP(S)
• LocalTargetConnection per il concatenamento proxy-to-proxy locale
• ScriptTarget per le chiamate a uno script Node.js ospitato su Edge

Configura solo uno di questi in un TargetEndpoint.

Configurazione TargetEndpoint TLS/SSL

Gli endpoint di destinazione spesso devono gestire connessioni HTTPS con un'infrastruttura di backend eterogenea. Per questo motivo, sono supportate diverse impostazioni di configurazione TLS/SSL.

TLS/SSL Elementi di configurazione 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>

Esempio di TargetEndpoint 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, consulta Configurazione di TLS da Edge al backend (cloud e cloud privato).

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 target di produzione), puoi fare in modo che il proxy API rilevi a livello di programmazione l'ambiente che sta chiamando e imposti dinamicamente i riferimenti all'archivio chiavi e all'archivio attendibile appropriati. Il seguente articolo della community Apigee spiega questo scenario in modo più dettagliato e fornisce esempi di proxy API implementabili: Dynamic SSLInfo for TargetEndpoint using variable reference.

Nell'esempio seguente di come impostare il tag <SSLInfo> in una configurazione TargetEndpoint, i valori possono essere forniti in fase di runtime, ad esempio da un callout Java, da un criterio JavaScript o da un criterio Assign Message. Utilizza le variabili del messaggio che contengono i valori che vuoi impostare.

Le variabili sono consentite solo nei seguenti elementi.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

Utilizzo di riferimenti per impostare dinamicamente i valori TLS/SSL

Quando configuri un TargetEndpoint che utilizza HTTPS, devi considerare il caso in cui il certificato TLS/SSL scade o una modifica alla configurazione del sistema richiede l'aggiornamento del certificato. In un'installazione di Edge for Private Cloud, quando configuri TLS/SSL utilizzando valori statici o variabili di flusso, è possibile che tu debba riavviare i Message Processor.

Per saperne di più, vedi Aggiornare un certificato TLS.

Tuttavia, puoi configurare facoltativamente TargetEndpoint in modo che utilizzi un riferimento al keystore o al truststore. Il vantaggio di utilizzare un riferimento è che puoi aggiornarlo in modo che punti a un keystore o un truststore diverso per aggiornare il certificato TLS/SSL senza dover riavviare i processori di messaggi.

Ad esempio, di seguito è riportato un TargetEndpoint 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 -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 del keystore e il relativo tipo.

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 keystore diverso, assicurandoti che l'alias abbia 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 target

TargetEndpoints supporta il bilanciamento del carico su più TargetServer denominati utilizzando tre algoritmi di bilanciamento del carico.

Per istruzioni dettagliate, consulta la sezione Bilanciamento del carico tra server di backend.

Norme

La directory /policies in un proxy API contiene tutte le policy disponibili da allegare ai flussi nel proxy API.

Elementi di configurazione delle policy

Allegato delle norme

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

Come mostrato sopra:

Le policy vengono associate come passaggi di elaborazione ai flussi. Il nome del criterio viene utilizzato per fare riferimento al criterio da applicare come passaggio di elaborazione. Il formato di un allegato di norme è il seguente:

<Step><Name>MyPolicy</Name></Step>

Le policy vengono applicate nell'ordine in cui vengono collegate a un flusso. Ad esempio:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Elementi di configurazione dell'allegato di policy

Flussi

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

• PreFlow: viene sempre eseguito. Viene eseguito prima di qualsiasi flusso condizionale.
• PostFlow: viene sempre eseguito. Viene eseguito dopo qualsiasi flusso condizionale.

Inoltre, puoi aggiungere un PostClientFlow a ProxyEndpoint, che viene eseguito dopo che la risposta viene restituita all'app client richiedente. A questo flusso possono essere associate solo le norme MessageLogging e l'estensione Google Stackdriver Logging. PostClientFlow riduce la latenza del proxy API e rende disponibili le informazioni per la registrazione 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 fine del messaggio di risposta.

Guarda un breve video su come fare

Ecco un esempio di PostClientFlow con un criterio di registrazione dei messaggi allegato.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

La pipeline di elaborazione del proxy API esegue i flussi nella seguente sequenza:

Pipeline di richiesta:

1. Proxy Request PreFlow
2. Flussi condizionali della richiesta proxy (facoltativo)
3. Proxy Request PostFlow
4. Target Request PreFlow
5. Flussi condizionali delle richieste target (facoltativo)
6. Target Request PostFlow

Pipeline di risposta:

1. Target Response PreFlow
2. Flussi condizionali di risposta target (facoltativo)
3. Target Response PostFlow
4. Proxy Response PreFlow
5. Flussi condizionali di risposta del proxy (facoltativo)
6. PostFlow di risposta del proxy
7. PostClientFlow Response (facoltativo)

Solo i flussi con allegati di criteri devono essere configurati nelle configurazioni ProxyEndpoint o TargetEndpoint. PreFlow e PostFlow devono essere specificati in una configurazione ProxyEndpoint o TargetEndpoint solo quando è necessario applicare un criterio durante l'elaborazione di PreFlow o PostFlow.

A differenza dei flussi condizionali, l'ordine degli elementi PreFlow e PostFlow non è importante: il proxy API eseguirà sempre ciascun elemento nel punto appropriato della pipeline, indipendentemente dalla posizione in cui vengono visualizzati nella configurazione dell'endpoint.

Flussi condizionali

ProxyEndpoint e TargetEndpoint supportano un numero illimitato di flussi condizionali (noti anche come "flussi denominati").

Il proxy API verifica la condizione specificata nel flusso condizionale e, se la condizione è soddisfatta, i passaggi di elaborazione nel flusso condizionale vengono eseguiti dal proxy API. Se la condizione non è soddisfatta, i passaggi di elaborazione nel flusso condizionale vengono ignorati. I flussi condizionali vengono valutati nell'ordine definito nel proxy API e viene eseguito il primo la cui condizione è soddisfatta.

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 del modulo
• Molti altri tipi di condizioni

Ad esempio, il seguente flusso condizionale specifica che viene eseguito solo quando il percorso della risorsa richiesta è /accesstoken. Qualsiasi richiesta in entrata con il percorso /accesstoken causa l'esecuzione di questo flusso, insieme a tutte le norme associate al flusso. Se il percorso della richiesta non include il suffisso /accesstoken, il flusso non viene eseguito (anche se potrebbe essere eseguito un altro flusso condizionale).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request>
  </Flow>
</Flows>

Elementi di configurazione del flusso

Elaborazione dei passaggi

L'ordine sequenziale dei flussi condizionali viene applicato da Apigee Edge. I flussi condizionali vengono eseguiti dall'alto verso il basso. Viene eseguito il primo flusso condizionale la cui condizione restituisce true e viene eseguito un solo flusso condizionale.

Ad esempio, nella seguente configurazione di Flow, qualsiasi richiesta in entrata che non includa il suffisso del percorso /first o /second causerà l'esecuzione di ThirdFlow, applicando la policy denominata 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 allegati ai flussi utilizzando i criteri. Questi vengono visualizzati nella sezione "Script" dell'editor proxy API nell'interfaccia utente di gestione.

Consulta File di risorse per i tipi di risorse supportati.

Le risorse possono essere archiviate in un proxy API, un ambiente o un'organizzazione. In ogni caso, una risorsa viene a cui viene fatto riferimento per nome in un criterio. API Services risolve il nome passando dal proxy API, all'ambiente e all'organizzazione.

A una risorsa archiviata a livello di organizzazione è possibile fare riferimento tramite i criteri in qualsiasi ambiente. A una risorsa archiviata a livello di ambiente è possibile fare riferimento nei criteri di quell'ambiente. Una risorsa archiviata a livello di proxy API può essere referenziata solo dai criteri in quel proxy API.