Norme relative a MonetizationLimitsCheck

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Nota: il criterio MonetizationLimitsCheck è valido solo se hai attivato la monetizzazione di Apigee nella tua organizzazione.

Panoramica

Il criterio MonetizationLimitsCheck ti consente di applicare i limiti di monetizzazione.

Nello specifico, il criterio viene attivato se lo sviluppatore di app che accede all'API monetizzata non ha acquistato un abbonamento al prodotto API associato o se il saldo dello sviluppatore non è sufficiente. In questo caso, il criterio MonetizationLimitsCheck genererà un errore e bloccherà una chiamata all'API. Per ulteriori informazioni, consulta Applicare gli abbonamenti degli sviluppatori ai prodotti API.

Quando colleghi il criterio MonetizationLimitsCheck a un proxy API, le variabili di flusso mint.limitscheck.* e mint.subscription_* vengono completate, come descritto nella documentazione di riferimento della variabile di flusso mint.

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Nota: nonostante l'utilizzo del criterio MonetizationLimitsCheck, è possibile che a uno sviluppatore con pagamento anticipato venga consentito di effettuare chiamate API in eccesso e che lo sviluppatore possa ritrovarsi con un saldo del portafoglio negativo. Per comprendere le condizioni in cui il saldo di uno sviluppatore diventa negativo, consulta Saldo dello sviluppatore negativo.

<MonetizationLimitsCheck>

Definisce il criterio MonetizationLimitsCheck.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Tipo complesso
Elemento principale	N/D
Elementi secondari	<DisplayName> <FaultResponse> <IgnoreUnresolvedVariables>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <MonetizationLimitsCheck>:

Elemento secondario	Obbligatorio?	Descrizione
<DisplayName>	Facoltativo	Un nome personalizzato per il criterio.
<FaultResponse>	Facoltativo	Definisce il messaggio di risposta restituito al client richiedente.
<IgnoreUnresolvedVariables>	Facoltativo	Ignora eventuali errori di variabili irrisolti nel flusso.

La sintassi dell'elemento <MonetizationLimitsCheck> è la seguente:

Sintassi

<?xml version="1.0" encoding="UTF-8" standalone="no"?><MonetizationLimitsCheck continueOnError="[true|false]" enabled="[true|false]" name="policy_name">
   <DisplayName>POLICY_DISPLAY_NAME</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>VALUE</IgnoreUnresolvedVariables>
</MonetizationLimitsCheck>

Esempio

Nell'esempio seguente, se uno sviluppatore non ha acquistato un abbonamento al prodotto API associato, l'accesso all'API monetizzata viene bloccato e viene restituito lo stato 403 con un messaggio personalizzato.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">
  <DisplayName>Monetization-Limits-Check-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="text/xml">
        <error>
          <messages>
            <message>Usage has been exceeded ({mint.limitscheck.isRequestBlocked}) or app developer has been suspended</message>
          </messages>
        </error>
      </Payload>
      <StatusCode>403</StatusCode>
    </Set>
  </FaultResponse>
</MonetizationLimitsCheck>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
enabled	true	Facoltativo	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async	falso	Ritirato	Questo attributo è stato ritirato.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <MonetizationLimitsCheck>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito	N/D
Obbligatorio?	Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<FaultResponse>

Definisce il messaggio di risposta restituito al client richiedente. FaultResponse utilizza le stesse impostazioni dell'elemento <FaultResponse> nel criterio RaiseFault.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<MonetizationLimitsCheck>
Elementi secondari	<AssignVariable> <Add> <Copy> <Remove> <Set>

<AssignVariable>

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

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<FaultResponse>
Elementi secondari	<Name> <Value>

Ad esempio, utilizza il seguente codice per impostare la variabile denominata myFaultVar nella norma MonetizationLimitsCheck:

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

Un criterio in una regola di errore può quindi accedere alla variabile. Ad esempio, il seguente criterio AssignMessage utilizza la variabile 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>
<AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> nel criterio MonetizationLimitsCheck utilizza la stessa sintassi dell'elemento <AssignVariable> nel criterio AssignMessage.

<Name>

Nome della variabile. Per ulteriori informazioni, consulta l'elemento Name nel criterio AssignMessage.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<AssignVariable>
Elementi secondari	Nessuno

<Value>

Valore della variabile. Per ulteriori informazioni, consulta l'elemento Valore nel criterio AssignMessage.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<AssignVariable>
Elementi secondari	Nessuno

<Add>

Aggiunge intestazioni HTTP al messaggio di errore.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<FaultResponse>
Elementi secondari	<Headers>

<Headers>

Specifica l'intestazione HTTP da aggiungere, impostare, copiare o rimuovere.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<Add> <Copy> <Remove> <Set>
Elementi secondari	Nessuno

• Un'intestazione vuota (<Add><Headers/></Add>) non aggiunge alcuna intestazione.
• L'elemento <Header> supporta la funzionalità di sostituzione dinamica delle stringhe chiamata modello di messaggio.

Esempi:

Aggiungi intestazione

L'esempio seguente copia il valore della variabile di flusso request.user.agent nell'intestazione:

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

Imposta intestazione

L'esempio seguente imposta l'intestazione user-agent sulla variabile messaggio specificata con l'elemento <AssignTo>.

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

Intestazione copia - 1

L'esempio seguente copia il headerA dalla richiesta:

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

Copia intestazione - 2

L'esempio seguente copia più intestazioni:

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

Questo esempio copia "h1", "h2" e il secondo valore di "h3". Se "h3" ha un solo valore, "h3" non viene copiato.

Rimuovi intestazione - 1

L'esempio seguente rimuove un'intestazione:

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

Rimuovi intestazione - 2

L'esempio seguente rimuove più intestazioni:

<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, "h3" non viene rimosso.

<Copy>

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

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<FaultResponse>
Elementi secondari	<Headers> <StatusCode>

La tabella seguente descrive gli attributi di <Copy>:

Attributo	Obbligatorio?	Tipo	Descrizione
origine	Facoltativo	Stringa	Specifica l'oggetto di origine della copia. Se source non è specificato, viene trattato come un semplice messaggio. Ad esempio, se il criterio si trova nel flusso di richiesta, l'origine predefinita è l'oggetto request. Se il criterio è nel relativo flusso di risposta, il valore predefinito è 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 diverso da messaggio, <Copia> non risponde.

<StatusCode>

Specifica il codice di stato HTTP nel messaggio di errore. Puoi copiare o impostare il valore per l'oggetto specificato dall'attributo source.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<Copy> <Set>
Elementi secondari	Nessuno

Esempio:

Copia codice stato

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

Imposta codice di stato

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

<Remove>

Rimuove le intestazioni HTTP specificate dal messaggio di errore. Per rimuovere tutte le intestazioni, specifica <Remove><Headers/></Remove>.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<FaultResponse>
Elementi secondari	<Headers>

<Set>

Imposta le informazioni nel messaggio di errore.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	<FaultResponse>
Elementi secondari	<Headers> <Payload> <StatusCode>

<Payload>

Imposta il payload del messaggio di errore.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<Set>
Elementi secondari	Nessuno

Esempi:

Imposta il payload di testo

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

Imposta il payload JSON - 1

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

Imposta il payload JSON - 2

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

Questo esempio inserisce le variabili utilizzando gli attributi variablePrefix e variableSuffix con caratteri delimitatori.

Imposta il payload JSON - 3

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

Questo esempio inserisce le variabili utilizzando le parentesi graffe. Puoi utilizzare le parentesi graffe a partire dalla release del 16/08/17.

Imposta il payload XML

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

Questo esempio inserisce le variabili utilizzando le parentesi graffe. Puoi utilizzare le parentesi graffe a partire dalla release del 16/08/17.

<IgnoreUnresolvedVariables>

Determina se l'elaborazione si interrompe quando viene rilevata una variabile non risolta.

Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione; in caso contrario, false. Il valore predefinito è true.

L'impostazione di <IgnoreUnresolvedVariables> su true è diversa dall'impostazione di continueOnError di <MonetizationLimitsCheck> su true. Se imposti continueOnError su true, Apigee ignora tutti gli errori, non solo quelli nelle variabili.

La sintassi dell'elemento <IgnoreUnresolvedVariables> è la seguente:

Sintassi

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

Esempio

Nell'esempio seguente, <IgnoreUnresolvedVariables> viene impostato su false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Codici di errore

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

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto	Stato HTTP	Causa
mint.service.subscription_not_found_for_developer	500	Questo errore si verifica quando uno sviluppatore non dispone di un abbonamento al prodotto API.
mint.service.wallet_not_found_for_developer	500	Questo errore si verifica quando uno sviluppatore con pagamento anticipato tenta di utilizzare un'API monetizzata senza gestire un portafoglio per la valuta specificata nel piano tariffario.
mint.service.developer_usage_exceeds_balance	500	Questo errore si verifica quando l'utilizzo di uno sviluppatore con pagamento anticipato supera il saldo del portafoglio.
mint.service.wallet_blocked_due_to_inactivity	500	Questo errore si verifica quando il portafoglio di uno sviluppatore con pagamento anticipato non viene ricaricato da più di 1,5 anni e lo sviluppatore tenta di utilizzare un'API.

Variabili di errore

Ogni volta che si verificano errori di esecuzione in un criterio, Apigee genera messaggi di errore. Puoi visualizzare questi messaggi di errore nella risposta di errore. Spesso i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del tuo prodotto. Ti consigliamo di personalizzare i messaggi di errore in base al tipo di errore per renderli più significativi.

Per personalizzare i messaggi di errore, puoi utilizzare le regole di errore o il criterio RaiseFault. Per informazioni sulle differenze tra le regole di errore e il criterio RaiseFault, consulta Regole di errore e criterio RaiseFault. Devi verificare la presenza di condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio RaiseFault. Apigee fornisce variabili di errore univoche per ogni criterio e i valori delle variabili di errore vengono impostati quando un criterio attiva errori di runtime. Utilizzando queste variabili, puoi verificare la presenza di condizioni di errore specifiche e intraprendere le azioni appropriate. Per ulteriori informazioni su come controllare le condizioni di errore, consulta Condizioni di compilazione.

Variabili	Dove	Esempio
fault.name	fault.name può corrispondere a uno dei problemi elencati nella tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice dell'errore.	fault.name Matches "UnresolvedVariable"
MonetizationLimitsCheck.POLICY_NAME.failed	POLICY_NAME è il nome specificato dall'utente del criterio che ha generato l'errore.	MonetizationLimitsCheck.monetization-limits-check-1.failed = true

Per ulteriori informazioni sugli errori relativi alle norme, consulta Informazioni importanti sugli errori relativi alle norme

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono completate automaticamente quando viene eseguita la norma MonetizationLimitsCheck. Per ulteriori informazioni, consulta le variabili di flusso mint.

Variabile di flusso	Descrizione
mint.limitscheck.is_request_blocked	true per le richieste bloccate.
mint.limitscheck.is_subscription_found	true se viene trovato un abbonamento API.
mint.limitscheck.purchased_product_name	Nome del prodotto API acquistato. Ad esempio: MyProduct.
mint.limitscheck.status_message	Messaggio di stato. Ad esempio: limits_check_success.
mint.subscription_end_time_ms	Data e ora di fine dell'abbonamento al prodotto API.
mint.subscription_start_time_ms	Data/ora di inizio dell'abbonamento al prodotto API. Ad esempio: 1618433956209.