Questa pagina è stata tradotta dall'API Cloud Translation.

criterio RaiseFault

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Cosa

Genera un messaggio personalizzato in risposta a una condizione di errore. Utilizza RaiseFault per definire una risposta agli errori che viene restituita all'app richiedente quando si verifica una condizione specifica.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità di ciascun tipo di ambiente, consulta Tipi di criteri.

Per informazioni generali sulla gestione degli errori, consulta Gestione degli errori.

Esempi

Restituzione FaultResponse

Nell'uso più comune, RaiseFault viene utilizzato per restituire una risposta di errore personalizzata all'app richiedente. Ad esempio, questo criterio restituisce un codice di stato 404 senza payload:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

Payload FaultResponse di reso

Un esempio più complesso prevede la restituzione di un payload personalizzato di risposta agli errori, insieme a intestazioni HTTP e un codice di stato HTTP. Nell'esempio seguente, la risposta all'errore viene compilata con un messaggio XML contenente il codice di stato HTTP ricevuto da Apigee dal servizio di backend e un'intestazione contenente il tipo di errore che si è verificato:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Per un elenco di tutte le variabili disponibili per il completamento dinamico dei messaggi FaultResponse, vedi Riferimento per le variabili

Gestire gli errori di callout del servizio

Informazioni sul criterio RaiseFault

Apigee consente di eseguire una gestione personalizzata delle eccezioni utilizzando un criterio di tipo RaiseFault. Il criterio RaiseFault, simile al criterioAssignMessage, consente di generare una risposta agli errori personalizzata in risposta a una condizione di errore.

Utilizza il criterio RaiseFault per definire una risposta di errore che viene restituita all'app richiedente quando si verifica una specifica condizione di errore. La risposta di errore può essere composta da intestazioni HTTP, parametri di query e un payload dei messaggi. Una risposta di errore personalizzata può essere più utile per gli sviluppatori di app e gli utenti finali delle app rispetto ai messaggi di errore generici o ai codici di risposta HTTP.

Se eseguito, il criterio RaiseFault trasferisce il controllo dal flusso attuale al flusso Error, che poi restituisce la risposta di errore designata all'app client richiedente. Quando il flusso del messaggio passa al flusso di errore, non avviene alcuna ulteriore elaborazione dei criteri. Tutti i restanti passaggi di elaborazione vengono ignorati e la risposta di errore viene restituita direttamente all'applicazione richiedente.

Puoi utilizzare RaiseFault in un ProxyEndpoint o in un TargetEndpoint. In genere, devi collegare una Condizione al criterio RaiseFault. Dopo l'esecuzione di RaiseFault, Apigee eseguirà la normale elaborazione degli errori, valutando FaultRules oppure, se non sono definite regole di errore, termina l'elaborazione della richiesta.

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio RaiseFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Attributi <RaiseFault>

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo	Descrizione	Predefinito	Presenza
`name`	Il nome interno della norma. Il valore dell'attributo `name` può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento `<DisplayName>` per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/A	Obbligatorio
`continueOnError`	Impostalo su `false` per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri. Imposta su `true` per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche: Le regole di errore vengono attivate SOLO in stato di errore (informazioni su continueOnError) Gestione dei guasti all'interno del flusso di corrente	false	Facoltativo
`enabled`	Imposta il criterio su `true` per applicare il criterio. Impostala su `false` per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.	true	Facoltativo
`async`	Questo attributo è obsoleto.	false	Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Predefinito

Predefinito	N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo `name` del criterio.
Presenza	Facoltativo
Tipo	Stringa

N/A

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.

Presenza Facoltativo

Tipo Stringa

Elemento <IgnoraUnresolvedVariables>

(Facoltativo) Ignora qualsiasi errore di variabile non risolto nel flusso. Valori validi: true/false. Valore predefinito: true.

Elemento <FaultResponse>

(Facoltativo) Definisce il messaggio di risposta restituito al client richiedente. FaultResponse utilizza le stesse impostazioni del criterioAssignMessage.

Elemento <FaultResponse><AssignVariabile>

Assegna un valore a una variabile del flusso di destinazione. Se la variabile di flusso non esiste, AssignVariable la crea.

Ad esempio, utilizza il seguente codice per impostare la variabile denominata myFaultVar nel criterio RaiseFault:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

Potrai quindi fare riferimento a questa variabile nei modelli di messaggio in un secondo momento nel criterio RaiseFault. Inoltre, un criterio associato a una regola di errore può quindi accedere alla variabile. Ad esempio, il seguente criterio AssegnaMessage utilizza la variabile impostata in RaiseFault per impostare un'intestazione nella risposta all'errore:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignVariable> nel criterio RaiseFault utilizza la stessa sintassi dell'elemento <AssignVariable> nel criterioAssignMessage.

Elemento <FaultResponse><Add>/<Headers>

Aggiunge intestazioni HTTP al messaggio di errore. Tieni presente che l'intestazione vuota <Add><Headers/></Add> non aggiunge alcuna intestazione. Questo esempio copia il valore della variabile di flusso request.user.agent nell'intestazione.

L'elemento <Header> supporta la funzionalità di sostituzione delle stringhe dinamica chiamata modelli dei messaggi.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Predefinita:	N/A
Presenza:	Facoltativo
Tipo:	String

Elemento <FaultResponse><Copy>

Copia le informazioni dal messaggio specificato dall'attributo source a il messaggio di errore.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

Predefinita:	N/A
Presenza:	Facoltativo
Tipo:	String

Attributi

 <Copy source="response">

Attributo	Descrizione	Presenza	Tipo
source	Specifica l'oggetto di origine della copia. Se l'elemento source non viene specificato, viene considerato come un messaggio semplice. Ad esempio, se il criterio si trova nel flusso di richiesta, l'origine utilizza per impostazione predefinita l'oggetto request. Se il criterio è nel flusso di risposta, per impostazione predefinita viene usato l'oggetto response. Se ometti source, puoi utilizzare un riferimento assoluto a una variabile di flusso come origine della copia. Ad esempio, specifica il valore come {request.header.user-agent}. Se la variabile di origine non può essere risolta o si risolve in un tipo non messaggio, <Copy> non risponde.	Facoltativo	String

Attributo

Descrizione

Presenza

Tipo

source

Specifica l'oggetto di origine della copia.

Se l'elemento source non viene specificato, viene considerato come un messaggio semplice. Ad esempio, se il criterio si trova nel flusso di richiesta, l'origine utilizza per impostazione predefinita l'oggetto request. Se il criterio è nel flusso di risposta, per impostazione predefinita viene usato l'oggetto response. Se ometti source, puoi utilizzare un riferimento assoluto a una variabile di flusso come origine della copia. Ad esempio, specifica il valore come {request.header.user-agent}.
Se la variabile di origine non può essere risolta o si risolve in un tipo non messaggio, <Copy> non risponde.

Facoltativo

String

<FaultResponse><Copy>/<Headers>

Copia l'intestazione HTTP specificata dall'origine nel messaggio di errore. Per copiare tutte le intestazioni, specifica <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

Se esistono più intestazioni con lo stesso nome, utilizza la seguente sintassi:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

In questo esempio vengono copiati "h1", "h2" e il secondo valore di "h3". Se "h3" ha un solo valore, il valore non viene copiato.

Predefinita:	N/A
Presenza:	Facoltativo
Tipo:	String

Elemento <FaultResponse><Copy>/<StatusCode>

Il codice di stato HTTP da copiare dall'oggetto specificato dall'attributo source al messaggio di errore.

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Predefinita:	false
Presenza:	Facoltativo
Tipo:	String

Elemento <FaultResponse><Remove>/<Headers>

Rimuove le intestazioni HTTP specificate dal messaggio di errore. Per rimuovere tutte le intestazioni, specifica <Remove><Headers/></Remove>. Questo esempio rimuove l'intestazione user-agent dal messaggio.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

Se esistono più intestazioni con lo stesso nome, utilizza la seguente sintassi:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

Questo esempio rimuove "h1", "h2" e il secondo valore di "h3". Se "h3" ha un solo valore, questo non viene rimosso.

Predefinita:	N/A
Presenza:	Facoltativo
Tipo:	String

Elemento <FaultResponse><Set>

Imposta le informazioni nel messaggio di errore.

Gli elementi secondari di <Set> supportano la funzionalità di sostituzione dinamica delle stringhe chiamata modelli di messaggi.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </Set>

Predefinita:	N/A
Presenza:	Facoltativo
Tipo:	N/A

Elemento <FaultResponse>/<Set>/<Headers>

Imposta o sovrascrive le intestazioni HTTP nel messaggio di errore. Tieni presente che l'intestazione vuota <Set><Headers/></Set> non imposta nessuna intestazione. Questo esempio imposta l'intestazione user-agent sulla variabile del messaggio specificata con l'elemento <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Predefinita:	N/A
Presenza:	Facoltativo
Tipo:	String

Elemento <FaultResponse>/<Set>/<Payload>

Imposta il payload del messaggio di errore.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Imposta un payload JSON:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

In un payload JSON, puoi inserire variabili utilizzando gli attributi variablePrefix e variableSuffix con caratteri di delimitatore, come mostrato nell'esempio seguente.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

oppure, a partire dalla release 16.08.17 di Cloud, puoi anche utilizzare le parentesi graffe per inserire le variabili:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Imposta un payload misto in XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Predefinita:
Presenza:	Facoltativo
Tipo:	String

Attributi

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

Attributo	Descrizione	Presenza	Tipo
contentType	Se contentType è specificato, il suo valore viene assegnato all'intestazione `Content-Type`.	Facoltativo	String
variablePrefix	Facoltativamente, specifica il delimitatore iniziale su una variabile di flusso perché i payload JSON non possono utilizzare il carattere "{" predefinito.	Facoltativo	Carattere
variableSuffix	Facoltativamente, specifica il delimitatore finale su una variabile di flusso perché i payload JSON non possono utilizzare il carattere predefinito "}".	Facoltativo	Carattere

Elemento <FaultResponse>/<Set>/<StatusCode>

Imposta il codice di stato della risposta.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Predefinita:	false
Presenza:	Facoltativo
Tipo:	Booleano

Elemento <ShortFaultReason>

Specifica di visualizzare un motivo di errore breve nella risposta:

<ShortFaultReason>true|false</ShortFaultReason>

Per impostazione predefinita, il motivo dell'errore nella risposta al criterio è:

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Per rendere il messaggio più leggibile, puoi impostare l'elemento <ShortFaultReason> su true per accorciare faultstring in base al nome del criterio:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Valori validi: true/false(valore predefinito).

Predefinita:	false
Presenza:	Facoltativo
Tipo:	Booleano

Variabili di flusso

Le variabili di flusso consentono il comportamento dinamico di criteri e flussi in fase di runtime, in base a intestazioni HTTP, contenuto del messaggio o contesto del flusso. Le seguenti variabili di flusso predefinite sono disponibili dopo l'esecuzione di un criterio RaiseFault. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento per le variabili.

Variabile	Tipo	Autorizzazione	Descrizione
fault.name	String	Sola lettura	Quando viene eseguito il criterio RaiseFault, questa variabile è sempre impostata sulla stringa `RaiseFault`.
fault.type	String	Sola lettura	Restituisce il tipo di errore presente nell'errore e, se non disponibile, una stringa vuota.
fault.category	String	Sola lettura	Restituisce la categoria dell'errore e, se non è disponibile, una stringa vuota.

Esempio di utilizzo di RaiseFault

L'esempio seguente utilizza una condizione per imporre la presenza di un elemento queryparam con il nome zipcode sulla richiesta in entrata. Se queryparam non è presente, il flusso genererà un errore tramite RaiseFault:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

Di seguito viene illustrato come sarebbe in RaiseFault:

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
    </Set>
  </FaultResponse>
</RaiseFault>

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore	Stato HTTP	Causa
`steps.raisefault.RaiseFault`	`500`	Vedi stringa di errore.

Errori di deployment

Nessuno.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la pagina Cosa devi sapere sugli errori relativi ai criteri.

Variabili	Dove	Esempio
`fault.name="fault_name"`	`fault_name` è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome dell'errore è l'ultima parte del codice di errore.	`fault.name = "RaiseFault"`
`raisefault.policy_name.failed`	`policy_name` è il nome specificato dall'utente del criterio che ha generato l'errore.	`raisefault.RF-ThrowError.failed = true`

Esempio di risposta di errore

Nota: per la gestione degli errori, la best practice consiste nell'eseguire il trap della parte errorcode della risposta di errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Schema

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, su GitHub sono disponibili gli schemi dei criteri.

Argomenti correlati

Consulta la sezione Gestione degli errori.