Riferimento per la configurazione dei proxy API

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

In qualità di sviluppatore che lavora con Apigee Edge, le tue attività di sviluppo principali prevedono la configurazione di proxy API che fungono da proxy per le API o i servizi di backend. Questo documento è un riferimento di tutti gli elementi di configurazione disponibili durante la creazione dei proxy API.

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

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

Sviluppo locale di configurazioni proxy

Puoi scaricare le configurazioni proxy in modo da poterle modificare su un computer locale. Al termine, carica i risultati su Edge. Questo approccio consente di integrare le configurazioni proxy nel controllo del codice sorgente, nel controllo delle versioni e in altri flussi di lavoro condivisi. Inoltre, lavorando su una configurazione proxy in locale, puoi utilizzare il tuo editor XML e i tuoi strumenti di convalida.

Questa sezione descrive come utilizzare l'interfaccia utente per scaricare una configurazione proxy esistente, modificarla e quindi caricarla nuovamente su 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 l'interfaccia utente:

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

    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 nella struttura del proxy API.

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

    Ad esempio, per abilitare il monitoraggio dello stato di 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 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 radice dei file di configurazione espansi).

    Ad esempio, se hai espanso i file nella directory /myappdir, passa a 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 sia inclusa nel file ZIP. La directory di primo livello del file ZIP deve essere /apiproxy.

  6. Archivia nuovamente i file di configurazione del proxy, inclusi i file nuovi o modificati. Puoi utilizzare un'utilità come zip, come mostra l'esempio seguente:
    zip my-new-proxy.zip -r .

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

    Non ci sono 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 il numero di revisione della nuova configurazione proxy automaticamente quando la carichi.

  7. Carica la nuova configurazione del proxy utilizzando l'UI Edge. Nella vista Proxy API, seleziona Progetto > Carica una nuova revisione.

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

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

    Edge non esegue il deployment della nuova revisione per te dopo averla caricata con l'interfaccia utente.

  8. Esegui il deployment della nuova revisione.

Per maggiori informazioni, consulta il Tutorial: come scaricare un proxy utilizzando l'interfaccia utente e l'API di gestione nella community Apigee.

Struttura del proxy API

Un proxy API è costituito dalla seguente configurazione:

Configurazione di base Impostazioni di configurazione principali per un proxy API. Vedi Configurazione di base.
Configurazione proxyEndpoint Impostazioni per la connessione HTTP in entrata (dalla richiesta di app ad Apigee Edge), i flussi di richiesta e risposta e gli allegati dei criteri. Vedi ProxyEndpoint.
TargetEndpoint Configuration (Configurazione endpoint target) Impostazioni per la connessione HTTP in uscita (da Apigee Edge al servizio di backend), i flussi di richiesta e risposta e gli allegati dei criteri. Vedi TargetEndpoint.
Flussi Pipeline di richiesta e risposta ProxyEndpoint e TargetEndpoint a cui è possibile associare i criteri. Vedi Flussi.
Norme File di configurazione in formato XML conformi agli schemi di criteri di Apigee Edge. Consulta le norme.
Risorse Script, file JAR e file YAML a cui fanno riferimento i criteri per eseguire logica personalizzata. Consulta le risorse.

Struttura e contenuti della directory del proxy API

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

Mostra la struttura di directory in cui apiproxy è la radice. Direttamente nella directory apiproxy ci sono i criteri, i proxy, le risorse e le directory delle destinazioni, nonché il file weatherapi.xml.

File di configurazione e struttura di directory di un proxy API

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

Configurazione di base

/apiproxy/weatherapi.xml

La configurazione di base per un proxy API, che definisce il nome del proxy API. Il nome deve essere univoco all'interno di un'organizzazione.

Configurazione di esempio:

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

Elementi di configurazione di base

Nome Descrizione Predefinito Campo obbligatorio?
APIProxy
name Il nome del proxy API, che deve essere univoco all'interno di un'organizzazione. I caratteri che puoi utilizzare nel nome sono limitati a quanto segue: A-Za-z0-9_- N/A
revision Il numero di revisione della configurazione del proxy API. Non è necessario impostare esplicitamente il numero di revisione, poiché Apigee Edge monitora automaticamente la revisione corrente del proxy API. N/A No
ConfigurationVersion La versione dello schema di configurazione del proxy API a cui è conforme il proxy API. L'unico valore attualmente supportato è mainVersion 4 e minorVersion 0. Questa impostazione può essere utilizzata in futuro per consentire l'evoluzione del formato del proxy API. 4.0 No
Description Una descrizione testuale del proxy API. Se fornita, la descrizione verrà visualizzata nell'interfaccia utente di gestione perimetrale. N/A No
DisplayName Un nome facile da usare che può essere diverso dall'attributo name della configurazione del proxy API. N/A No
Policies Un elenco di criteri nella directory /policies di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di gestione perimetrale. Si tratta semplicemente di un'impostazione "manifest", progettata per fornire visibilità sui contenuti del proxy API. N/A No
ProxyEndpoints Un elenco di ProxyEndpoint nella directory /proxies di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di gestione perimetrale. Si tratta semplicemente di un'impostazione "manifest", progettata per fornire visibilità sui contenuti del proxy API. N/A No
Resources Un elenco di risorse (JavaScript, Python, Java, YAML) nella directory /resources di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di gestione perimetrale. Si tratta semplicemente di un'impostazione "manifest", progettata per fornire visibilità sui contenuti del proxy API. N/A No
Spec Identifica la specifica OpenAPI associata al proxy API. Il valore è impostato su un URL o su un percorso nell'archivio delle specifiche.

Nota: lo store delle specifiche è disponibile solo nell'esperienza New Edge. Per maggiori informazioni sull'archivio delle specifiche, consulta Gestione e condivisione delle specifiche.
N/A No
TargetServers Un elenco di TargetServer a cui viene fatto riferimento in qualsiasi TargetEndpoints di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di gestione perimetrale. Si tratta semplicemente di un'impostazione "manifest", progettata per fornire visibilità sui contenuti del proxy API. N/A No
TargetEndpoints Un elenco di TargetEndpoint nella directory /targets di questo proxy API. Normalmente, questo elemento viene visualizzato solo quando il proxy API è stato creato utilizzando l'interfaccia utente di gestione perimetrale. Si tratta semplicemente di un'impostazione "manifest", progettata per fornire visibilità sui contenuti del proxy API. N/A No

ProxyEndpoint

La seguente immagine mostra il flusso di richiesta/risposta:

Mostra un client che chiama un servizio HTTP. La richiesta passa attraverso l&#39;endpoint proxy e poi l&#39;endpoint di destinazione prima di essere elaborata dal servizio HTTP. La risposta passa attraverso l&#39;endpoint di destinazione e poi l&#39;endpoint proxy prima di essere restituita al client.

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

Elementi di configurazione ProxyEndpoint

Nome Descrizione Predefinito Campo obbligatorio?
ProxyEndpoint
name Il nome di ProxyEndpoint. Deve essere univoco all'interno della configurazione del proxy API quando (in rari casi) vengono definiti più ProxyEndpoint. I caratteri che puoi utilizzare nel nome sono limitati a quanto segue: A-Za-z0-9._\-$ %. N/A
PreFlow Definisce i criteri nel flusso PreFlow di una richiesta o risposta. N/A
Flows
Definisce i criteri nei flussi condizionali di una richiesta o risposta.
N/A
PostFlow
Definisce i criteri nel flusso PostFlow di una richiesta o risposta.
N/A
HTTPProxyConnection Definisce l'indirizzo di rete e il percorso URI associati al proxy API
BasePath

Una stringa obbligatoria che identifica in modo univoco il percorso dell'URI utilizzato da Apigee Edge per instradare i messaggi in entrata al proxy API appropriato.

Il BasePath è un frammento URI (ad esempio /weather) aggiunto all'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'unicità viene convalidata quando viene generato o importato un proxy API.

Utilizzo di un carattere jolly nei percorsi di base

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

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

/
VirtualHost

Associa un proxy API a URL di base specifici per un ambiente. Un VirtualHost è una configurazione denominata che definisce uno o più URL per un ambiente.

I VirtualHosts denominati per un ProxyEndpoint determinano i domini e le porte su cui è esposto un proxy API e, per estensione, l'URL che le app utilizzano per richiamare un proxy API.

Per impostazione predefinita, per un ambiente sono definiti due VirtualHost denominati: default e secure. Un'organizzazione può anche definire domini personalizzati. Ad esempio, per garantire che un proxy API sia disponibile solo tramite HTTPS, imposta VirtualHost nella connessioneProxy HTTP su secure.

predefinita No
Properties Un insieme di impostazioni di configurazione HTTP facoltative può essere definito come proprietà di un <ProxyEndpoint>. N/A No
FaultRules
Definisce come ProxyEndpoint reagisce a un errore. Una regola di errore specifica due elementi:
  • Una condizione che specifica l'errore da gestire in base alla categoria, alla sottocategoria o al nome predefiniti dell'errore
  • Uno o più criteri che definiscono il comportamento della regola di errore per la condizione corrispondente

Consulta la sezione Gestione degli errori.

N/A No
DefaultFaultRule

Gestisce tutti gli errori (sistema, trasporto, messaggi o criteri) che non sono gestiti esplicitamente da un'altra regola di errore.

Consulta la sezione Gestione degli errori.

N/A No
RouteRule Definisce la destinazione dei messaggi di richiesta in entrata dopo l'elaborazione da parte della pipeline di richieste ProxyEndpoint. Di solito, RouteRule punta a una configurazione TargetEndpoint denominata, ma può anche puntare direttamente a un URL.
Name Attributo obbligatorio, che fornisce un nome per la RouteRule. I caratteri che puoi utilizzare nel nome sono limitati a quanto segue: A-Za-z0-9._\-$ %. Ad esempio, Cat2 %_ è un nome legale. N/A
Condition Un'istruzione condizionale facoltativa utilizzata per il routing dinamico in fase di runtime. Le RouteRules condizionali sono utili, ad esempio, per abilitare il routing basato sui contenuti al fine di supportare il controllo delle versioni del backend. N/A No
TargetEndpoint

Una stringa facoltativa che identifica una configurazione TargetEndpoint denominata. Un TargetEndpoint denominato è qualsiasi TargetEndpoint definito nello stesso proxy API nella directory /targets.

Denominando TargetEndpoint, indichi dove inoltrare i messaggi di richiesta dopo l'elaborazione da parte della pipeline delle richieste ProxyEndpoint. Tieni presente che si tratta di un'impostazione facoltativa.

Un ProxyEndpoint può chiamare direttamente un URL. Ad esempio, una risorsa JavaScript o Java, con il ruolo di client HTTP, potrebbe eseguire il compito di base di TargetEndpoint, ovvero inoltrare le richieste a un servizio di backend.

N/A No
URL Una stringa facoltativa che definisce un indirizzo di rete in uscita chiamato da ProxyEndpoint, bypassando qualsiasi configurazione TargetEndpoint che potrebbe essere archiviata in /targets N/A No

Come configurare RouteRules

Un TargetEndpoint denominato si riferisce a un file di configurazione in /apiproxy/targets a cui la 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 URL diretta

Un ProxyEndpoint può anche richiamare direttamente un servizio di backend. La chiamata di un URL diretto ignora qualsiasi configurazione TargetEndpoints denominata in /apiproxy/targets). Per questo motivo, TargetEndpoint è una configurazione facoltativa del proxy API, anche se, in pratica, la chiamata diretta da ProxyEndpoint è sconsigliata.

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

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

Route condizionali

RouteRules può essere concatenata per supportare il routing dinamico in fase di runtime. Le richieste in entrata possono essere instradate a configurazioni TargetEndpoint denominate, direttamente agli URL o a una combinazione delle due, in base a intestazioni HTTP, contenuto dei messaggi, parametri di query o informazioni contestuali come ora del giorno, impostazioni internazionali e così via.

Le regole di route condizionale funzionano come altre istruzioni condizionali su Apigee Edge. Consulta gli articoli Riferimento condizioni e Riferimento variabili.

Ad esempio, la seguente combinazione RouteRule valuta prima la richiesta in entrata per verificare il valore di un'intestazione HTTP. Se l'intestazione HTTP routeTo ha il valore TargetEndpoint1, la richiesta viene inoltrata 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 null per supportare scenari in cui il messaggio della richiesta non deve essere inoltrato a TargetEndpoint. Questo è utile quando ProxyEndpoint esegue tutte le elaborazioni necessarie, ad esempio utilizzando JavaScript per chiamare un servizio esterno o recuperando dati da una ricerca nell'archivio chiave/valore dei servizi API.

Ad esempio, quanto segue definisce una route nulla:

<RouteRule name="GoNowhere"/>

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

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

Ricorda che RouteRules può essere concatenata, quindi una route nulla condizionale è in genere un componente di un insieme di RouteRules progettato per supportare il routing condizionale.

Un uso pratico di una route null condizionale supporta la memorizzazione nella cache. Utilizzando il valore della variabile impostato dal criterio Cache, puoi configurare un proxy API per eseguire la route null quando viene fornita una voce dalla cache.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

Mostra un client che chiama un servizio HTTP. La richiesta passa attraverso l&#39;endpoint proxy e poi l&#39;endpoint di destinazione prima di essere elaborata dal servizio HTTP. La risposta passa attraverso l&#39;endpoint di destinazione e poi l&#39;endpoint proxy prima di essere restituita al client.

Un TargetEndpoint è l'equivalente in uscita di un ProxyEndpoint. Un TargetEndpoint funziona come client per un'API o un servizio di backend: invia richieste e riceve risposte.

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

Configurazione TargetEndpoint

/targets/default.xml

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

Ecco una configurazione TargetEndpoint di esempio:

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

Elementi di configurazione TargetEndpoint

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

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

Configurane solo uno in un TargetEndpoint.

Nome Descrizione Predefinito Campo obbligatorio?
TargetEndpoint
name Il nome di TargetEndpoint, che deve essere univoco all'interno della configurazione del proxy API. Il nome di TargetEndPoint viene utilizzato nella RouteRule ProxyEndpoint per indirizzare le richieste per l'elaborazione in uscita. I caratteri che puoi utilizzare nel nome sono limitati a quanto segue: A-Za-z0-9._\-$ %. N/A
PreFlow Definisce i criteri nel flusso PreFlow di una richiesta o risposta. N/A
Flows
Definisce i criteri nei flussi condizionali di una richiesta o risposta.
N/A
PostFlow
Definisce i criteri nel flusso PostFlow di una richiesta o risposta.
N/A
HTTPTargetConnection

Con gli elementi figlio, specifica la copertura delle risorse di backend tramite HTTP.

Se utilizzi HTTPTargetConnection, non configurare altri tipi di connessioni di destinazione (ScriptTarget o LocalTargetConnection).

URL Definisce l'indirizzo di rete del servizio di backend a cui TargetEndpoint inoltra i messaggi di richiesta. N/A No
LoadBalancer

Definisce una o più configurazioni TargetServer denominate. Le configurazioni TargetServer denominate possono essere utilizzate per il bilanciamento del carico che definisce due o più connessioni di configurazione degli endpoint.

Puoi anche utilizzare TargetServers per disaccoppiare le configurazioni proxy API dagli URL concreti degli endpoint del servizio di backend.

Consulta Bilanciamento del carico tra server di backend.

N/A No
Properties Un insieme di impostazioni di configurazione HTTP facoltative può essere definito come proprietà di un <TargetEndpoint>. N/A No
SSLInfo Facoltativamente, definisci le impostazioni TLS/SSL su un TargetEndpoint per controllare la connessione TLS/SSL tra il proxy API e il servizio di destinazione. Vedi Configurazione degli endpoint di destinazione TLS/SSL. N/A No
LocalTargetConnection Con gli elementi figlio, specifica una risorsa da raggiungere localmente, bypassando le caratteristiche di rete come il bilanciamento del carico e i processori di messaggi.

Per specificare la risorsa di destinazione, includi l'elemento secondario APIProxy (con l'elemento ProxyEndpoint) o l'elemento figlio Percorso.

Per maggiori informazioni, consulta la sezione Utilizzare insieme i proxy API di Cahaining.

Se utilizzi LocalTargetConnection, non configurare altri tipi di connessioni di destinazione (HTTPTargetConnection o ScriptTarget).

APIProxy Specifica il nome di un proxy API da utilizzare come target per le richieste. Il proxy di destinazione deve trovarsi nella stessa organizzazione e nello stesso ambiente delle richieste di invio del proxy. Si tratta di un'alternativa all'utilizzo dell'elemento Path. N/A No
ProxyEndpoint Utilizzato con APIProxy per specificare il nome del proxyEndpoint del proxy di destinazione. N/A No
Path Specifica il percorso dell'endpoint di un proxy API da utilizzare come destinazione per le richieste. Il proxy di destinazione deve trovarsi nella stessa organizzazione e nello stesso ambiente delle richieste di invio del proxy. Questa è un'alternativa all'utilizzo di APIProxy. N/A No
FaultRules
Definisce come TargetEndpoint reagisce a un errore. Una regola di errore specifica due elementi:
  • Una condizione che specifica l'errore da gestire in base alla categoria, alla sottocategoria o al nome predefiniti dell'errore
  • Uno o più criteri che definiscono il comportamento della regola di errore per la condizione corrispondente

Consulta la sezione Gestione degli errori.

N/A No
DefaultFaultRule

Gestisce tutti gli errori (sistema, trasporto, messaggi o criteri) che non sono gestiti esplicitamente da un'altra FaultRule.

Consulta la sezione Gestione degli errori.

N/A No
ScriptTarget
ResourceURL

Definisce il tipo di risorsa (nodo) e il nome dello script Node.js principale che implementa la funzionalità TargetEndpoint.

<ResourceURL>node://server.js</ResourceURL>

Lo script deve essere incluso nei file di risorse del proxy API. Consulta la sezione Aggiungere Node.js a un proxy API esistente.

Se utilizzi ScriptTarget, non configurare altri tipi di connessioni di destinazione (HTTPTargetConnection o LocalTargetConnection).

N/A
EnvironmentVariable

Facoltativamente, passa le variabili di ambiente allo script Node.js principale.

Consulta Informazioni sul supporto Edge per i moduli Node.js.

N/A No
Arguments

Facoltativamente, passa gli argomenti allo script Node.js principale.

Consulta Informazioni sul supporto Edge per i moduli Node.js.

N/A No

Configurazione dell'endpoint di destinazione TLS/SSL

TargetEndpoints ha spesso bisogno di gestire connessioni HTTPS con un'infrastruttura di backend eterogenea. Per questo motivo, sono supportate diverse impostazioni di configurazione TLS/SSL.

Elementi di configurazione di TargetEndpoint TLS/SSL

Nome Descrizione Predefinito Campo obbligatorio?
SSLInfo
Enabled Indica se TLS/SSL è abilitato per l'endpoint. Il valore predefinito è true se <URL> specifica il protocollo HTTPS e false se <URL> specifica HTTP. true se <URL> specifica HTTPS No
TrustStore Un archivio chiavi contenente certificati server attendibili. N/A No
ClientAuthEnabled Un'impostazione che attiva l'autenticazione client in uscita (TLS/SSL bidirezionale) false No
KeyStore Un archivio chiavi contenente chiavi private utilizzate per l'autenticazione client in uscita N/A Sì (se ClientAuthEnabled è true)
KeyAlias L'alias di chiave della chiave privata utilizzata per l'autenticazione client in uscita N/A Sì (se ClientAuthEnabled è true)
Ciphers

Crittografia supportate per TLS/SSL in uscita. Se non vengono specificate crittografie, saranno consentite tutte le crittografie disponibili per JVM.

Per limitare le crittografie, aggiungi i seguenti elementi che elencano le crittografie supportate:

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
N/A No
Protocols

Protocolli supportati per TLS/SSL in uscita. Se non viene specificato alcun protocollo, saranno consentiti tutti i protocolli disponibili per la JVM.

Per limitare i protocolli, aggiungi i seguenti elementi che elencano i protocolli supportati:

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
N/A No
CommonName

Se specificato, un valore in base al quale viene convalidato il nome comune del certificato di destinazione. Questo valore è valido solo per le configurazioni TargetEndpoint e TargetServer. Non è valido per le configurazioni VirtualHost.

Per impostazione predefinita, il valore specificato corrisponde esattamente al nome comune del certificato di destinazione. Ad esempio, l'uso di *.myhost.com come valore per <CommonName> troverà corrispondenze e convaliderà il nome host di destinazione solo se il valore esatto *.myhost.com viene specificato come nome comune nel certificato di destinazione.

Facoltativamente, Apigee può eseguire la corrispondenza con caratteri jolly utilizzando l'attributo wildcardMatch.

Ad esempio, un nome comune specificato come abc.myhost.com in un certificato di destinazione verrebbe abbinato e convalidato se l'elemento <CommonName> viene specificato come segue:

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

N/A No

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

Utilizzo delle variabili di flusso per impostare i valori TLS/SSL in modo dinamico

Puoi anche impostare dinamicamente i dettagli TLS/SSL per supportare requisiti di runtime flessibili. Ad esempio, se il proxy si connette a due destinazioni potenzialmente diverse (una destinazione di test e una di produzione), puoi fare in modo che il proxy API rilevi in modo programmatico l'ambiente che sta chiamando e imposti dinamicamente i riferimenti all'archivio chiavi e all'archivio di attendibilità appropriati. Il seguente articolo della community Apigee spiega questo scenario in modo più dettagliato e fornisce esempi di proxy API di cui è possibile eseguire il deployment: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

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

Le variabili sono consentite solo nei seguenti elementi.

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

Utilizzo dei riferimenti per impostare i valori TLS/SSL in modo dinamico

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

Per ulteriori informazioni, vedi Aggiornare un certificato TLS.

Tuttavia, puoi facoltativamente configurare TargetEndpoint in modo da utilizzare un riferimento all'archivio chiavi o all'archivio di attendibilità. Il vantaggio dell'utilizzo di un riferimento è che puoi aggiornare il riferimento in modo che punti a un archivio chiavi o a un altro archivio di attendibilità per aggiornare il certificato TLS/SSL senza dover riavviare i processori di messaggi.

Ad esempio, l'immagine seguente è 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.

Per visualizzare il riferimento, utilizza la seguente chiamata API GET:

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 abbia lo stesso nome, usa 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

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

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

Norme

La directory /policies in un proxy API contiene tutti i criteri disponibili per il collegamento a Flows nel proxy API.

Elementi di configurazione dei criteri

Nome Descrizione Predefinito Campo obbligatorio?
Policy
name

Il nome interno del criterio. I caratteri che puoi usare nel nome sono limitati a: A-Za-z0-9._\-$ %. Tuttavia, l'interfaccia utente di gestione perimetrale applica limitazioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy della UI di gestione con un nome diverso in linguaggio naturale.

N/A
enabled

Imposta il criterio su true per applicare il criterio.

Imposta il criterio su false per "disattivare" il criterio. Il criterio non verrà applicato in modo forzato anche se rimane collegato a un flusso.

true No
continueOnError

Imposta il criterio su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Impostalo su true per continuare a eseguire l'esecuzione del flusso anche in caso di errore di un criterio.

false No
async

Nota: questo attributo non rende il criterio eseguito in modo asincrono. Nella maggior parte dei casi, lascia il valore predefinito false.

Se il criterio viene impostato su true, l'esecuzione del criterio viene scaricata su un thread diverso, lasciando libero il thread principale per gestire richieste aggiuntive. Al termine dell'elaborazione offline, il thread principale torna a gestire il flusso dei messaggi. In alcuni casi, l'impostazione asincrona di true migliora le prestazioni del proxy API. Tuttavia, un uso eccessivo di asincrono può compromettere le prestazioni con un cambio di thread troppo elevato.

Per utilizzare il comportamento asincrono nei proxy API, consulta Modello a oggetti JavaScript.

false No

Allegato alle norme

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

mostra un client che chiama un servizio HTTP. La richiesta rileva ProxyEndpoint e TargetEndpoint, ciascuno dei quali contiene passaggi che attivano i criteri. Dopo che il servizio HTTP restituisce la risposta, questa viene elaborata da TargetEndpoint e poi da ProxyEndpoing prima di essere restituita al client. Come per la richiesta, la risposta viene elaborata
  dai criteri entro alcuni passaggi.

Come mostrato sopra:

I criteri sono allegati ai Flussi come passaggi di elaborazione. Il nome del criterio viene utilizzato per fare riferimento al criterio da applicare come passaggio di elaborazione. Il formato dell'allegato del criterio è il seguente:

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

I criteri vengono applicati nell'ordine in cui sono associati a un flusso. Ad esempio:

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

Elementi di configurazione dell'allegato dei criteri

Nome Descrizione Predefinito Campo obbligatorio?
Step
Name Il nome del criterio che deve essere eseguito da questa definizione di passaggio. N/A
Condition Un'istruzione condizionale che determina se il criterio viene applicato o meno. Se a un criterio è associata una condizione, questo viene eseguito solo se l'istruzione condizionale restituisce true. N/A No

Flussi

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

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

Inoltre, puoi aggiungere un PostClientFlow a ProxyEndpoint che viene eseguito dopo che la risposta viene restituita all'app client richiedente. Solo il criterio MessageLogging e l'estensione Google Stackdriver Logging possono essere associati a questo flusso. PostClientFlow riduce la latenza del proxy API e rende disponibili informazioni per il logging che non vengono calcolate finché la risposta non viene restituita al client, ad esempio client.sent.start.timestamp e client.sent.end.timestamp.Il flusso viene utilizzato principalmente per misurare l'intervallo di tempo tra i timestamp di inizio e di fine del messaggio di risposta.

Guarda un breve video dimostrativo

Video: guarda questo breve video sull'utilizzo di un logging dei messaggi in PostClientFlow.

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

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

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

Pipeline di richiesta:

  1. PreFlow richiesta proxy
  2. Flussi condizionali delle richieste proxy (facoltativi)
  3. PostFlow richiesta proxy
  4. Preflusso richiesta target
  5. Flussi condizionali delle richieste target (facoltativi)
  6. PostFlow richiesta target

Pipeline di risposta:

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

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

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

Flussi condizionali

ProxyEndpoints e TargetEndpoints supportano un numero illimitato di flussi condizionali (noti anche come "flussi con nome").

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

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

  • URI 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 richiesta della risorsa è /accesstoken. Qualsiasi richiesta in entrata con il percorso /accesstoken determina l'esecuzione di questo flusso, insieme a tutti i criteri associati al flusso. Se il percorso di richiesta non include il suffisso /accesstoken, il flusso non viene eseguito (anche se potrebbe verificarsi un altro flusso condizionale).

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

Elementi di configurazione dei flussi

Nome Descrizione Predefinito Campo obbligatorio?
Flow Una pipeline di elaborazione di richieste o risposte definita da un ProxyEndpoint o TargetEndpoint
Name Il nome univoco del flusso. N/A
Condition Un'istruzione condizionale che valuta o più variabili per restituire vero o falso. Tutti i flussi diversi dai tipi predefiniti PreFlow e PostFlow devono definire una condizione per la loro esecuzione. N/A
Request La pipeline associata all'elaborazione della richiesta dei messaggi N/A No
Response La pipeline associata all'elaborazione del messaggio di risposta N/A No

Elaborazione del passaggio

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

Ad esempio, nella seguente configurazione di Flow, qualsiasi richiesta in entrata che non include il suffisso del percorso /first o /second comporterà l'esecuzione di ThirdFlow, applicando il criterio denominato Return404.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

Risorse

Le "risorse" (file di risorse da utilizzare nei proxy API) sono script, codice e trasformazioni XSL che possono essere associati a Flows utilizzando i criteri. Questi vengono visualizzati nella sezione "Script" dell'editor proxy API nell'interfaccia utente di gestione.

Consulta File di risorse per conoscere i tipi di risorse supportati.

Le risorse possono essere archiviate in un proxy API, in un ambiente o in un'organizzazione. In ogni caso, in un criterio viene fatto riferimento a una risorsa in base al nome. Servizi API risolve il nome passando dal proxy API all'ambiente, al livello organizzazione.

I criteri possono fare riferimento a una risorsa archiviata a livello di organizzazione in qualsiasi ambiente. I criteri in quell'ambiente possono fare riferimento a una risorsa archiviata a livello di ambiente. I criteri nel proxy API possono fare riferimento a una risorsa archiviata a livello di proxy API.