Questa pagina è stata tradotta dall'API Cloud Translation.

Norme di MonetizationLimitsCheck

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Le norme di MonetizationLimitsCheck ti consentono di applicare i limiti di monetizzazione.

Nello specifico, le norme vengono attivate se lo sviluppatore di app che accede all'API monetizzata non ha acquistato un abbonamento al prodotto API associato o se il saldo non è sufficiente. In questo caso, le norme MonetizationLimitsCheck genereranno un errore e bloccheranno una chiamata API. Per maggiori informazioni, consulta la sezione Applicazione di abbonamenti degli sviluppatori a prodotti basati su 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.

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

`<MonetizationLimitsCheck>`

Definisce le norme MonetizationLimitsCheck.

Valore predefinito	N/A
Obbligatorio?	Obbligatorio
Tipo	Tipo complesso
Elemento principale	N/A
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 un 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/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

In questa sezione vengono descritti gli elementi secondari di <MonetizationLimitsCheck>.

`<DisplayName>`

Utilizzalo in aggiunta 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/A
Obbligatorio?	Facoltativo. Se ometti `<DisplayName>`, viene utilizzato il valore dell'attributo `name` del criterio.
Tipo	Stringa
Elemento principale	<`PolicyElement`>
Elementi secondari	Nessuna esperienza

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/A
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, viene creata da AssignVariable.

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

Ad esempio, utilizza il seguente codice per impostare la variabile denominata myFaultVar nelle norme 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 AttributionMessage 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> nelle norme MonetizationLimitsCheck utilizza la stessa sintassi dell'elemento <AssignVariable> nelle norme AttributionMessage.

`<Name>`

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

Valore predefinito	N/A
Obbligatorio?	Facoltativo
Tipo	String
Elemento principale	`<AssignVariable>`
Elementi secondari	Nessuna

`<Value>`

Valore variabile. Per ulteriori informazioni, consulta l'elemento Value nel criterio AttributionMessage.

Valore predefinito	N/A
Obbligatorio?	Facoltativo
Tipo	String
Elemento principale	`<AssignVariable>`
Elementi secondari	Nessuna

`<Add>`

Aggiunge intestazioni HTTP al messaggio di errore.

Valore predefinito	N/A
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/A
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	`<Add>` `<Copy>` `<Remove>` `<Set>`
Elementi secondari	Nessuna

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

Nell'esempio seguente viene copiato headerA dalla richiesta:

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

Copia intestazione - 2

Nell'esempio seguente vengono copiate più intestazioni:

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

In questo esempio viene copiato "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 nel messaggio di errore.

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

La tabella seguente descrive gli attributi di <Copy>:

Attributo	Obbligatorio?	Tipo	Descrizione
source	Facoltativo	String	Specifica l'oggetto di origine della copia. Se l'origine non è specificata, viene considerata come un semplice messaggio. Ad esempio, se il criterio si trova nel flusso di richiesta, l'origine per impostazione predefinita utilizzerà l'oggetto request. Se il criterio si trova nel flusso di risposta, per impostazione predefinita viene utilizzato 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 se si risolve in un tipo non messaggio, <Copy> non risponde.

Attributo

Obbligatorio?

Tipo

Descrizione

source

Facoltativo

String

Specifica l'oggetto di origine della copia.

Se l'origine non è specificata, viene considerata come un semplice messaggio. Ad esempio, se il criterio si trova nel flusso di richiesta, l'origine per impostazione predefinita utilizzerà l'oggetto request. Se il criterio si trova nel flusso di risposta, per impostazione predefinita viene utilizzato 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 se si risolve in un tipo non messaggio, <Copy> non risponde.

`<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/A
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	`<Copy>` `<Set>`
Elementi secondari	Nessuna

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/A
Obbligatorio?	Facoltativo
Tipo	Tipo complesso
Elemento principale	`<FaultResponse>`
Elementi secondari	`<Headers>`

`<Set>`

Imposta le informazioni nel messaggio di errore.

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

`<Payload>`

Imposta il payload del messaggio di errore.

Valore predefinito	N/A
Obbligatorio?	Facoltativo
Tipo	String
Elemento principale	`<Set>`
Elementi secondari	Nessuna

Esempi:

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

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

Imposta payload JSON - 3

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

In questo esempio vengono inserite variabili utilizzando parentesi graffe. Puoi utilizzare parentesi graffe a partire dalla versione 16.08.17.

Imposta payload XML

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

In questo esempio vengono inserite variabili utilizzando parentesi graffe. Puoi utilizzare parentesi graffe a partire dalla versione 16.08.17.

`<IgnoreUnresolvedVariables>`

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

Imposta il valore 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 su true di <MonetizationLimitsCheck>. 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

Nell'esempio seguente viene impostato il valore <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 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 trovata una sottoscrizione 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`	Ora di fine dell'abbonamento al prodotto API.
`mint.subscription_start_time_ms`	Ora di inizio dell'abbonamento al prodotto API. Ad esempio: `1618433956209`.