Cosa devi sapere sugli errori delle norme

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questo argomento descrive la struttura degli errori dei criteri e i tipi di variabili di flusso che vengono impostate quando si verifica un errore del criterio. Queste informazioni sono essenziali se stai progettando e implementando la gestione dei errori per i proxy.

Questo argomento presuppone che tu abbia una comprensione generale di come funziona la gestione dei guasti in Apigee e che tu sappia cosa sono le regole di errore. Se hai bisogno di una revisione, consulta Gestione degli errori. Le informazioni riportate qui ti aiuteranno anche a esplorare e utilizzare il riferimento sugli errori delle norme.

Informazioni sulla risposta di errore del criterio predefinita

Quando un criterio genera un errore, Apigee entra immediatamente nel flusso di errore e genera un messaggio di errore. Questo messaggio generato dal sistema è un oggetto JSON che include due bit di informazioni: errorcode e faultstring.

Nota: è utile sapere che le parti di un errore mostrate di seguito sono disponibili come variabili di flusso. Puoi riorganizzare e personalizzare i messaggi di errore tramite queste variabili. La variabile fault.name è il valore dell'attributo errorcode, mentre error.message è il valore dell'attributo faultstring. Queste variabili sono trattate in modo più dettagliato nelle sezioni seguenti di questo argomento.

Ad esempio:

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"mymessage message is not available for ExtractVariable: ParseJsonResponse"
   }
}

Analizziamo rapidamente questo messaggio di errore:

errorcode è composto da un prefix e un error name, come segue: [prefix].[error_name]. Nell'esempio precedente, "steps.extractvariables è il prefisso e SourceMessageNotAvailable è il nome dell'errore. Il prefisso indica il tipo di criterio che ha generato l'errore. Nell'esempio precedente, puoi notare che un criterio ExtractVariables ha generato l'errore e che il nome dell'errore è SourceMessageNotAvailable.

faultstring contiene una descrizione dell'errore. La stringa di errore in genere include indizi per aiutarti a trovare il problema specifico che ha causato l'errore, come il nome del criterio, il nome di una variabile non risolta o qualsiasi altro elemento abbia contribuito all'errore. Ad esempio, nel messaggio di errore precedente, mymessage è il nome di una variabile di messaggio non risolta a cui viene fatto riferimento nel criterio, mentre ParseJsonResponse è il nome del criterio che ha attivato l'errore.

Nota: nel Riferimento agli errori dei criteri, utilizziamo una convenzione coerente per documentare le stringhe di errore dei criteri. Il punto in cui si verificano le variabili di posizionamento viene indicato con una notazione []. Ecco un esempio di come documentiamo la stringa di errore dell'errore riportato sopra:

VAR_NAME message is not available for ExtractVariable: POLICY_NAME

Variabili specifiche per gli errori dei criteri

Quando viene attivato un errore del criterio, vengono compilate alcune variabili di flusso specifiche per gli errori. Queste variabili sono estremamente utili per la gestione degli errori. Come spiegato in Gestione degli errori, è prassi comune bloccare gli errori dei criteri generati dal sistema ed eseguire un'azione successiva, ad esempio creare una risposta di errore personalizzata. Ad esempio, per motivi di sicurezza, potrebbe essere opportuno impedire ai client di vedere gli errori e i codici di stato effettivi restituiti da Apigee.

Variabile fault.name

Quando un criterio genera un errore, imposta la variabile di flusso fault.name sulla parte error_name del codice di errore (come descritto nella sezione precedente). È molto comune valutare questa variabile per eseguire le regole di errore in modo condizionale.

Ecco una regola di errore di esempio che verifica il valore di fault.name:

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Source Message Not Available Fault">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
</FaultRule>

Tieni presente che, quando un criterio attiva un errore, la variabile fault.name è sempre impostata sul nome dell'errore.

Nota: quando sviluppi il codice per la gestione degli errori, consulta il riferimento sugli errori dei criteri per conoscere il nome di ogni errore relativo ai criteri. Inoltre, è pratica comune utilizzare lo strumento di debug per esaminare le risposte di errore e le variabili impostate.

Variabile [prefix].[policy_name].failed

Oltre a fault.name, un'altra variabile che gli sviluppatori controllano di solito è il flag [prefix].[policy_name].failed, che viene impostato su true o false quando viene eseguito un criterio. Nelle regole di errore, devi verificare se è vero, ovvero se si è verificato un errore. Ecco come creare una condizione che controlli il flag [prefix].[policy_name].failed. Per controllare correttamente questa variabile, devi sapere due cose:

• Il nome del criterio che stai controllando. Si tratta del valore dell'attributo del nome del criterio, non del nome visualizzato. Questo attributo viene sempre incluso nel codice XML di definizione del criterio.
• Un prefisso specifico per il tipo di criterio che stai controllando. Di seguito spiegheremo come trovare il prefisso.

Per spiegarci meglio, ecco un altro esempio di regola di errore. Osserva nella condizione esterna come forma il nome della variabile [prefix].[policy_name].failed. In questo caso il prefisso è extractvariables e il nome del criterio è ParseJsonResponse. In questo caso, la regola di errore viene eseguita solo se questa variabile è true. Inoltre, ecco un suggerimento: poiché le regole di errore possono contenere più passaggi, questo pattern è un buon modo per organizzare le regole di errore in blocchi.

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.ParseJsonResponse.failed = true) </Condition>
</FaultRule>

Nota:come puoi sapere qual è il prefisso della variabile di errore? Non puoi necessariamente indovinare dal contenuto della stringa di errore o del codice di errore. Devi cercarlo nel riferimento sugli errori dei criteri oppure puoi utilizzare la traccia per ispezionare le variabili di flusso che vengono create quando si verifica un errore. Ad esempio, per il criterio Estrai variabili, il prefisso [prefix].[policy_name].failed è extractvariables ed è piuttosto semplice. Tuttavia, il prefisso del criterio di controllo dell'accesso è acl. Quindi, il punto è che devi controllare.

Informazioni sulle variabili error e message

La variabile error è disponibile solo nel flusso di errori di un proxy. Puoi ottenere informazioni utili dalla variabile error, come il messaggio di errore, il codice di stato, la frase di motivazione e così via. Il modello di formattazione per la variabile di errore è il seguente:

error.ERROR_COMPONENT = VALUE

Ad esempio:

error.message = "request message is not available for ExtractVariable:
  ParseJsonResponse"

e

error.status.code = "500"

Suggerimento:puoi utilizzare questa variabile anche per impostare le intestazioni delle risposte. Questo può essere estremamente utile perché nel flusso di errore l'oggetto risposta non è disponibile.

La variabile message è disponibile anche nel flusso di errore e può essere utilizzata per scopi simili alla variabile error. La variabile del messaggio è speciale perché è contestuale. In un flusso di richiesta, si comporta come una variabile di richiesta e in un flusso di risposta può essere utilizzata per ottenere/impostare i valori di risposta.

Consulta la pagina Riferimento alle variabili di flusso per informazioni su tutte le variabili Apigee, inclusi error e message.