Configurer une règle d'enregistrement des transactions

Vous consultez la documentation sur Apigee Edge.
Consultez la documentation sur Apigee X.

Configurez les règles d'enregistrement des transactions pour chaque produit d'API de votre lot de produits d'API, comme indiqué dans les sections suivantes.

Introduction

Une règle d'enregistrement des transactions permet à la monétisation de capturer des paramètres de transaction et des attributs personnalisés. La monétisation a besoin de ces informations pour effectuer le traitement de la monétisation, par exemple pour appliquer des plans tarifaires.

Par exemple, si vous configurez un plan de partage des revenus, un pourcentage des revenus générés par chaque transaction impliquant votre produit d'API monétisé est partagé avec le développeur de l'application à l'origine de la requête. La part des revenus est basée sur le prix net ou brut de la transaction (vous spécifiez lequel), soit un pourcentage du prix brut ou net de chaque transaction permettant de déterminer la part de revenus. Pour cette raison, la monétisation doit connaître le prix brut ou net d'une transaction, le cas échéant. Il obtient le prix brut ou net défini dans les paramètres de la règle d'enregistrement des transactions.

Si vous configurez un tableau des tarifs dans lequel vous facturez au développeur chaque transaction, vous pouvez définir le tarif du plan en fonction d'un attribut personnalisé, comme le nombre d'octets transmis lors d'une transaction. La monétisation doit connaître l'attribut personnalisé ainsi que son emplacement. Vous devez donc spécifier l'attribut personnalisé dans la règle d'enregistrement des transactions.

En plus de spécifier des attributs de transaction dans la règle d'enregistrement des transactions, vous pouvez spécifier des critères de réussite pour déterminer quand une transaction aboutit (pour la facturation). Pour obtenir des exemples de définition des critères de réussite des transactions, consultez Exemples de définition de critères de réussite des transactions dans une règle d'enregistrement des transactions. Vous pouvez également spécifier des attributs personnalisés pour un produit d'API (sur lesquels vous basez des frais de forfait).

Configurer une règle d'enregistrement des transactions

Accédez à la page des offres groupées, comme décrit ci-dessous.

Configurer des attributs de transaction

Dans la section Attributs de la transaction, spécifiez les critères qui indiquent que la monétisation a réussi.

1. Dans le champ Critère de réussite de la transaction, spécifiez l'expression en fonction de la valeur de l'attribut "État" (décrite ci-dessous) afin de déterminer quand la transaction aboutit (pour la facturation). Les transactions infructueuses (autrement dit, qui ne répondent pas aux critères de l'expression) sont enregistrées, mais les plans tarifaires ne leur sont pas appliqués. Exemple :

   txProviderStatus == 'OK'

2. L'attribut Status (État) contient la valeur utilisée par l'expression configurée dans le champ Transaction Success Criteria (Critères de réussite des transactions). Configurez l'attribut Status en définissant les champs suivants:

   Champ	Description
   Ressource API	Formats d'URI définis dans le produit d'API qui seront utilisés pour identifier les transactions monétisées.
   Emplacement de la réponse	Emplacement de la réponse dans laquelle l'attribut est spécifié. Les valeurs valides sont les suivantes: Variable de flux, En-tête, Corps JSON et Corps XML.
   Valeur	Valeur de la réponse. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux).

3. Pour configurer des attributs de transaction facultatifs, activez l'option Utiliser des attributs facultatifs et configurez l'un des attributs de transaction définis dans le tableau suivant.

   Attribut	Description
   Prix brut	Cet attribut ne s'applique qu'aux plans tarifaires qui utilisent le modèle de partage des revenus. Dans ce cas, le prix brut ou le prix net est obligatoire. Assurez-vous que la valeur numérique est exprimée sous la forme d'un type de chaîne. Prix brut d'une transaction. Pour les forfaits basés sur le partage des revenus, vous devez enregistrer l'attribut prix brut ou prix net. L'attribut obligatoire dépend du partage des revenus. Par exemple, vous pouvez configurer un plan de partage des revenus en fonction du prix brut d'une transaction. Dans ce cas, le champ "Prix brut" est obligatoire.
   Prix net	Cet attribut ne s'applique qu'aux plans tarifaires qui utilisent le modèle de partage des revenus. Dans ce cas, le prix brut ou le prix net est obligatoire. Assurez-vous que la valeur numérique est exprimée sous la forme d'un type de chaîne. Prix net d'une transaction. Pour les plans de partage des revenus, vous devez enregistrer le champ "Prix net" ou "Prix brut". Le champ obligatoire dépend du partage des revenus. Par exemple, vous pouvez configurer un plan de partage des revenus en fonction du prix net d'une transaction. Dans ce cas, le champ "Prix net" est obligatoire.
   Currency	Cet attribut est obligatoire pour les plans tarifaires qui utilisent le modèle de partage des revenus. Type de devise qui s'applique à la transaction.
   Code d'erreur	Code d'erreur associé à la transaction. Elle fournit des informations supplémentaires sur l'échec d'une transaction.
   Description article	Description de la transaction.
   Taxes	Cet attribut n'est pertinent que pour les modèles de partage des revenus, et seulement si le montant des taxes est enregistré dans les appels d'API. Assurez-vous que la valeur numérique est exprimée sous la forme d'un type String. Montant des taxes pour l'achat. Prix net + taxes = prix brut.

Par exemple, en définissant les valeurs suivantes, la monétisation obtient la valeur de la variable de flux à partir de la réponse du message, dans une variable appelée response.reason.phrase. Si la valeur est correcte et que la règle de vérification des limites de monétisation est associée à la requête de proxy d'API, la monétisation la comptabilise comme une transaction.

Champ	Valeur
Critères de réussite de la transaction	txProviderStatus == 'OK'
État: ressource d'API	**
État: emplacement de la réponse	Variable de flux
État: variable Flow	response.reason.phrase

Configurer des attributs personnalisés

Dans la section Attributs personnalisés, vous devez identifier les attributs personnalisés à inclure dans la règle d'enregistrement des transactions. Par exemple, si vous configurez un plan tarifaire dans lequel vous facturez le développeur pour chaque transaction, vous pouvez définir le tarif du plan en fonction d'un attribut personnalisé, comme le nombre d'octets transmis lors d'une transaction. Vous devez ensuite inclure cet attribut personnalisé dans la règle d'enregistrement des transactions.

Chacun de ces attributs est stocké dans le journal des transactions, que vous pouvez interroger. Ils s'affichent également lorsque vous créez un plan tarifaire, afin que vous puissiez choisir un ou plusieurs de ces attributs pour votre tarif.

Vous pouvez inclure des attributs personnalisés définis dans la règle d'enregistrement des transactions dans vos rapports récapitulatifs sur les revenus, comme décrit dans la section Inclure des attributs de transaction personnalisés dans les rapports récapitulatifs sur les revenus.

Pour configurer des attributs personnalisés, activez l'option Utiliser des attributs personnalisés et définissez jusqu'à 10 attributs personnalisés. Pour chaque attribut personnalisé que vous incluez dans la règle d'enregistrement des transactions, vous devez spécifier les informations suivantes.

Champ	Description
Nom de l'attribut personnalisé	Saisissez un nom décrivant l'attribut personnalisé. Si le plan tarifaire est basé sur un attribut personnalisé, ce nom est présenté à l'utilisateur dans les détails du plan tarifaire. Par exemple, si l'attribut personnalisé capture la durée, vous devez nommer la durée de l'attribut. Les unités réelles de l'attribut personnalisé (heures, minutes ou secondes, par exemple) sont définies dans le champ de l'unité d'évaluation lorsque vous créez un plan tarifaire d'attribut personnalisé (consultez Spécifier un plan tarifaire avec des détails sur l'attribut personnalisé).
Ressource API	Sélectionnez un ou plusieurs suffixes d'URI (c'est-à-dire le fragment URI suivant le chemin de base) d'une ressource d'API accessible dans la transaction. Les ressources disponibles sont les mêmes que pour les attributs de transaction.
Emplacement de la réponse	Sélectionnez l'emplacement dans la réponse où l'attribut est spécifié. Les valeurs valides sont les suivantes: Variable de flux, En-tête, Corps JSON et Corps XML.
Valeur	Spécifiez une valeur pour l'attribut personnalisé. Chaque valeur que vous spécifiez correspond à un champ, un paramètre ou un élément de contenu qui fournit l'attribut personnalisé à l'emplacement que vous avez spécifié. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux). Par exemple, si vous configurez un attribut personnalisé intitulé "Longueur du contenu" et sélectionnez l'en-tête comme emplacement de la réponse, si la valeur "Longueur du contenu" est fournie dans le champ "Longueur du contenu HTTP", vous devez spécifier Content-Length comme valeur.

Associer des ressources avec un ID de transaction unique

Certaines transactions sont simples et impliquent un appel d'API à une ressource spécifique. Toutefois, d'autres transactions peuvent être plus complexes. Par exemple, supposons qu'une transaction pour acheter un produit intégré dans une application de jeu mobile implique plusieurs appels de ressources:

• Un appel à une API de réservation permet de s'assurer qu'un utilisateur prépayé a suffisamment de crédit pour acheter le produit et alloue ("réserve") les fonds pour l'achat.
• Un appel à une API de facturation qui déduit les fonds du compte de l'utilisateur prépayé

Pour traiter l'ensemble de la transaction, la monétisation doit être associée à la première ressource (appel et réponse vers et depuis l'API de réservation) avec la deuxième ressource (appel et réponse vers et depuis l'API de facturation). Pour ce faire, elle s'appuie sur les informations que vous spécifiez dans la section Associer les ressources avec un ID de transaction unique.

Pour configurer des attributs personnalisés, activez l'option Utiliser des ID de transaction uniques et associez les transactions. Pour chaque transaction, vous spécifiez une ressource, un emplacement de réponse et une valeur d'attribut qui est associée aux valeurs correspondantes dans les autres transactions.

Par exemple, supposons que l'appel d'API de réservation et l'appel d'API de charge soient liés comme suit: un champ nommé session_id dans l'en-tête de réponse de l'API de réservation correspond à un en-tête de réponse nommé reference_id dans l'API de charge. Dans ce cas, vous pouvez définir les entrées de la section "Associer des ressources avec un ID de transaction unique" comme suit:

Ressource	Emplacement de la réponse	Valeur
reserve/{id}**	Header	session_id
/charge/{id}**	Header	reference_id

Configurer des remboursements

Dans la section Remboursements, spécifiez les attributs utilisés par la monétisation pour traiter les remboursements.

Par exemple, supposons qu'un utilisateur achète un produit d'une application mobile qui utilise vos API monétisées. La transaction est monétisée en fonction du forfait partagé. Supposons toutefois que l'utilisateur ne soit pas satisfait du produit et qu'il souhaite le retourner. Si le produit est remboursé via un appel à l'API qui effectue le remboursement, la monétisation effectue les ajustements nécessaires. Cette opération est effectuée en fonction des informations que vous spécifiez dans la section "Remboursements" de la politique d'enregistrement des transactions.

Pour configurer les remboursements, activez l'option Utiliser des attributs de remboursement et définissez les détails du remboursement:

1. Définissez les critères de remboursement en définissant les champs suivants:

   Champ	Description
   Emplacement de la réponse	Ressource pour l'opération de remboursement. Si le produit d'API fournit plusieurs ressources, vous ne pouvez sélectionner que celle qui effectue le remboursement.
   Critères de remboursement	Expression basée sur la valeur de l'attribut "État" (décrite ci-dessous) pour déterminer le moment où la transaction de remboursement aboutit (pour la facturation). Les transactions qui n'aboutissent pas (c'est-à-dire qui ne répondent pas aux critères de l'expression) sont enregistrées, mais les plans tarifaires ne leur sont pas appliqués. Exemple : txProviderStatus == 'OK'

2. Configurez l'attribut État en définissant les champs suivants:

   Champ	Description
   Emplacement de la réponse	Emplacement de la réponse dans laquelle l'attribut est spécifié. Les valeurs valides sont les suivantes: Variable de flux, En-tête, Corps JSON et Corps XML.
   Valeur	Valeur de la réponse. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux).

3. Configurez l'attribut Parent ID en définissant les champs suivants:

   Champ	Description
   Emplacement de la réponse	Emplacement de la réponse dans laquelle l'attribut est spécifié. Les valeurs valides sont les suivantes: Variable de flux, En-tête, Corps JSON et Corps XML.
   Valeur	Identifiant de la transaction faisant l'objet d'un remboursement. Par exemple, si un utilisateur achète un produit, puis demande un remboursement, l'ID de la transaction parente correspond à l'ID de la transaction d'achat. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux).

4. Pour configurer des attributs de remboursement facultatifs, activez l'option Utiliser des attributs de remboursement facultatifs. Les attributs de remboursement facultatifs sont identiques aux attributs de transaction facultatifs, tels que définis dans Configurer des attributs de transaction.

Gérer les règles d'enregistrement des transactions avec l'API

Les sections suivantes décrivent comment gérer les règles d'enregistrement des transactions à l'aide de l'API.

Créer une règle d'enregistrement des transactions à l'aide de l'API

Vous spécifiez une règle d'enregistrement des transactions en tant qu'attribut d'un produit d'API. La valeur de l'attribut identifie les éléments suivants:

• Suffixe de l'URI de la ressource produit à laquelle la règle d'enregistrement des transactions est associée. Le suffixe inclut une variable de modèle entourée d'accolades. La variable de modèle est évaluée par les services d'API au moment de l'exécution. Par exemple, le suffixe d'URI suivant inclut la variable de modèle {id}.

  /reserve/{id}**
  

  Dans ce cas, les services d'API évaluent le suffixe URI de la ressource comme /reserve, suivi de tout sous-répertoire commençant par un ID défini par le fournisseur d'API.

• Ressource dans la réponse à laquelle elle est associée. Un produit d'API peut disposer de plusieurs ressources, et chaque ressource peut être associée à une règle d'enregistrement des transactions en réponse à une ressource de la ressource.
• Une règle d'extraction de variable permettant d'extraire le contenu d'un message de réponse pour les paramètres de transaction que vous souhaitez capturer.

Pour ajouter l'attribut de règle d'enregistrement des transactions à un produit d'API, envoyez une requête PUT à l'API de gestion https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (et non à une API de monétisation).

Spécifier des critères de réussite des transactions à l'aide de l'API

Vous pouvez spécifier des critères de réussite des transactions pour déterminer à quel moment une transaction a abouti (pour la facturation). Les transactions qui échouent (c'est-à-dire qui répondent aux critères de l'expression) sont enregistrées, mais les plans tarifaires ne leur sont pas appliqués. Pour obtenir des exemples de définition des critères de réussite des transactions, consultez Exemples de définition de critères de réussite des transactions dans une règle d'enregistrement des transactions.

Vous spécifiez les critères de réussite des transactions en tant qu'attribut d'un produit d'API. Pour ce faire, envoyez une requête PUT à l'API de gestion https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (et non à l'API de monétisation).

Par exemple, dans la requête suivante, une transaction aboutit si la valeur de txProviderStatus est success (les spécifications liées aux critères de réussite de la transaction sont mises en surbrillance).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Spécifier des attributs personnalisés à l'aide de l'API

Vous pouvez spécifier des attributs personnalisés pour un produit d'API sur lequel vous basez des frais pour votre plan tarifaire de base. Par exemple, si vous configurez un plan tarifaire où vous facturez le développeur pour chaque transaction, vous pouvez définir le tarif du plan en fonction d'un attribut personnalisé, comme le nombre d'octets transmis lors d'une transaction. Lorsque vous créez un plan tarifaire, vous pouvez spécifier un ou plusieurs attributs personnalisés sur lesquels baser votre tarif pour ce plan. Cependant, un produit spécifique dans un plan tarifaire ne peut avoir qu'un seul attribut personnalisé sur lequel baser le tarif du plan.

Vous spécifiez des attributs personnalisés comme attributs d'un produit d'API. Pour ce faire, envoyez une requête PUT à l'API de gestion https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (et non à l'API de monétisation).

Pour chaque attribut personnalisé que vous ajoutez à un produit d'API, vous devez spécifier un nom et une valeur d'attribut. Le nom doit être au format MINT_CUSTOM_ATTRIBUTE_{num}, où {num} est un entier.

Par exemple, la requête suivante spécifie trois attributs personnalisés.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Exemples de définition de critères de réussite de transaction dans une règle d'enregistrement des transactions

Le tableau suivant fournit des exemples de transactions ayant abouti ou échoué, en fonction de l'expression des critères de réussite de la transaction et de la valeur txProviderStatus renvoyée par le proxy d'API. txProviderStatus est la variable interne utilisée pour monétiser la transaction.

Expression des critères de réussite	Expression valide ?	Valeur txProviderStatus du proxy d'API	Résultat de l'évaluation
null	vrai	"200"	faux
""	faux	"200"	faux
" "	faux	"200"	faux
"sdfsdfsdf"	faux	"200"	faux
"txProviderStatus =='100'"	vrai	"200"	faux
"txProviderStatus =='200'"	vrai	"200"	vrai
"true"	vrai	"200"	vrai
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	vrai	"OK"	vrai
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	vrai	"OK"	vrai
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	vrai	"Not Found"	vrai
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	vrai	"Bad Request"	vrai
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	vrai	"Bad Request"	vrai
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	vrai	null	faux
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	vrai	"bad request"	vrai
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	vrai	"Redirect"	faux
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	vrai	"heeeelllooo"	faux
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	vrai	null	faux
"txProviderStatus == 100"	vrai	"200"	faux