Norme relative a MonetizationLimitsCheck

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza la documentazione di Apigee Edge.

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

Panoramica

Le norme MonetizationLimitsCheck ti consentono 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, la norma MonetizationLimitsCheck segnala un errore e bloccherà una chiamata 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 norme e le implicazioni sull'utilizzo, consulta Tipi di criteri.

Nota: nonostante l'uso delle norme MonetizationLimitsCheck, è possibile che uno sviluppatore prepagato possa effettuare chiamate API in eccesso con conseguente rischio con un saldo di Wallet 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 relativi alle variabili non risolte nel flusso.

L'elemento <MonetizationLimitsCheck> utilizza la seguente sintassi:

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/A	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. Facoltativamente, 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 in caso di errore del criterio. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (su continueOnError) Gestione degli errori nel 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	Deprecato	Questo attributo è stato ritirato.

Riferimento 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 di flusso di destinazione. Se la variabile di 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 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 la sezione Valore nel criterioAssignMessage.

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 delle stringhe dinamiche chiamata modelli di messaggio.

Esempi:

Aggiungi intestazione

Nell'esempio seguente, il valore della variabile di flusso request.user.agent viene copiato 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>

Copia intestazione - 1

L'esempio seguente copia il headerA dalla richiesta:

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

Copia intestazione - 2

Il seguente esempio copia più intestazioni:

<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, poi "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 seguito da "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>

Nella tabella seguente vengono descritti gli attributi di <Copy>:

Attributo	Obbligatorio?	Tipo	Descrizione
origine	Facoltativo	Stringa	Specifica l'oggetto di origine della copia. Se l'origine non è specificato, viene considerato un messaggio semplice. Ad esempio, se il criterio si trova nel nel flusso di richieste, l'origine usa per impostazione predefinita l'oggetto request. Se il criterio è in flusso di risposta, per impostazione predefinita viene utilizzato l'oggetto response. Se ometti source, puoi utilizzare una riferimento assoluto a una variabile di flusso come origine della copia. Ad esempio, specifica il valore {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 di 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 payload JSON - 2

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

In questo esempio vengono inserite variabili utilizzando gli attributi variablePrefix e Attributi variableSuffix con caratteri di delimitazione.

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. altrimenti false. Il valore predefinito è true.

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

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

Sintassi

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

Esempio

L'esempio seguente imposta <IgnoreUnresolvedVariables> su false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Codici di errore

Questa sezione descrive i codici e i messaggi di errore che vengono 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
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 prepagato tenta di utilizzare un'API monetizzata senza mantenere 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 prepagato supera il saldo di Wallet.
mint.service.wallet_blocked_due_to_inactivity	500	Questo errore si verifica quando il portafoglio di uno sviluppatore prepagato 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. Molte volte, i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del prodotto. Per rendere i messaggi più significativi, potresti voler personalizzare i messaggi in base al tipo di errore.

Per personalizzare i messaggi di errore, puoi utilizzare regole di errore o il criterio AlzaFault. Per informazioni sulle differenze tra le regole di errore e il criterio RaiseFault, consulta FaultRules e il criterio AlzaFault. Devi verificare le condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio AlzaFault. Apigee fornisce variabili di errore univoche per ciascun criterio e i relativi valori vengono impostati quando un criterio attiva gli errori di runtime. Utilizzando queste variabili, puoi verificare le condizioni di errore specifiche e intraprendere le azioni appropriate. Per saperne di più sul controllo delle condizioni di errore, consulta Condizioni di costruzione.

Variabili	Dove	Esempio
fault.name	fault.name può corrispondere a qualsiasi errore elencato nella tabella Errori di runtime. Il nome del guasto è l'ultima parte del codice di 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 ai criteri, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate automaticamente quando 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.