Stai visualizzando la documentazione di Apigee Edge.
Consulta la
documentazione di Apigee X. info
Il criterio RaiseFault consente agli sviluppatori di API di avviare un flusso di errori, impostare le variabili di errore
in un messaggio del corpo della risposta e impostare i codici di stato della risposta appropriati. Puoi anche utilizzare il criterio RaiseFault
per impostare le variabili di flusso relative all'errore, ad esempio fault.name, fault.type,
e fault.category. Poiché queste variabili sono visibili nei dati di analisi e nei log di accesso del router
utilizzati per il debug, è importante identificare l'errore con precisione.
Puoi utilizzare il criterio RaiseFault per trattare condizioni specifiche come errori, anche se non si è verificato un errore effettivo
in un altro criterio o nel server di backend del proxy API. Ad esempio, se vuoi
che il proxy invii un messaggio di errore personalizzato all'app client ogni volta che il corpo della risposta di backend
contiene la stringa unavailable, puoi richiamare il criterio RaiseFault come
mostrato nel seguente snippet di codice:
<!-- /antipatterns/examples/raise-fault-conditions-1.xml --> <TargetEndpoint name="default"> ... <Response> <Step> <Name>RF-Service-Unavailable</Name> <Condition>(message.content Like "*unavailable*")</Condition> </Step> </Response> ...
Il nome del criterio RaiseFault è visibile come il fault.name in
API Monitoring e come il x_apigee_fault_policy nei log di accesso di Analytics e del router.
In questo modo è più facile diagnosticare la causa dell'errore.
Antipattern
Utilizzo del criterio RaiseFault all'interno di FaultRules dopo che un altro criterio ha già generato un errore
Considera l'esempio riportato di seguito, in cui un criterio OAuthV2 nel flusso del proxy API non è riuscito a causa di un errore InvalidAccessToken. In caso di errore, Edge imposta fault.name come InvalidAccessToken, entra nel
flusso di errori ed esegue tutte le FaultRules definite. In FaultRule è presente un criterio RaiseFault denominato
RaiseFault che invia una risposta di errore personalizzata ogni volta che si verifica un errore InvalidAccessToken. Tuttavia, l'utilizzo del criterio RaiseFault in una FaultRule comporta la sovrascrittura della variabile fault.name
e l'occultamento della vera causa dell'errore.
<!-- /antipatterns/examples/raise-fault-conditions-2.xml --> <FaultRules> <FaultRule name="generic_raisefault"> <Step> <Name>RaiseFault</Name> <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition> </Step> </FaultRule> </FaultRules>
Utilizzo del criterio RaiseFault in una FaultRule in tutte le condizioni
Nell'esempio riportato di seguito, un criterio RaiseFault denominato RaiseFault viene eseguito se fault.name
non è RaiseFault:
<!-- /antipatterns/examples/raise-fault-conditions-3.xml --> <FaultRules> <FaultRule name="fault_rule"> .... <Step> <Name>RaiseFault</Name> <Condition>!(fault.name equals "RaiseFault")</Condition> </Step> </FaultRule> </FaultRules>
Come nel primo scenario, le variabili di errore chiave fault.name, fault.code,
e fault.policy vengono sovrascritte con il nome del criterio RaiseFault. Questo comportamento rende
quasi impossibile determinare quale criterio ha effettivamente causato l'errore senza accedere a un file di traccia
che mostra l'errore o riprodurre il problema.
Utilizzo del criterio RaiseFault per restituire una risposta HTTP 2xx al di fuori del flusso di errori.
Nell'esempio riportato di seguito, un criterio RaiseFault denominato HandleOptionsRequest viene eseguito quando
il verbo della richiesta è OPTIONS:
<!-- /antipatterns/examples/raise-fault-conditions-4.xml --> <PreFlow name="PreFlow"> <Request> … <Step> <Name>HandleOptionsRequest</Name> <Condition>(request.verb Equals "OPTIONS")</Condition> </Step> … </PreFlow>
L'intenzione è di restituire immediatamente la risposta al client API senza elaborare altri criteri. Tuttavia, questo comportamento porterà a dati di analisi fuorvianti perché le variabili di errore conterranno il nome del criterio RaiseFault, rendendo più difficile il debug del proxy. Il modo corretto per implementare il comportamento desiderato è utilizzare i flussi con condizioni speciali, come descritto in Aggiungere il supporto CORS.
Impatto
L'utilizzo del criterio RaiseFault come descritto sopra comporta la sovrascrittura delle variabili di errore chiave con il
nome del criterio RaiseFault anziché con il nome del criterio non riuscito. Nei log di accesso di Analytics e NGINX,
le variabili x_apigee_fault_code e x_apigee_fault_policy vengono sovrascritte. In API Monitoring, Fault Code
e Fault Policy vengono sovrascritti. Questo comportamento rende difficile la risoluzione dei problemi e
la determinazione del criterio che è la vera causa dell'errore.
Nello screenshot riportato di seguito di API Monitoring,
puoi notare che il codice di errore e il criterio di errore sono stati sovrascritti con valori RaiseFault
generici, rendendo impossibile determinare la causa principale dell'errore dai log:
Best practice
Quando un criterio Edge genera un errore e vuoi personalizzare il messaggio di risposta di errore, utilizza i criteri AssignMessage o JavaScript anziché il criterio RaiseFault.
Il criterio RaiseFault deve essere utilizzato in un flusso non di errore. Ciò significa che devi utilizzare RaiseFault solo per trattare una condizione specifica come un errore, anche se non si è verificato un errore effettivo in un criterio o nel server di backend del proxy API. Ad esempio, puoi utilizzare il criterio RaiseFault per segnalare che mancano parametri di input obbligatori o che la sintassi è errata.
Puoi anche utilizzare RaiseFault in una regola di errore se vuoi rilevare un errore durante l'elaborazione di un errore. Ad esempio, il gestore di errori stesso potrebbe causare un errore che vuoi segnalare utilizzando RaiseFault.