Configurer une règle d'enregistrement des transactions

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

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

Introduction

Une règle d'enregistrement des transactions permet à la monétisation de capturer les paramètres de transaction et les attributs personnalisés. La monétisation a besoin de ces informations pour procéder au 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 émettant la requête. La part des revenus est basée sur le prix net ou brut de la transaction (vous précisez laquelle). Autrement dit, un pourcentage du prix brut ou net de chaque transaction est utilisé pour déterminer la part des 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 à partir des paramètres que vous avez définis dans la règle d'enregistrement des transactions.

Si vous définissez un tableau des tarifs et que vous facturez chaque transaction au développeur, vous pouvez définir le tarif du forfait en fonction d'un attribut personnalisé, comme le nombre d'octets transmis dans une transaction. La monétisation doit connaître l'attribut personnalisé et savoir où le trouver. Vous devez donc spécifier l'attribut personnalisé dans la règle d'enregistrement des transactions.

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

Configurer une règle d'enregistrement des transactions

Accédez à la page "Offres groupées" comme indiqué ci-dessous.

Périphérie

Lorsque vous ajoutez un lot de produits d'API à l'aide de l'interface utilisateur Edge, vous devez configurer la règle d'enregistrement des transactions en procédant comme suit:

  1. Sélectionnez le produit d'API à configurer dans la section Règle d'enregistrement des transactions (si le lot de produits contient plusieurs produits d'API).
  2. Configurez les attributs de transaction.
  3. Configurez des attributs personnalisés.
  4. Associez des ressources à des ID de transaction uniques.
  5. Configurez des remboursements.
  6. Répétez l'opération pour chaque produit API défini dans le lot de produits API.

Classic Edge (cloud privé)

Pour configurer une règle d'enregistrement des transactions à l'aide de l'interface utilisateur Classic Edge:

  1. Connectez-vous à http://ms-ip:9000, où ms-ip correspond à l'adresse IP ou au nom DNS du nœud du serveur de gestion.
  2. Sélectionnez Publier > Produits dans la barre de navigation en haut de l'écran.
  3. Cliquez sur + Règle d'enregistrement des transactions sur la ligne du produit d'API concerné. La fenêtre "Nouvelle règle d'enregistrement des transactions" s'affiche.
  4. Configurez la règle d'enregistrement des transactions en procédant comme suit :
  5. Cliquez sur Enregistrer.

Configurer les attributs de transaction

Dans la section Attributs de transaction, spécifiez les critères de réussite d'une transaction de monétisation.

  1. Dans le champ Critères de réussite des transactions, spécifiez l'expression en fonction de la valeur de l'attribut "État" (décrit ci-dessous) afin de déterminer si la transaction aboutit (à des fins de 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. L'attribut Status contient la valeur utilisée par l'expression configurée dans le champ Critères de réussite des transactions. Configurez l'attribut Status en définissant les champs suivants:
    Champ Description
    Ressource API Modèles 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 où l'attribut est spécifié. Les valeurs valides incluent : "Flow Variable", "Header", "JSON Body" et "XML Body".
    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 Use Optional Attributes (Utiliser des attributs facultatifs), puis configurez l'un des attributs de transaction définis dans le tableau suivant.
    Attribut Description
    Prix brut

    Cet attribut n'est applicable qu'aux plans tarifaires qui utilisent le modèle de partage des revenus. Pour ces plans tarifaires, le prix brut ou le prix net est obligatoire. Assurez-vous que la valeur numérique est exprimée sous forme de type "Chaîne". Prix brut d'une transaction. Pour les plans de partage des revenus, vous devez indiquer l'attribut Prix brut ou Prix net. L'attribut obligatoire dépend de la part des revenus. Par exemple, vous pouvez configurer un plan de partage des revenus basé sur le prix brut d'une transaction. Dans ce cas, le champ Prix brut est obligatoire.

    Prix net

    Cet attribut n'est applicable qu'aux plans tarifaires qui utilisent le modèle de partage des revenus. Pour ces plans tarifaires, le prix brut ou le prix net est obligatoire. Assurez-vous que la valeur numérique est exprimée sous forme de type "Chaîne". Prix net d'une transaction. Pour les plans de partage des revenus, vous devez enregistrer le champ "Prix net" ou le champ "Prix brut". Le champ obligatoire dépend de la part des revenus. Par exemple, vous pouvez configurer un plan de partage des revenus basé sur le 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 applicable à la transaction.

    Code d'erreur

    Code d'erreur associé à la transaction. Elle fournit des informations supplémentaires sur les échecs de transaction.

    Description article

    Description de la transaction.

    Taxes

    Cet attribut n'est pertinent que pour les modèles de partage des revenus et uniquement si le montant des taxes est enregistré dans les appels d'API. Assurez-vous que la valeur numérique est exprimée sous forme de type "Chaîne". Montant des taxes sur l'achat. Prix net plus 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 au message dans une variable appelée response.reason.phrase. Si la valeur est OK et que la règle de vérification des limites de monétisation est associée à la requête du proxy d'API ProxyEndpoint, la monétisation la comptabilise comme une transaction.

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

Configurer des attributs personnalisés

Dans la section Custom Attributes (Attributs personnalisés), identifiez les attributs personnalisés à inclure dans la règle d'enregistrement des transactions. Par exemple, si vous configurez un plan de tableau des tarifs pour lequel vous facturez au développeur pour chaque transaction, vous pouvez définir le tarif du forfait en fonction d'un attribut personnalisé comme le nombre d'octets transmis dans 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 (vous pouvez ainsi choisir un ou plusieurs de ces attributs sur lesquels baser le tarif du forfait).

Vous pouvez inclure des attributs personnalisés définis dans la règle d'enregistrement des transactions de 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 visible par l'utilisateur dans les détails du plan. Par exemple, si l'attribut personnalisé capture la durée, vous devez nommer l'attribut durée. Les unités réelles pour l'attribut personnalisé (heures, minutes ou secondes, par exemple) sont définies dans le champ d'unité de classification lorsque vous créez un plan tarifaire pour les attributs personnalisés (voir Spécifier un plan tarifaire avec les détails des attributs personnalisés).
Ressource API Sélectionnez un ou plusieurs suffixes d'URI (c'est-à-dire le fragment d'URI qui suit 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 incluent : "Flow Variable", "Header", "JSON Body" et "XML Body".
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é nommé "Longueur du contenu" et que vous sélectionnez "En-tête" comme emplacement de réponse, si la valeur "Longueur du contenu" est fournie dans le champ HTTP Content-Length, vous devez alors spécifier Content-Length comme valeur.

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

  • Appel à une API Reserve qui garantit qu'un utilisateur prépayé dispose d'un crédit suffisant pour acheter le produit et alloue (« réserve ») les fonds pour l'achat.
  • Appel à une API de facturation qui déduit les fonds du compte de l'utilisateur prépayé.

Pour traiter l'intégralité de la transaction, la monétisation doit pouvoir associer la première ressource (l'appel et la réponse à et depuis l'API Reserve) à la deuxième ressource (l'appel et la réponse vers et depuis l'API Charge). Pour ce faire, il s'appuie sur les informations que vous spécifiez dans la section Associer les ressources à 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 associés aux valeurs correspondantes dans les autres transactions.

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

Ressource Emplacement de la réponse Valeur
reserve/{id}**

En-tête

session_id
/charge/{id}**

En-tête

reference_id

Configurer des remboursements

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

Par exemple, supposons qu'un utilisateur achète un produit depuis une application mobile qui utilise vos API monétisées. La transaction est monétisée en fonction du plan de revenus partagé. Cependant, supposons que l'utilisateur n'est 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 de monétisation nécessaires. Elle le fait en fonction des informations que vous spécifiez dans la section "Remboursements" des règles d'enregistrement des transactions.

Pour configurer des remboursements, activez l'option Utiliser les 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 réussite d'un remboursement Expression basée sur la valeur de l'attribut Status (décrit ci-dessous) pour déterminer le moment où l'opération de remboursement a abouti (à des fins de facturation). Les transactions de remboursement 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 Status en définissant les champs suivants:
    Champ Description
    Emplacement de la réponse Emplacement de la réponse où l'attribut est spécifié. Les valeurs valides incluent : "Flow Variable", "Header", "JSON Body" et "XML Body".
    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 (ID parent) en définissant les champs suivants:
    Champ Description
    Emplacement de la réponse Emplacement de la réponse où l'attribut est spécifié. Les valeurs valides incluent : "Flow Variable", "Header", "JSON Body" et "XML Body".
    Valeur Identifiant de la transaction pour laquelle un remboursement est traité. Par exemple, si un utilisateur achète un produit, puis demande un remboursement, l'ID de 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 et configurez-les. Les attributs de remboursement facultatifs sont les mêmes que les attributs de transaction facultatifs, tels que définis dans la section Configurer les attributs de transaction.

Gérer les règles d'enregistrement des transactions à l'aide de 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 API. La valeur de l'attribut identifie:

  • Suffixe d'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 d'URI de la ressource en tant que /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 avoir une règle d'enregistrement des transactions associée à une réponse de cette ressource.
  • Une règle de variable d'extraction qui permet à la règle d'enregistrement de transaction 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 d'une transaction à l'aide de l'API

Vous pouvez spécifier des critères de réussite de transaction pour déterminer le moment où une transaction aboutit (à des fins de facturation). Les transactions qui n'aboutissent pas (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 de critères de réussite d'une transaction, consultez la section Exemples de définition de critères de réussite d'une transaction dans une règle d'enregistrement de transaction.

Vous spécifiez les critères de réussite de la transaction 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 API sur lequel vous appliquez des frais de forfait de base. Par exemple, si vous définissez un plan de tableau des tarifs pour lequel vous facturez au développeur pour chaque transaction, vous pouvez définir le tarif du forfait en fonction d'un attribut personnalisé tel que le nombre d'octets transmis dans une transaction. Lorsque vous créez un plan tarifaire, vous pouvez spécifier un ou plusieurs attributs personnalisés sur lesquels baser le tarif du forfait. Toutefois, chaque produit spécifique d'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 en tant qu'attributs d'un produit 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 API, vous devez spécifier un nom et une valeur d'attribut. Le nom doit respecter le 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 d'une transaction dans une règle d'enregistrement des transactions

Le tableau suivant fournit des exemples de transactions réussies et échouées, en fonction de l'expression de 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 par la monétisation pour déterminer le succès de la transaction.

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