Configurer le plan tarifaire avec des attributs personnalisés

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Introduction

Dans certains cas, vous pouvez avoir besoin que les compteurs de transactions soient basés sur une variable ou une valeur personnalisée. Par exemple, vous devrez peut-être:

• Facturez aux développeurs un montant variable en fonction d'une valeur fournie dans le message d'un appel d'API. Par exemple, vous pouvez facturer aux développeurs d'applications en fonction du nombre d'octets transmis dans la requête API.
• Regroupez plusieurs appels d'API en une seule transaction.

En utilisant des plans tarifaires avec des attributs personnalisés, vous pouvez identifier une valeur dans le message d'un appel d'API qui sert de compteur et qui est utilisée pour calculer le nombre et les frais des transactions.

Les forfaits suivants avec des attributs personnalisés sont acceptés:

• Fiche tarifaire avec attribut personnalisé
• Notification ajustable avec attribut personnalisé

Vous pouvez définir jusqu'à 10 attributs personnalisés par forfait.

Comprendre les calculs des attributs personnalisés

La manière dont la valeur de l'attribut personnalisé est prise en compte dans le nombre de transactions et les frais du plan tarifaire dépend du modèle de facturation, comme indiqué dans le tableau suivant.

Modèle de recharge	Calcul de l'attribut personnalisé
Tarif forfaitaire et tarif évolutif en fonction du volume consommé	custom attribute number * rate = charge to developer Pour un tarif forfaitaire, le numéro de l'attribut personnalisé devient le nombre de transactions multiplié par le tarif. Pour les bandes de volume, le nombre de transactions d'une bande est augmenté du numéro de l'attribut personnalisé, et le développeur est facturé pour ce nombre de transactions. Par exemple, si une valeur d'attribut personnalisé dans le message est 10, 10 transactions sont facturées au développeur, et 10 transactions sont ajoutées au nombre de bandes actuel. Si le développeur ne dispose que de six transactions restantes dans la tranche actuelle, le nombre de transactions est multiplié par le tarif de cette tranche. Les quatre restants sont placés dans la tranche suivante et sont multipliés par le taux de cette tranche. Dans un forfait avec bandes de volume, si la dernière bande de volume présente une limite (n'est pas "illimitée") et qu'une transaction dépasse cette limite, deux situations se présentent: Le développeur bénéficie du montant excédentaire sans frais. L'application de développeur ne peut plus effectuer d'autres appels à l'API tant que la période du forfait n'est pas réinitialisée. Pour savoir quand les forfaits sont réinitialisés, consultez Quand les frais récurrents sont-ils facturés et les forfaits groupés réinitialisés ?.
Groupes	Étant donné que les lots sont facturés par groupe et non par transaction, le calcul suivant est effectué: custom attribute number = amount added to bundle count Par exemple, si le numéro d'attribut personnalisé dans le message est 10, 10 est ajouté au nombre de transactions utilisées dans le lot. S'il ne reste que six transactions dans le bundle actuel, celui-ci est rempli et le nombre de bundle suivant est incrémenté de 4. Le tarif de ce prochain lot, le cas échéant, est facturé. Si le dernier lot est limité (et non illimité) et qu'une transaction dépasse cette limite, deux choses se produisent: Le développeur bénéficie du montant excédentaire sans frais. L'application de développeur ne peut plus effectuer d'autres appels à l'API tant que la période du forfait n'est pas réinitialisée. Pour savoir quand les forfaits sont réinitialisés, consultez Quand les frais récurrents sont-ils facturés et les forfaits groupés réinitialisés ?.
Notifications réglables	Pour les notifications ajustables, le calcul suivant est effectué: custom attribute number = amount added to transaction count Par exemple, si le numéro d'attribut personnalisé dans le message est 10, 10 est ajouté au nombre total de transactions.

Où le forfait obtient-il la valeur de l'attribut personnalisé ?

La règle d'enregistrement des transactions (sur le lot de produits d'API) indique à la monétisation où rechercher la valeur de l'attribut personnalisé dans le message. Vous définissez l'attribut personnalisé dans la section "Attributs personnalisés" de la règle d'enregistrement des transactions pour le lot de produits de l'API.

Vous pouvez ensuite sélectionner cet attribut personnalisé dans le plan tarifaire après avoir créé un lot de produits d'API contenant la règle d'enregistrement des transactions avec l'attribut personnalisé défini.

Voici le processus global:

1. Définissez les attributs personnalisés lorsque vous ajoutez un produit API.
2. Créez un lot de produits d'API contenant le produit.
   Dans la règle d'enregistrement des transactions du lot de produits d'API, ajoutez les attributs personnalisés qui seront utilisés pour définir les plans tarifaires.
3. Créez un plan tarifaire de type tableau des tarifs ou notification ajustable pour le lot de produits de l'API, puis spécifiez un paramètre d'évaluation personnalisée.

La figure suivante montre la relation entre l'attribut personnalisé défini dans la règle d'enregistrement des transactions et la configuration du forfait de tarif. La notification ajustable avec la relation de plan tarifaire d'attribut personnalisé est similaire, mais la valeur en fonction du volume n'est pas applicable.

Générer la valeur de l'attribut personnalisé dans le message

La règle d'enregistrement des transactions peut rechercher la valeur de l'attribut personnalisé à plusieurs endroits, tels que l'en-tête de la réponse, le corps de la réponse ou les variables de flux prédéfinies dans la réponse. (La requête n'est pas disponible, car une transaction n'est pas officielle tant que vous n'avez pas reçu de réponse positive.) Vous trouverez ci-dessous des exemples montrant comment ajouter un en-tête de réponse avec sa valeur numérique au message. Dans les deux cas, nous utiliserons la règle d'attribution de message avec des variables.

Ajouter la taille de la charge utile de la requête à l'en-tête de réponse

Dans chaque requête de message, une variable client.received.content.length contient le nombre d'octets dans la charge utile de la requête. En associant une règle Assign Message à la réponse du point de terminaison du proxy, nous pouvons générer un en-tête de réponse appelé messageSize contenant la valeur de longueur:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messageSize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Ajouter une valeur d'attribut personnalisé d'application à l'en-tête

De la même manière, nous pouvons générer un en-tête avec la valeur d'un attribut personnalisé sur une application. Par exemple, si vous incluez un attribut personnalisé appelé apprating dans chaque application du développeur, comme suit:

Lorsque vous utilisez la règle Vérifier la clé API (qui est requise pour la monétisation), cette valeur est stockée dans une variable appelée verifyapikey.{policy_name}.apprating. À l'aide de la règle AssignMessage associée à la réponse du point de terminaison du proxy, vous pouvez générer un en-tête appelé apprating contenant la valeur apprating de l'application:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Configurer le forfait

Outre la configuration des attributs personnalisés décrite ci-dessus, le forfait est configuré de la même manière que d'habitude (pour les forfaits sans attributs personnalisés), mais doit respecter les exigences suivantes.

Configurer un forfait de carte tarifaire avec un attribut personnalisé à l'aide de l'UI

Configurez les plans de tableau des tarifs avec des attributs personnalisés à l'aide de l'interface utilisateur Edge ou Classic Edge, comme décrit dans les sections suivantes.

Configurer un plan de notification ajustable avec des attributs personnalisés à l'aide de l'UI

Configurez des plans de notification ajustables avec des attributs personnalisés, comme décrit ci-dessous.

Spécifier les détails d'un forfait avec des attributs personnalisés à l'aide de l'API

Effectuez les étapes préalables suivantes:

1. Dans la règle d'enregistrement des transactions d'un produit API, ajoutez les attributs personnalisés qui seront utilisés pour définir les forfaits. Pour en savoir plus, consultez l'introduction de cette rubrique, ainsi que Créer une règle d'enregistrement des transactions. Faites-le pour chaque produit d'API que vous souhaitez inclure dans le package d'API.
2. Une fois que les produits d'API et les règles d'enregistrement des transactions sont configurés exactement comme vous le souhaitez, créez un package d'API contenant le produit. Consultez Créer des packages d'API.

Ensuite, vous utilisez l'API pour créer le plan tarifaire.

Vous spécifiez les détails d'un forfait tarifaire avec des attributs personnalisés lorsque vous le créez. Vous spécifiez les détails dans la propriété ratePlanDetails dans le corps de la requête dans un appel à /organizations/{org_name}/monetization-packages/{package_id}/rate-plans. Dans les détails, vous spécifiez une valeur de paramètre de classification qui identifie le nom de l'attribut personnalisé. Vous pouvez également spécifier une valeur de paramètre de note qui agrège l'attribut personnalisé sur un intervalle de temps spécifié.

Pour obtenir la liste complète des options de configuration des détails du forfait, consultez la section Paramètres de configuration des détails du forfait.

L'exemple suivant permet de créer un tableau des tarifs avec un plan d'attributs personnalisés basé sur un attribut personnalisé nommé messageSize (voir les éléments en gras).

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"messageSize",
      "ratingParameterUnit":"MB",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "recurringStartUnit": 1,
    "recurringType": "CALENDAR",
    "recurringFee": "10",
    "setUpFee": "10",
    "startDate": "2013-09-15 00:00:00",
    "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

L'exemple suivant crée une notification ajustable avec un plan tarifaire à attribut personnalisé basé sur un attribut personnalisé nommé messageSize (voir l'élément en gras).

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Custom attribute-based adjustable notification plan",
     "description": "Custom attribute-based adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "messageSize",
           "ratingParameterUnit": "MB",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password