Configurer le plan tarifaire avec des attributs personnalisés

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

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

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

Les plans tarifaires suivants avec des attributs personnalisés sont acceptés:

• Tableau des tarifs avec attribut personnalisé
• Notification ajustable avec attribut personnalisé

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

Comprendre les calculs d'attributs personnalisés

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

Modèle en charge	Calcul des attributs personnalisés
Taux fixe et Bandes de volume	custom attribute number * rate = charge to developer Pour un taux forfaitaire, le numéro d'attribut personnalisé devient le nombre de transactions multiplié par le tarif. Pour une bande de volume, le nombre de transactions dans une bande est incrémenté du nombre d'attributs personnalisés, et ce nombre de transactions est facturé au développeur. Par exemple, si la valeur d'un 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. S'il ne reste que six transactions dans la bande actuelle, 6 est multiplié par le taux de cette bande. Les quatre autres sont transmises à la bande suivante et sont multipliés par le taux de cette bande. Dans un forfait avec bandes de volume, si la dernière bande de volume présente une limite (qui n'est pas "illimitée") et qu'une transaction dépasse cette limite, deux événements se produisent: Le développeur obtient sans frais le montant "supérieur". L'application du développeur ne peut plus effectuer d'appels à l'API tant que la période de planification n'est pas réinitialisée. Pour en savoir plus sur la réinitialisation des forfaits, consultez Quand les frais récurrents sont-ils facturés et les forfaits groupés sont-ils réinitialisés ?.
Bundles	Les lots étant facturés par groupe et non par transaction, le calcul suivant s'effectue: custom attribute number = amount added to bundle count Par exemple, si le numéro d'attribut personnalisé dans le message est 10, cette valeur est ajoutée au nombre de transactions utilisées dans le bundle. S'il ne reste que six transactions dans le bundle actuel, celui-ci est rempli et le nombre de lots suivant est incrémenté de 4. Le tarif du prochain bundle, le cas échéant, est facturé. Si le dernier bundle a une limite (non "illimitée") et qu'une transaction dépasse cette limite, deux événements se produisent: Le développeur obtient sans frais le montant "supérieur". L'application du développeur ne peut plus effectuer d'appels à l'API tant que la période de planification n'est pas réinitialisée. Pour en savoir plus sur la réinitialisation des forfaits, consultez Quand les frais récurrents sont-ils facturés et les forfaits groupés sont-ils réinitialisés ?.
Notifications ajustables	Dans le cas d'une notification ajustable, le calcul est le suivant: custom attribute number = amount added to transaction count Par exemple, si le numéro d'attribut personnalisé dans le message est 10, cette valeur est ajoutée au nombre total de transactions.

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

Les règles d'enregistrement des transactions (sur le lot de produits de l'API) indiquent à la monétisation où chercher la valeur de l'attribut personnalisé dans le message. Vous devez définir l'attribut personnalisé dans la section "Attributs personnalisés" des règles 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 API contenant la règle d'enregistrement des transactions avec l'attribut personnalisé défini.

Voici la procédure générale:

1. Définissez les attributs personnalisés lorsque vous ajoutez un produit API.
2. Créez un lot de produits API contenant le produit.
   Dans la règle d'enregistrement des transactions du lot de produits API, ajoutez les attributs personnalisés qui serviront à définir les plans tarifaires.
3. Créez un plan tarifaire de type Tableau des tarifs ou une notification ajustable pour le lot de produits API et 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 plan tarifaire. La notification ajustable avec la relation du plan tarifaire avec les attributs personnalisés est similaire, bien que la valeur liée au volume ne soit 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 officielle qu'une fois que vous avez reçu une réponse positive.) Vous trouverez ci-dessous des exemples montrant comment ajouter au message un en-tête de réponse contenant sa valeur numérique. Dans les deux cas, nous utilisons la règle Assign Message (Attribuer un message) en conjonction avec des variables.

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

Dans chaque demande de message, il existe une variable client.received.content.length contenant le nombre d'octets de la charge utile de la requête. En associant une stratégie d'attribution de message à la réponse du point de terminaison du proxy, nous pouvons générer un en-tête de réponse appelé messageSize qui contient 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 de développeur, procédez comme suit:

Lorsque vous utilisez la règle "Valider la clé API" (obligatoire pour la monétisation), cette valeur est stockée dans une variable appelée verifyapikey.{policy_name}.apprating. En utilisant la stratégie d'attribution de message jointe à 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 plan tarifaire

En dehors de la configuration des attributs personnalisés décrite ci-dessus, le plan tarifaire est configuré de la même manière que vous le feriez normalement (pour les plans tarifaires sans attributs personnalisés), mais il doit respecter les exigences suivantes.

Configuration du plan de tableau des tarifs avec attribut personnalisé à l'aide de l'UI

Configurez des plans de tableau des tarifs avec des attributs personnalisés à l'aide de l'interface utilisateur Edge ou de l'interface utilisateur 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 plan tarifaire avec des attributs personnalisés à l'aide de l'API

Procédez comme suit:

1. Dans la règle d'enregistrement des transactions d'un produit d'API, ajoutez les attributs personnalisés qui serviront à définir les plans tarifaires. Pour en savoir plus, consultez l'introduction de cette rubrique, ainsi que la section Créer une règle d'enregistrement des transactions. Effectuez cette opération 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.

Vous allez ensuite utiliser l'API pour créer le plan tarifaire.

Vous spécifiez les détails d'un plan tarifaire avec des attributs personnalisés lorsque vous le créez. Vous spécifiez les détails dans la propriété ratePlanDetails du corps de la requête lors d'un appel à /organizations/{org_name}/monetization-packages/{package_id}/rate-plans. Dans les détails, vous spécifiez une valeur de paramètre "rating" 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é.

Consultez la section Paramètres de configuration des détails du plan tarifaire pour obtenir la liste complète des options de détails du plan tarifaire.

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

Le code suivant crée un plan tarifaire pour les notifications ajustables avec l'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