Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Il criterio IncrementaFault consente agli sviluppatori di API di avviare un flusso di errore, impostare variabili di errore
in un messaggio del corpo della risposta e impostare codici di stato di risposta appropriati. Puoi anche utilizzare il criterio AlzaFault
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 degli accessi del router utilizzati per il debug, è importante identificare l'errore in modo preciso.
Puoi utilizzare il criterio AlzaFault per trattare condizioni specifiche come errori, anche se un errore effettivo non si è verificato 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 del backend contiene la stringa unavailable, puoi richiamare il criterio AlzaFault come mostrato nello snippet di codice riportato di seguito:
<!-- /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 AlzaFault è visibile come fault.name in
Monitoraggio delle API e come x_apigee_fault_policy nei log degli accessi di Analytics e router.
Ciò consente di diagnosticare facilmente la causa dell'errore.
Antipattern
Utilizzare il criterio AlzaFault in 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 e viene visualizzato un errore InvalidAccessToken. In caso di errore, Edge imposta fault.name su InvalidAccessToken, entra nel flusso di errori ed esegue tutte le regole di errore definite. In FaultRule, esiste un criterio AlzaFault 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 significa che la variabile fault.name
viene sovrascritta e maschera la 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 AlzaFault in una regola FaultRule in tutte le condizioni
Nell'esempio seguente, un criterio AlzaFault 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 AlzaFault. 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 AlzaFault per restituire una risposta HTTP 2xx al di fuori del flusso di errori.
Nell'esempio seguente, 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>
Lo scopo è restituire immediatamente la risposta al client API senza elaborare altri criteri. Tuttavia, questo 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 AlzaFault come descritto sopra comporta la sovrascrittura delle variabili di errore della chiave con il nome del criterio AlzaFault anziché con il nome del criterio con errori. Nei log di accesso di Analytics e NGINX,
le variabili x_apigee_fault_code e x_apigee_fault_policy
vengono sovrascritte. In Monitoraggio API, i valori Fault Code
e Fault Policy vengono sovrascritti. Questo comportamento rende difficile la risoluzione dei problemi e
determinare quale criterio è la vera causa dell'errore.
Nello screenshot riportato di seguito di Monitoraggio API puoi vedere che i criteri relativi al codice di errore e al 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 perimetrale genera un errore e vuoi personalizzare il messaggio di risposta di errore, utilizza i criterivaletin o JavaScript anziché il criterio RaiseFault.
Il criterio RaiseFault deve essere utilizzato in un flusso diverso da errori. In altre parole, utilizza AlzaFault solo per trattare una condizione specifica come 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 AlzaFault per segnalare che i parametri di input obbligatori mancano o hanno una sintassi errata.
Puoi anche utilizzare AlzaFault in una regola di errore se vuoi rilevare un errore durante l'elaborazione di un guasto. Ad esempio, il gestore dei guasti potrebbe causare un errore che vuoi segnalare utilizzando AlzaFault.