Cette page a été traduite par l'API Cloud Translation.

Règle MonétisationLimitsCheck

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Présentation

La règle MonetizationLimitsCheck vous permet d'appliquer des limites de monétisation.

Plus précisément, la règle est déclenchée si le développeur de l'application accédant à l'API monétisée n'a pas souscrit d'abonnement au produit d'API associé ou si le solde du développeur est insuffisant. Dans ce cas, la règle MonetizationLimitsCheck génère une erreur et bloque un appel d'API. Pour plus d'informations, consultez la section Appliquer des abonnements développeurs aux produits d'API.

Lorsque vous associez la règle MonetizationLimitsCheck à un proxy d'API, les variables de flux mint.limitscheck.* et mint.subscription_* sont renseignées, comme décrit dans la documentation de référence sur les variables de flux mint.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

`<MonetizationLimitsCheck>`

Définit la règle MonetizationLimitsCheck

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Type complexe
Élément parent	ND
Éléments enfants	`<DisplayName>` `<FaultResponse>` `<IgnoreUnresolvedVariables>`

Le tableau suivant fournit une description détaillée des éléments enfants de <MonetizationLimitsCheck> :

Élément enfant	Obligatoire ?	Description
`<DisplayName>`	Facultatif	Nom personnalisé de la règle.
`<FaultResponse>`	Facultatif	Définit le message de réponse renvoyé au client à l'origine de la requête.
`<IgnoreUnresolvedVariables>`	Facultatif	Ignore toutes les erreurs de variable non résolues dans le flux.

L'élément <MonetizationLimitsCheck> utilise la syntaxe suivante :

Syntaxe

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

Exemple

Dans l'exemple suivant, si un développeur n'a pas acheté d'abonnement au produit d'API associé, l'accès à l'API monétisée est bloqué et un état 403 est renvoyé avec un message personnalisé.

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

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
`name`	ND	Obligatoire	Nom interne de la règle. La valeur de l'attribut `name` peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément `<DisplayName>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
`continueOnError`	faux	Facultatif	Définissez sur `false` pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur `true` pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
`enabled`	true	Facultatif	Définissez sur `true` pour appliquer la règle. Définissez sur `false` pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
`async`	faux	Obsolète	Cet attribut est obsolète.

Référence d'élément enfant

Cette section décrit les éléments enfants de <MonetizationLimitsCheck>.

`<DisplayName>`

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	N/A
Obligatoire ?	Facultatif. Si vous omettez `<DisplayName>`, la valeur de l'attribut `name` de la règle est utilisée.
Type	Chaîne
Élément parent	<`PolicyElement`>
Éléments enfants	Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

`<FaultResponse>`

Définit le message de réponse renvoyé au client à l'origine de la requête. FaultResponse utilise les mêmes paramètres que l'élément <FaultResponse> dans la stratégie RaiseFault.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<MonetizationLimitsCheck>`
Éléments enfants	`<AssignVariable>` `<Add>` `<Copy>` `<Remove>` `<Set>`

`<AssignVariable>`

Attribue une valeur à une variable de flux de destination. Si la variable de flux n'existe pas, AssignVariable la crée.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<FaultResponse>`
Éléments enfants	`<Name>` `<Value>`

Par exemple, utilisez le code suivant pour définir la variable nommée myFaultVar dans la règle MonetizationLimitsCheck :

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

Une règle dans une règle d'erreur peut ensuite accéder à la variable. Par exemple, la règle d'attribution de message suivante utilise la variable pour définir un en-tête dans la réponse d'erreur :

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

L'élément <AssignVariable> de la règle MonetizationLimitsCheck utilise la même syntaxe que l'élément <AssignVariable> de la règle AssignMessage.

`<Name>`

Nom de la variable. Pour en savoir plus, consultez l'élément Name (Nom) dans la stratégie AssignMessage.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	`<AssignVariable>`
Éléments enfants	Aucun

`<Value>`

Valeur de la variable. Pour en savoir plus, consultez l'élément Value (Valeur) dans la stratégie AssignMessage.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	`<AssignVariable>`
Éléments enfants	Aucun

`<Add>`

Ajoute des en-têtes HTTP au message d'erreur.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<FaultResponse>`
Éléments enfants	`<Headers>`

`<Headers>`

Spécifie l'en-tête HTTP à ajouter, définir, copier ou supprimer.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<Add>` `<Copy>` `<Remove>` `<Set>`
Éléments enfants	Aucun

Exemples :

Ajouter un en-tête

L'exemple suivant copie la valeur de la variable de flux request.user.agent dans l'en-tête :

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

Définir l'entête

L'exemple suivant définit l'en-tête user-agent sur la variable de message spécifiée avec l'élément <AssignTo>.

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

Copier l'en-tête - 1

L'exemple suivant copie la valeur headerA de la requête :

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

Copier l'en-tête - 2

L'exemple suivant copie plusieurs en-têtes :

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

Cet exemple copie "h1", "h2" et la deuxième valeur de "h3". Si "h3" n'a qu'une seule valeur, le paramètre "h3" n'est pas copié.

Supprimer l'en-tête - 1

L'exemple suivant supprime un en-tête :

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

Supprimer l'en-tête - 2

L'exemple suivant permet de supprimer plusieurs en-têtes :

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

Cet exemple supprime "h1", "h2" et la deuxième valeur de "h3". Si "h3" n'a qu'une seule valeur, le paramètre "h3" n'est pas supprimé.

`<Copy>`

Copie les informations depuis le message spécifié par l'attribut source vers le message d'erreur.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<FaultResponse>`
Éléments enfants	`<Headers>` `<StatusCode>`

Le tableau suivant décrit les attributs de <Copy> :

Attribut	Obligatoire ?	Type	Description
source	Facultatif	Chaîne	Spécifie l'objet source de la copie. Si la source n'est pas spécifiée, l'objet est traité comme un message simple. Par exemple, si la règle se trouve dans le flux de requête, la source est définie par défaut sur l'objet de requête. Si la règle se trouve dans le flux de réponse, elle utilise par défaut l'objet de réponse. Si vous omettez la source, vous pouvez utiliser une référence absolue à une variable de flux en tant que source de la copie. Par exemple, spécifiez la valeur en tant que {request.header.user-agent}. Si la variable source ne peut pas être résolue ou est associée à un type qui n'est pas un message, <Copy> ne répond pas.

Attribut

Obligatoire ?

Type

Description

source

Facultatif

Chaîne

Spécifie l'objet source de la copie.

Si la source n'est pas spécifiée, l'objet est traité comme un message simple. Par exemple, si la règle se trouve dans le flux de requête, la source est définie par défaut sur l'objet de requête. Si la règle se trouve dans le flux de réponse, elle utilise par défaut l'objet de réponse. Si vous omettez la source, vous pouvez utiliser une référence absolue à une variable de flux en tant que source de la copie. Par exemple, spécifiez la valeur en tant que {request.header.user-agent}.
Si la variable source ne peut pas être résolue ou est associée à un type qui n'est pas un message, <Copy> ne répond pas.

`<StatusCode>`

Spécifie le code d'état HTTP dans le message d'erreur. Vous pouvez copier ou définir la valeur de l'objet spécifié par l'attribut source.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<Copy>` `<Set>`
Éléments enfants	Aucun

Exemple :

Copier le code d'état

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

Définir le code d'état

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

`<Remove>`

Supprime les en-têtes HTTP spécifiés du message d'erreur. Pour supprimer tous les en-têtes, spécifiez <Remove><Headers/></Remove>.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<FaultResponse>`
Éléments enfants	`<Headers>`

`<Set>`

Définit les informations dans le message d'erreur.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<FaultResponse>`
Éléments enfants	`<Headers>` `<Payload>` `<StatusCode>`

`<Payload>`

Définit la charge utile du message d'erreur.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	`<Set>`
Éléments enfants	Aucun

Exemples :

Définir la charge utile du texte

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

Définir la charge utile JSON - 1

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

Définir la charge utile JSON - 2

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

Cet exemple insère des variables en utilisant les attributs variablePrefix et variableSuffix avec des caractères de délimitation.

Définir la charge utile JSON - 3

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

Cet exemple insère des variables à l'aide d'accolades. Vous pouvez utiliser des accolades à partir de la version 16.08.17.

Définir la charge utile XML

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

Cet exemple insère des variables à l'aide d'accolades. Vous pouvez utiliser des accolades à partir de la version 16.08.17.

`<IgnoreUnresolvedVariables>`

Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.

Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, sinon false. La valeur par défaut est true.

Définir <IgnoreUnresolvedVariables> sur true n'est pas la même chose que définir la valeur continueOnError de <MonetizationLimitsCheck> sur true. Si vous définissez continueOnError sur true, Apigee ignore toutes les erreurs, et pas seulement les erreurs dans les variables.

L'élément <IgnoreUnresolvedVariables> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant définit <IgnoreUnresolvedVariables> sur false :

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Codes d'erreur

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

Variables de flux

Les variables de flux prédéfinies suivantes sont automatiquement renseignées lors de l'exécution de la règle MonetizationLimitsCheck. Pour en savoir plus, consultez les variables de flux mint.

Variable de flux	Description
`mint.limitscheck.is_request_blocked`	`true` pour les requêtes bloquées.
`mint.limitscheck.is_subscription_found`	`true` si un abonnement à l'API est détecté.
`mint.limitscheck.purchased_product_name`	Nom du produit d'API acheté. Exemple : `MyProduct`.
`mint.limitscheck.status_message`	Message d'état. Les valeurs suivantes peuvent être renvoyées : `limits_check_success` : la vérification des limites a réussi. `apiproduct_name_and_developer_email_not_available` : impossible de déterminer le développeur de l'API ou le nom du produit d'API pour effectuer la vérification des limites. `apiproduct_name_not_available` : impossible de déterminer le nom du produit d'API pour vérifier les limites. `developer_email_not_available` : impossible de déterminer l'adresse e-mail du développeur de l'API pour vérifier les limites. `developer_usage_exceeds_balance` : le solde du développeur disposant d'une réserve prépayée est trop faible. `rateplan_not_available` : produit d'API sans plan tarifaire, sans défaut. `subscription_not_available` : le développeur de l'API qui possède l'application n'a pas d'abonnement. `wallet_disabled_due_to_inactivity` : le développeur n'a pas utilisé son portefeuille depuis plus d'un an. Pour le réactiver, vous devez l'approvisionner d'au moins une unité (soit 0,01 $). `wallet_not_found` : le développeur n'a pas de portefeuille. Cela peut se produire lorsqu'aucune recharge n'a été effectuée pour ce développeur.
`mint.subscription_end_time_ms`	Heure de fin de l'abonnement au produit d'API.
`mint.subscription_start_time_ms`	Heure de début de l'abonnement au produit d'API. Exemple : `1618433956209`.

Règle MonétisationLimitsCheck Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Présentation

<MonetizationLimitsCheck>

Syntaxe

Exemple

Référence d'élément enfant

<DisplayName>

Syntaxe

Exemple

<FaultResponse>

<AssignVariable>

<Name>

<Value>

<Add>

<Headers>

Ajouter un en-tête

Définir l'entête

Copier l'en-tête - 1

Copier l'en-tête - 2

Supprimer l'en-tête - 1

Supprimer l'en-tête - 2

<Copy>

<StatusCode>

Copier le code d'état

Définir le code d'état

<Remove>

<Set>

<Payload>

Définir la charge utile du texte

Définir la charge utile JSON - 1

Définir la charge utile JSON - 2

Définir la charge utile JSON - 3

Définir la charge utile XML

<IgnoreUnresolvedVariables>

Syntaxe

Exemple

Codes d'erreur

Runtime errors

Fault variables

Variables de flux

Règle MonétisationLimitsCheck

`<MonetizationLimitsCheck>`

`<DisplayName>`

`<FaultResponse>`

`<AssignVariable>`

`<Name>`

`<Value>`

`<Add>`

`<Headers>`

`<Copy>`

`<StatusCode>`

`<Remove>`

`<Set>`

`<Payload>`

`<IgnoreUnresolvedVariables>`