Questa pagina è stata tradotta dall'API Cloud Translation.

Norme relative a MonetizationLimitsCheck

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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 suo saldo è insufficiente. In questo caso, il criterio MonetizationLimitsCheck genererà un errore e bloccherà una chiamata API. Per ulteriori informazioni, consulta la sezione Imposizione di 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 compilate, come descritto nel riferimento alla variabile di flusso mint.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

`<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 qualsiasi errore di variabile non risolto 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 l'abbonamento al prodotto API associato, l'accesso all'API monetizzata viene bloccato e viene restituito uno 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 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>

Una policy in una regola di errore può quindi accedere alla variabile. Ad esempio, la seguente policy AssignMessage utilizza la variabile per impostare un'intestazione nella risposta di 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> nella norma MonetizationLimitsCheck utilizza la stessa sintassi dell'elemento <AssignVariable> nella norma 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 Value nelle norme 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

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 del 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 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>

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

`<Copy>`

Copia le informazioni da il messaggio specificato dall'attributo source a il 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 la policy si trova nel flusso di richieste, l'origine viene impostata per impostazione predefinita sull'oggetto richiesta. Se il criterio è nel 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 viene risolta in un tipo non di messaggio, <Copy> non riesce a rispondere.

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 la policy si trova nel flusso di richieste, l'origine viene impostata per impostazione predefinita sull'oggetto richiesta. Se il criterio è nel 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 viene risolta in un tipo non di messaggio, <Copy> non riesce a rispondere.

`<StatusCode>`

Specifica il codice di stato HTTP nel messaggio di errore. Puoi copiare o impostare il valore da 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 payload testo

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

Imposta 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>

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

Imposta 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 17/08/2016.

Imposta 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 17/08/2016.

`<IgnoreUnresolvedVariables>`

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

Imposta true per ignorare le variabili non risolte e continuare l'elaborazione; altrimenti false. Il valore predefinito è true.

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

L'elemento <IgnoreUnresolvedVariables> utilizza la seguente sintassi:

Sintassi

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

Esempio

L'esempio seguente imposta <IgnoreUnresolvedVariables> su false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Codici di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`mint.service.subscription_not_found_for_developer`	`500`	This error occurs when a developer does not have a subscription to the API Product.
`mint.service.wallet_not_found_for_developer`	`500`	This error occurs when a prepaid developer attempts to consume a monetized API without maintaining a wallet for the currency specified in rate plan.
`mint.service.developer_usage_exceeds_balance`	`500`	This error occurs when a prepaid developer's usage exceeds the wallet balance.
`mint.service.wallet_blocked_due_to_inactivity`	`500`	This error occurs when a prepaid developer's wallet is not topped up in over 1.5 years and the developer attempts to consume an API.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

Variables	Where	Example
`fault.name`	The `fault.name` can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`MonetizationLimitsCheck.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`MonetizationLimitsCheck.monetization-limits-check-1.failed = true`

For more information about policy errors, see What you need to know about policy errors

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate automaticamente quando viene eseguita la policy 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. Possono essere restituiti i seguenti valori: `limits_check_success` - Verifica dei limiti riuscita. `apiproduct_name_and_developer_email_not_available` - Impossibile determinare lo sviluppatore dell'API o il nome del prodotto API per eseguire il controllo dei limiti. `apiproduct_name_not_available` - Impossibile determinare il nome del prodotto API per eseguire il controllo dei limiti. `developer_email_not_available` - Impossibile determinare l'email dello sviluppatore API per eseguire il controllo dei limiti. `developer_usage_exceeds_balance` - Il saldo prepagato dello sviluppatore è troppo basso. `rateplan_not_available` - Prodotto API senza piano tariffario, nessun errore. `subscription_not_available` - API developer that owns the app does not have a subscription. `wallet_disabled_due_to_inactivity` - Lo sviluppatore non ha utilizzato il proprio wallet per più di un anno. Una ricarica di almeno un'unità (pari a 0, 01 $se espresso in dollari) riattiverà il piano. `wallet_not_found`: lo sviluppatore non ha un portafoglio. Ciò può accadere quando non è stata eseguita alcuna ricarica per lo sviluppatore.
`mint.subscription_end_time_ms`	Data/ora di fine dell'abbonamento al prodotto API.
`mint.subscription_start_time_ms`	Ora di inizio dell'abbonamento al prodotto API. Ad esempio: `1618433956209`.

Norme relative a MonetizationLimitsCheck Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

<MonetizationLimitsCheck>

Sintassi

Esempio

Riferimento all'elemento secondario

<DisplayName>

Sintassi

Esempio

<FaultResponse>

<AssignVariable>

<Name>

<Value>

<Add>

<Headers>

Aggiungi intestazione

Imposta intestazione

Copia intestazione - 1

Copia intestazione - 2

Rimuovi intestazione - 1

Rimuovi intestazione - 2

<Copy>

<StatusCode>

Copia codice di stato

Imposta codice di stato

<Remove>

<Set>

<Payload>

Imposta payload testo

Imposta payload JSON - 1

Imposta payload JSON - 2

Imposta payload JSON - 3

Imposta payload XML

<IgnoreUnresolvedVariables>

Sintassi

Esempio

Codici di errore

Runtime errors

Fault variables

Variabili di flusso

Norme relative a MonetizationLimitsCheck

`<MonetizationLimitsCheck>`

`<DisplayName>`

`<FaultResponse>`

`<AssignVariable>`

`<Name>`

`<Value>`

`<Add>`

`<Headers>`

`<Copy>`

`<StatusCode>`

`<Remove>`

`<Set>`

`<Payload>`

`<IgnoreUnresolvedVariables>`