Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.
Introduction
Les rapports sur la monétisation vous permettent d'accéder à des informations détaillées sur l'utilisation et l'activité des transactions. Par exemple, vous pouvez déterminer quelles applications, quels développeurs, quels packs de produits d'API ou quels produits d'API ont enregistré une activité de transaction pour une période donnée. La monétisation vous permet de générer des rapports récapitulatifs ou détaillés qui suivent l'utilisation des API.
Types de rapports sur la monétisation
Vous pouvez générer les types de rapports de monétisation suivants.
| Signaler | Description |
|---|---|
| Facturation | Affichez l'activité des développeurs pour un mois de facturation donné et vérifiez que les forfaits ont été appliqués correctement. |
| Solde prépayé | Affichez les recharges de solde effectuées par un développeur prépayé au cours d'un mois de facturation ou d'un mois actuellement ouvert, afin de pouvoir les rapprocher des paiements reçus de votre processeur de paiement. |
| Revenus | Affichez l'activité et les revenus générés par les développeurs au cours d'une période donnée. Vous pourrez ainsi analyser les performances de vos produits et packs de produits d'API pour vos développeurs (et leurs applications). |
| Variance |
Comparez l'activité et les revenus générés par les développeurs sur deux périodes afin d'analyser les tendances à la hausse ou à la baisse des performances de vos packages et produits d'API pour vos développeurs (et leurs applications). |
À propos de la conservation des données
Dans le cloud public Apigee Edge, la conservation des données de monétisation est un droit d'accès au forfait. Consultez les droits de monétisation sur https://cloud.google.com/apigee/specsheets. Contactez le service commercial d'Apigee si vous souhaitez que les données de monétisation soient conservées au-delà de la période de validité des droits. La conservation étendue des données est activée au moment de la demande. Elle ne peut pas être activée rétroactivement pour inclure des données antérieures à la période de conservation des données d'origine.
À propos des transactions en double
Si vous comparez les rapports sur les transactions de monétisation avec les données Analytics, vous remarquerez peut-être un petit nombre de transactions en double. Il s'agit d'un comportement normal, car le système de monétisation peut traiter plusieurs millions de transactions par jour, dont beaucoup en parallèle à tout moment. En moyenne, environ 0,1% des transactions peuvent être des doublons.
Explorer la page "Rapports sur la monétisation"
Accédez à la page "Rapports sur la monétisation", comme décrit ci-dessous.
Edge
Pour accéder à la page "Rapports" à l'aide de l'interface utilisateur Edge :
- Connectez-vous à apigee.com/edge.
- Sélectionnez Publier > Monétisation > Rapports dans la barre de navigation de gauche.
La page "Rapports" s'affiche.
Comme le montre la figure, la page "Rapports" vous permet de :
- Afficher des informations récapitulatives pour tous les rapports, y compris le nom et la description, le type de rapport et la plage de dates, ainsi que la date de la dernière modification
- Configurer un rapport
- Générer et télécharger un rapport au format CSV ou ZIP
- Modifier un rapport
- Supprimer un rapport
- Rechercher dans la liste des rapports
Classic Edge (Private Cloud)
Pour accéder à la page "Rapports" à l'aide de l'interface utilisateur Classic Edge :
- Connectez-vous à
http://ms-ip:9000, où ms-ip est l'adresse IP ou le nom DNS du nœud de serveur de gestion. - Sélectionnez Monétisation > Rapports sur la monétisation dans la barre de navigation supérieure.
La page "Rapports" s'affiche.
- Afficher la liste actuelle des rapports
- Configurer un rapport
- Générer et télécharger un rapport au format CSV
- Modifier un rapport
- Supprimer un rapport
Configurer un rapport
Configurez un rapport à l'aide de l'interface utilisateur, comme décrit dans les sections suivantes.
Étapes pour configurer un rapport
Configurez un rapport à l'aide de l'interface utilisateur Edge ou de l'interface utilisateur Classic Edge.
Edge
Pour configurer un rapport à l'aide de l'interface utilisateur Edge :
- Sélectionnez Publier > Monétisation > Rapports dans la barre de navigation de gauche.
- Cliquez sur + Rapport.
- Configurez les détails du rapport définis dans le tableau suivant.
Champ Description Nom Nom unique du rapport. Description La description du rapport. Type de rapport Consultez Types de rapports sur la monétisation. - Configurez les autres détails du rapport en fonction du type de rapport sélectionné, comme décrit dans les sections suivantes :
- Une fois les informations saisies dans la fenêtre du rapport, vous pouvez :
- Cliquez sur Enregistrer le rapport pour enregistrer la configuration du rapport.
Pour un rapport détaillé uniquement, cliquez sur Envoyer la tâche pour exécuter le rapport de manière asynchrone et récupérer les résultats ultérieurement. Pour en savoir plus, consultez Générer et télécharger un rapport.
- Cliquez sur Enregistrer au format CSV ou Enregistrer au format ZIP pour télécharger le rapport généré sur votre ordinateur local au format CSV (valeurs séparées par une virgule) ou au format ZIP compressé contenant le fichier CSV. Les téléchargements au format ZIP sont recommandés pour les rapports volumineux et sont plus efficaces.
Classic Edge (Private Cloud)
Pour créer un rapport à l'aide de l'interface utilisateur Classic Edge :
- Sélectionnez Monétisation > Rapports sur la monétisation dans la barre de navigation supérieure.
- Dans le menu déroulant, sélectionnez le type de rapport que vous souhaitez créer. Consultez Types de rapports sur la monétisation.
- Cliquez sur + Rapport.
- Configurez les détails du rapport en fonction du type de facturation sélectionné, comme décrit dans les sections suivantes :
- Une fois les informations saisies dans la fenêtre du rapport, vous pouvez :
- Cliquez sur Enregistrer sous… pour enregistrer la configuration du rapport et le télécharger ultérieurement.
Pour un rapport détaillé uniquement, cliquez sur Envoyer la tâche pour exécuter le rapport de manière asynchrone et récupérer les résultats ultérieurement. Pour en savoir plus, consultez Générer et télécharger un rapport.
- Cliquez sur Télécharger au format CSV pour générer et télécharger le rapport sur votre ordinateur local au format CSV (valeurs séparées par une virgule).
Configurer un rapport sur la facturation
Suivez la procédure pour configurer un rapport et saisissez les informations suivantes sur la page du rapport :
| Champ | Description |
|---|---|
| Mois de facturation |
Mois de facturation du rapport. |
| Niveau de reporting |
Niveau de création de rapports. Les valeurs valides sont les suivantes :
|
| Lots de produits |
Remarque : Dans l'interface utilisateur Classic Edge, les packs de produits d'API sont appelés "packages d'API". Sélectionnez les packs de produits d'API à inclure dans le rapport. Si vous n'en sélectionnez aucun, tous les packs de produits d'API sont inclus dans le rapport. Le rapport inclut une ligne distincte pour chaque pack de produits API sélectionné. Pour un rapport récapitulatif, vous pouvez éventuellement cocher Ne pas afficher dans les options d'affichage du récapitulatif. Dans ce cas, le rapport agrège les informations de tous les bundles de produits d'API (ou de ceux sélectionnés) et ne liste pas les informations de chaque bundle de produits d'API séparément. |
| Produits |
Sélectionnez les produits d'API à inclure dans le rapport. Si vous n'en sélectionnez aucun, tous les produits d'API sont inclus dans le rapport. Le rapport inclut une ligne distincte pour chaque produit API sélectionné. Pour un rapport récapitulatif, vous pouvez éventuellement cocher Ne pas afficher dans les options d'affichage du récapitulatif. Dans ce cas, le rapport agrège les informations de tous les développeurs (ou de ceux sélectionnés) et ne les liste pas séparément. |
| Entreprises | Sélectionnez les entreprises à inclure dans le rapport. Si vous n'en sélectionnez aucune, toutes les entreprises sont incluses dans le rapport. |
| Plan tarifaire |
Plans tarifaires à inclure dans le rapport. Sélectionnez l'une des options ci-dessous :
|
Configurer un rapport sur le solde prépayé
Suivez la procédure pour configurer un rapport et saisissez les informations suivantes sur la page du rapport :| Champ | Description |
|---|---|
| Mois de facturation |
Mois de facturation du rapport. |
| Niveau de reporting |
Niveau de création de rapports. Les valeurs valides sont les suivantes :
|
| Entreprises | Sélectionnez les entreprises à inclure dans le rapport. Si vous n'en sélectionnez aucune, toutes les entreprises sont incluses dans le rapport. |
Configurer un rapport sur les revenus
Suivez la procédure pour configurer un rapport et saisissez les informations suivantes sur la page du rapport :
| Champ | Description |
|---|---|
| Période |
Plage de dates du rapport. Sélectionnez l'une des options ci-dessous :
|
| Sélectionnez une devise |
Devise du rapport. Les valeurs valides sont les suivantes :
|
| Niveau de reporting |
Niveau de création de rapports. Les valeurs valides sont les suivantes :
|
| Lots de produits |
Remarque : Dans l'interface utilisateur Classic Edge, les packs de produits d'API sont appelés "packages d'API". Sélectionnez les packs de produits d'API à inclure dans le rapport. Si vous n'en sélectionnez aucun, tous les packs de produits d'API sont inclus dans le rapport. Le rapport inclut une ligne distincte pour chaque pack de produits API sélectionné. Pour un rapport récapitulatif, vous pouvez éventuellement cocher Ne pas afficher dans les options d'affichage du récapitulatif. Dans ce cas, le rapport agrège les informations de tous les bundles de produits d'API (ou de ceux sélectionnés) et ne liste pas les informations de chaque bundle de produits d'API séparément. |
| Produits |
Sélectionnez les produits d'API à inclure dans le rapport. Si vous n'en sélectionnez aucun, tous les produits d'API sont inclus dans le rapport. Le rapport inclut une ligne distincte pour chaque produit API sélectionné. Pour un rapport récapitulatif, vous pouvez éventuellement cocher Ne pas afficher dans les options d'affichage du récapitulatif. Dans ce cas, le rapport agrège les informations de tous les développeurs (ou de ceux sélectionnés) et ne les liste pas séparément. |
| Entreprises | Sélectionnez les entreprises à inclure dans le rapport. Si vous n'en sélectionnez aucune, toutes les entreprises sont incluses dans le rapport. Pour un rapport récapitulatif, vous pouvez éventuellement cocher Ne pas afficher dans la section "Options d'affichage du récapitulatif". Dans ce cas, le rapport agrège les informations de toutes les entreprises (ou de celles sélectionnées) et ne les liste pas séparément pour chaque entreprise sélectionnée. |
| Applications |
Sélectionnez les applications à inclure dans le rapport. Si vous n'en sélectionnez aucune, toutes les applications sont incluses dans le rapport. Le rapport inclut une ligne distincte pour chaque application sélectionnée. Pour un rapport récapitulatif, vous pouvez éventuellement cocher Ne pas afficher dans la section "Options d'affichage du récapitulatif". Dans ce cas, le rapport regroupe les informations de toutes les applications (ou de celles sélectionnées) et ne liste pas les informations de chaque application sélectionnée séparément. |
| Options d'affichage du récapitulatif |
Ordre dans lequel les colonnes sont regroupées et affichées dans le rapport. Sélectionnez un nombre qui indique l'ordre relatif de cette section dans le regroupement (1 correspond au premier regroupement). Par exemple, le rapport suivant est d'abord regroupé par packages, puis par produits, puis par développeurs, puis par applications.
Si vous ne souhaitez pas afficher une section, sélectionnez Ne pas afficher, puis sélectionnez les champs restants dans l'ordre. L'ordre est automatiquement mis à jour lorsque vous modifiez l'ordre relatif d'une section ou choisissez de ne pas afficher une section dans le rapport. |
Inclure des attributs de transaction personnalisés dans les rapports récapitulatifs sur les revenus
Les règles d'enregistrement des transactions vous permettent de capturer des données d'attributs personnalisés à partir des transactions. Vous pouvez inclure ces attributs personnalisés dans les rapports récapitulatifs sur les revenus. Définissez l'ensemble par défaut d'attributs personnalisés inclus dans les tables de la base de données de monétisation en définissant la propriété MINT.SUMMARY_CUSTOM_ATTRIBUTES pour votre organisation.
L'utilisation de cette fonctionnalité nécessite une certaine réflexion et planification. Examinez donc les points à prendre en compte ci-dessous.
Si vous êtes un client Cloud, contactez l'assistance Apigee Edge pour définir la propriété. Si vous êtes un client Apigee Edge pour le cloud privé, définissez l'indicateur à l'aide d'une requête PUT vers l'API suivante avec les identifiants d'administrateur système.
curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isMonetizationEnabled">true</Property> <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">["partner_id","tax_source"]</Property> <Property name="features.topLevelDevelopersAreCompanies">false</Property> </Properties> </Organization>"
Dans cet exemple, l'appel d'API active la fonctionnalité et ajoute les colonnes partner_id et tax_source à la base de données de monétisation. Notez que le tableau d'attributs personnalisés dans l'appel d'API est encodé au format URL.
Points à prendre en compte pour inclure des attributs de transaction personnalisés dans les rapports
- Assurez-vous de connaître les noms d'attributs que vous souhaitez utiliser avant de les créer avec l'API. Il s'agit des noms de colonnes de la base de données, où les données d'attribut personnalisé sont toujours stockées.
- Chaque règle d'enregistrement des transactions comporte 10 emplacements d'attributs personnalisés, comme illustré dans l'image suivante. Utilisez exactement les mêmes noms et positions d'attributs pour les mêmes attributs dans les produits qui seront inclus dans les rapports. Par exemple, dans la règle d'enregistrement des transactions suivante, les attributs personnalisés
partner_idettax_sourceoccupent respectivement les cases 4 et 5. Il s'agit de leur nom et de leur fonction dans toutes les règles d'enregistrement des transactions pour que les produits soient inclus dans les rapports.
Pour inclure des attributs personnalisés dans un rapport sur les revenus récapitulatif après avoir activé la fonctionnalité, utilisez l'API Reporting en ajoutant transactionCustomAttributes à MintCriteria. Consultez les options de configuration des critères.
Configurer un rapport sur les écarts (obsolète)
Suivez la procédure pour configurer un rapport et saisissez les informations suivantes sur la page du rapport :
| Champ | Description |
|---|---|
| Période |
Plage de dates du rapport. Sélectionnez l'une des options ci-dessous :
|
| Packages |
Packages d'API à inclure dans le rapport. Sélectionnez l'une des options ci-dessous :
Le rapport inclut une ligne distincte pour chaque package d'API sélectionné. Pour un rapport récapitulatif, vous pouvez éventuellement cocher "Ne pas afficher (packages)" dans la section "Options d'affichage du récapitulatif". Dans ce cas, le rapport agrège les informations de tous les packages d'API (ou de ceux sélectionnés) et ne liste pas les informations de chaque package d'API séparément. |
| Produits |
Produits d'API à inclure dans le rapport. Sélectionnez l'une des options ci-dessous :
Le rapport inclut une ligne distincte pour chaque produit API sélectionné. Pour un rapport récapitulatif, vous pouvez éventuellement cocher "Ne pas afficher (produits)" dans la section "Options d'affichage du récapitulatif". Dans ce cas, le rapport agrège les informations de tous les produits d'API (ou de ceux sélectionnés) et ne liste pas les informations de chaque produit d'API séparément. |
| Entreprises |
Les entreprises à inclure dans le rapport. Sélectionnez l'une des options ci-dessous :
Le rapport inclut une ligne distincte pour chaque entreprise sélectionnée. Pour un rapport récapitulatif, vous pouvez éventuellement cocher "Ne pas afficher (entreprises)" dans la section "Options d'affichage du récapitulatif". Dans ce cas, le rapport regroupe les informations de toutes les entreprises (ou de celles sélectionnées) et ne liste pas les informations de chaque entreprise sélectionnée séparément. |
| Applications |
Applications à inclure dans le rapport. Sélectionnez l'une des options ci-dessous :
Le rapport inclut une ligne distincte pour chaque application sélectionnée. Pour un rapport récapitulatif, vous pouvez éventuellement cocher "Ne pas afficher (applications)" dans la section "Options d'affichage du récapitulatif". Dans ce cas, le rapport regroupe les informations de toutes les applications (ou de celles sélectionnées) et ne liste pas les informations de chaque application sélectionnée séparément. |
| Devise |
Devise du rapport. Les valeurs valides sont les suivantes :
|
| Options d'affichage du récapitulatif |
Ordre dans lequel les colonnes sont regroupées et affichées dans le rapport. Sélectionnez un nombre qui indique l'ordre relatif de cette section dans le regroupement (1 correspond au premier regroupement). Par exemple, le rapport suivant est d'abord regroupé par packages, puis par produits, puis par développeurs, puis par applications.
Si vous ne souhaitez pas afficher une section, sélectionnez Ne pas afficher, puis sélectionnez les champs restants dans l'ordre. L'ordre est automatiquement mis à jour lorsque vous modifiez l'ordre relatif d'une section ou choisissez de ne pas afficher une section dans le rapport. |
Générer et télécharger un rapport
Une fois que vous avez créé un rapport, vous pouvez télécharger ses résultats au format CSV ou ZIP. Vous pouvez générer le fichier CSV ou ZIP de manière synchrone ou asynchrone.
Pour un rapport synchrone, vous exécutez la demande de rapport et celle-ci est bloquée jusqu'à ce que le serveur de données analytiques fournisse une réponse. Toutefois, étant donné qu'un rapport peut nécessiter le traitement d'une grande quantité de données (par exemple, des centaines de Go), il est possible qu'un rapport synchrone échoue en raison de l'expiration d'un délai.
Un rapport Récapitulatif ne peut être généré qu'en mode synchrone.
Pour un rapport asynchrone, vous exécutez la demande de rapport et récupérez les résultats ultérieurement. Le traitement asynchrone des demandes peut constituer une bonne alternative dans certains cas, par exemple :
- Analyse et création de rapports couvrant de grands intervalles de temps
- Analyse des données avec diverses dimensions de regroupement et d'autres contraintes qui ajoutent de la complexité à la requête
- Gestion des requêtes lorsque vous constatez que les volumes de données ont considérablement augmenté pour certains utilisateurs ou organisations
Le niveau de rapport Détaillé est compatible avec la génération asynchrone.
Pour générer et télécharger un rapport au format CSV ou ZIP, effectuez l'une des opérations suivantes :
- Accédez à la page "Rapports".
- Placez le curseur sur le rapport que vous souhaitez télécharger.
Dans la colonne Modifié, cliquez sur :
- L'icône
ou l'icône 
(pour un rapport récapitulatif). Le rapport est enregistré de manière synchrone dans un fichier CSV ou ZIP. - Envoyer le job (pour un rapport détaillé). Le job asynchrone démarre.
Surveillez l'état du job dans la colonne Modifié.
L'icône de disque s'affiche lorsque le rapport est prêt à être téléchargé :
- Une fois le job terminé, cliquez sur l'icône de disque pour télécharger le rapport.
- L'icône
Vous trouverez ci-dessous un exemple de fichier CSV pour un rapport de facturation récapitulatif.
Modifier un rapport
Pour modifier un rapport :
- Accédez à la page "Rapports".
- Placez le curseur sur le rapport que vous souhaitez modifier, puis cliquez sur
dans le menu d'actions. - Mettez à jour la configuration du rapport si nécessaire.
- Cliquez sur Mettre à jour le rapport pour enregistrer la configuration modifiée du rapport.
Supprimer un rapport
Pour supprimer un rapport :
- Accédez à la page "Rapports".
- Placez le curseur sur le rapport que vous souhaitez supprimer.
- Cliquez sur
dans le menu d'actions.
Gérer les rapports sur la monétisation à l'aide de l'API
Les sections suivantes décrivent comment gérer les rapports de monétisation à l'aide de l'API.
Configurer un rapport à l'aide de l'API
Pour configurer un rapport pour l'ensemble d'une organisation, envoyez une requête POST à /organizations/{org_name}/report-definitions.
Pour configurer un rapport pour un développeur spécifique, envoyez une requête POST à /organizations/{org_name}/developers/{dev_id}/report-definitions, où {dev_id} est l'identifiant du développeur.
Lorsque vous envoyez la demande, vous devez spécifier le nom et le type du rapport. Le type est l'un des suivants : BILLING, REVENUE, VARIANCE (obsolète) ou PREPAID_BALANCE. Vous pouvez également spécifier des critères dans la propriété mintCriteria pour configurer davantage le rapport. Vous pouvez spécifier un large éventail de critères. Vous bénéficiez ainsi d'une grande flexibilité pour configurer le rapport.
Voici quelques exemples de critères que vous pouvez spécifier :
- Mois de facturation du rapport sur la facturation ou le solde prépayé
- Pour un rapport sur les revenus, le type de transactions couvertes dans le rapport, comme les transactions d'achat, les transactions de débit et les remboursements
- Pour un rapport sur la réserve prépayée, il s'agit du développeur auquel le rapport s'applique.
- Pour un rapport sur les revenus, les groupes de produits d'API (ou packages d'API), les produits, les plans tarifaires et les applications auxquels le rapport s'applique
- Devise applicable au rapport sur les revenus ou les écarts
- Pour les rapports sur la facturation, le solde prépayé ou les revenus, indiquez si le rapport est récapitulatif ou détaillé.
- Pour un rapport récapitulatif sur les revenus, incluez des attributs de transaction personnalisés dans le rapport.
Pour obtenir la liste complète des critères de rapport, consultez Options de configuration des rapports.
Par exemple, la commande suivante crée un rapport sur les revenus qui récapitule l'activité des transactions pour le mois de juillet 2015. Le rapport inclut différents types de transactions spécifiés dans la propriété transactionTypes. Il s'applique spécifiquement au bundle de produits Payment API et au produit Payment API. Étant donné qu'aucun développeur ni aucune application spécifiques ne sont indiqués dans la définition du rapport, celui-ci s'applique à tous les développeurs et à toutes les applications. Étant donné que la propriété currencyOption est définie sur LOCAL, chaque ligne du rapport s'affiche dans la devise du plan tarifaire applicable. De plus, la propriété groupBy spécifie que les colonnes du rapport seront regroupées dans l'ordre suivant : PACKAGE, PRODUCT, DEVELOPER, APPLICATION et RATEPLAN (inclut le nom et l'ID du forfait dans le rapport).
$ curl -H "Content-Type: application/json" -X POST -d \
'{
"name": "July 2015 revenue report",
"description": " July 2015 revenue report for Payment product",
"type": "REVENUE",
"mintCriteria":{
"fromDate":"2015-07-01 00:00:00",
"toDate":"2015-08-01 13:35:00",
"showTxDetail":true,
"showSummary":true,
"transactionTypes":[
"PURCHASE",
"CHARGE",
"REFUND",
"CREDIT",
"SETUPFEES",
"TERMINATIONFEES",
"RECURRINGFEES"
],
"monetizationPackageIds":[
"payment"
],
"productIds":[
"payment"
],
"currencyOption":"LOCAL",
"groupBy":[
"PACKAGE",
"PRODUCT",
"DEVELOPER",
"APPLICATION",
"RATEPLAN"
]
}
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password
La commande suivante crée un rapport de facturation détaillé qui affiche l'activité d'un développeur DEV FIVE pour le mois de juin 2015.
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"name": "June billing report, DEV FIVE",
"description": "June billing report, DEV FIVE",
"type": "BILLING",
"mintCriteria":{
"billingMonth": "JUNE",
"billingYear": 2015,
"showTxDetail":true,
"showSummary":false,
"currencyOption":"LOCAL"
},
"devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"myorg"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \
-u email:password
Afficher les configurations de rapports à l'aide de l'API
Vous pouvez afficher une configuration de rapport spécifique ou toutes les configurations de rapport d'une organisation. Vous pouvez également afficher les configurations de rapport pour un développeur spécifique.
Pour afficher une configuration de rapport spécifique pour une organisation, envoyez une requête GET à /organizations/{org_name}/report-definitions/{report_definition_id}, où {report_definition_id} correspond à l'identification de la configuration de rapport spécifique (l'ID est renvoyé dans la réponse lorsque vous créez la configuration de rapport). Exemple :
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/1f7fa53b-de5a-431d-9438-62131e1396c5" \
-u email:password
Pour afficher toutes les configurations de rapport de l'organisation, envoyez une requête GET à /organizations/{org_name}/report-definitions.
Vous pouvez transmettre les paramètres de requête suivants pour filtrer et trier les résultats :
| Paramètre de requête | Description |
|---|---|
all |
Indicateur permettant de spécifier s'il faut renvoyer tous les groupes de produits d'API. Si la valeur est définie sur false, le nombre de groupes de produits d'API renvoyés par page est défini par le paramètre de requête size. Valeur par défaut : false. |
size |
Nombre de groupes de produits d'API renvoyés par page. Valeur par défaut : 20. Si le paramètre de requête all est défini sur true, ce paramètre est ignoré. |
page |
Numéro de la page que vous souhaitez renvoyer (si le contenu est paginé). Si le paramètre de requête all est défini sur true, ce paramètre est ignoré. |
sort |
Champ selon lequel trier les informations. Si le paramètre de requête all est défini sur true, ce paramètre est ignoré. La valeur par défaut est UPDATED:DESC. |
Par exemple, la requête suivante renvoie les configurations de rapport pour l'organisation et limite la récupération à un maximum de cinq configurations de rapport :
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \
-u email:password
La réponse doit se présenter comme suit (seule une partie de la réponse est affichée) :
{ "reportDefinition" : [ { "description" : "Test revenue report", "developer" : null, "id" : "1f7fa53b-de5a-431d-9438-62131e1396c5", "lastModified" : "2015-08-27 15:44:03", "mintCriteria" : { "asXorg" : false, "currencyOption" : "LOCAL", "fromDate" : "2015-07-01 00:00:00", "groupBy" : [ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ], "monetizationPackageIds" : [ "payment" ], "productIds" : [ "payment" ], "showRevSharePct" : false, "showSummary" : true, "showTxDetail" : true, "showTxType" : false, "toDate" : "2015-08-01 00:05:00", "transactionTypes" : [ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ] }, "name" : "Test revenue report", "organization" : { ... }, "type" : "REVENUE" }, { "description" : "June billing report, DEV FIVE", "developer" : null, "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb", "lastModified" : "2015-08-27 17:13:20", "mintCriteria" : { "asXorg" : false, "billingMonth" : "JUNE", "billingYear" : 2015, "currencyOption" : "LOCAL", "showRevSharePct" : false, "showSummary" : false, "showTxDetail" : true, "showTxType" : false }, "name" : "June billing report, DEV FIVE", "organization" : { ... }, "type" : "BILLING" } ], "totalRecords" : 2 }
Pour afficher les configurations de rapport d'un développeur spécifique, envoyez une requête GET à /organizations/{org_name}/developers/{dev_id}/report-definitions, où {dev_id} est l'identifiant du développeur. Lorsque vous envoyez la requête, vous pouvez spécifier les paramètres de requête décrits ci-dessus pour filtrer et trier les données.
Par exemple, la commande suivante renvoie les configurations de rapport pour un développeur spécifique et trie la réponse par nom de rapport :
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xUreport-definitions?sort=name" \
-u email:password
Mettre à jour une configuration de rapport à l'aide de l'API
Pour mettre à jour une configuration de rapport, envoyez une requête PUT à /organizations/{org_name}/report-definitions/{report_definition_id}, où {report_definition_id} correspond à l'identification de la configuration de rapport spécifique. Lorsque vous effectuez la mise à jour, vous devez spécifier dans le corps de la requête les valeurs de configuration mises à jour et l'ID de la configuration du rapport. Par exemple, la requête suivante met à jour le rapport pour qu'il devienne un rapport récapitulatif (les propriétés mises à jour sont mises en évidence) :
$ curl -H "Content-Type: application/json" -X PUT -d \
'{
"id": "fedac696-ce57-469b-b62c-a77b535fd0eb",
"name": "June billing report, DEV FIVE",
"description": "June billing report, DEV FIVE",
"type": "BILLING",
"mintCriteria":{
"billingMonth": "JUNE",
"billingYear": 2015,
"showTxDetail":false,
"showSummary":true
}
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password
La réponse doit se présenter comme suit (seule une partie de la réponse est affichée) :
{ "description" : "June billing report, DEV FIVE", "developer" : null, "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb", "lastModified" : "2015-08-27 17:47:29", "mintCriteria" : { "asXorg" : false, "billingMonth" : "JUNE", "billingYear" : 2015, "showRevSharePct" : false, "showSummary" : true, "showTxDetail" : false, "showTxType" : false }, "name" : "June billing report, DEV FIVE", "organization" : { ... }, "type" : "BILLING" }
Supprimer une configuration de rapport à l'aide de l'API
Pour supprimer une configuration de rapport, envoyez une requête DELETE à /organizations/{org_namer}/report-definitions/{report_definition_id}, où {report_definition_id} correspond à l'identification de la configuration de rapport à supprimer.
Exemple :
$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password
Générer un rapport à l'aide de l'API
Une fois que vous avez configuré un rapport, vous pouvez le générer au format CSV (valeurs séparées par une virgule) pour l'afficher.
Pour générer un rapport, envoyez une requête POST à organizations/{org_id}/{report_type}, où {report_type} spécifie le type de rapport que vous souhaitez générer. Voici les types :
billing-reportsrevenue-reportsprepaid-balance-reportsvariance-reports
Par exemple, pour générer un rapport sur la facturation, envoyez une requête POST à organizations/{org_name}/billing-reports.
Dans le corps de la requête (pour tout type de rapport), spécifiez les critères de recherche du rapport. Utilisez les propriétés mintCriteria pour spécifier les critères de recherche. Pour en savoir plus, consultez Options de configuration des critères.
Par exemple, la requête suivante recherche un rapport sur les revenus en fonction de différents critères, tels que les dates de début et de fin du rapport, et les types de transactions.
$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
"fromDate":"2015-07-01 00:00:00",
"toDate":"2015-08-01 13:35:00",
"showTxDetail":true,
"showSummary":true,
"transactionTypes":[
"PURCHASE",
"CHARGE",
"REFUND",
"CREDIT",
"SETUPFEES",
"TERMINATIONFEES",
"RECURRINGFEES"
],
"currencyOption":"LOCAL",
"groupBy":[
"PACKAGE",
"PRODUCT",
"DEVELOPER",
"APPLICATION",
"RATEPLAN"]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password
Si le rapport sur les revenus est trouvé, il est généré au format CSV. Voici un exemple de résultat de rapport :
Reporting Period:,From:,2015-07-01, To:,2015-07-31 API Product:,All Developer:,All Application:,All Currency:,Local Type of Report:,Summary Revenue Report Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate, Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Inclure des attributs personnalisés de développeur dans les rapports sur les revenus à l'aide de l'API
Pour les rapports sur les revenus uniquement, vous pouvez inclure des attributs personnalisés dans le rapport si l'attribut personnalisé est défini pour le développeur. Vous définissez des attributs personnalisés lorsque vous ajoutez des développeurs à votre organisation, comme décrit dans Gérer les développeurs d'applications.
Pour inclure des attributs personnalisés dans un rapport sur les revenus, envoyez une requête POST à organizations/{org_name}/revenue-reports et incluez le tableau devCustomAttributes dans le corps de la requête :
"devCustomAttributes": [
"custom_attribute1",
"custom_attribute2",
...
]Remarque : Ne spécifiez pas les attributs prédéfinis MINT_* et ADMIN_* dans le tableau devCustomAttributes.
Par exemple, l'exemple suivant inclut trois attributs personnalisés, BILLING_TYPE, SFID et ORG_EXT, dans le rapport (s'ils sont définis pour le développeur) :
$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \ '{ "fromDate":"2015-07-01 00:00:00", "toDate":"2015-08-01 13:35:00", "showTxDetail":true, "showSummary":true, "transactionTypes":[ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ], "currencyOption":"LOCAL", "groupBy":[ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ], "devCustomAttributes": [ "BILLING_TYPE", "SFID", "ORG_EXT" ] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \ -u email:password
Vous trouverez ci-dessous un exemple de résultat de rapport incluant les valeurs des deux attributs personnalisés :
Reporting Period:,From:,2015-07-01, To:,2015-07-31 API Product:,All Developer:,All Application:,All Currency:,Local Type of Report:,Summary Revenue Report Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,BILLING_TYPE,SFID,ORG_EXT Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Signaler l'activité des transactions à l'aide de l'API
Vous pouvez afficher l'activité des transactions d'une organisation en envoyant une requête POST à /organizations/{org_name}/transaction-search. Lorsque vous envoyez la demande, vous devez spécifier des critères pour la récupération. Voici quelques exemples de critères que vous pouvez spécifier :
- ID d'un ou de plusieurs produits d'API pour lesquels des transactions ont été émises.
- Mois et année de facturation des transactions.
- Développeur(s) ayant émis la transaction.
- Type de transaction, comme "purchase" (achat) et "setupfees" (frais d'installation).
- État de la transaction (par exemple, réussie ou échouée).
Pour obtenir la liste complète des critères, consultez Options de configuration des critères.
Par exemple, la requête suivante renvoie les transactions émises par un développeur spécifique pour le mois de facturation de juin 2015 :
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"billingMonth": "JUNE",
"billingYear": 2015,
"devCriteria": [{
"id": "RtHAeZ6LtkSbEH56",
"orgId":"myorg"}],
"transactionTypes": ["PURCHASE", "CHARGE", "SETUPFEES"],
"transactionStatus": ["SUCCESS", "FAILED"]
}'
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transaction-search \
-u email:password
Vous pouvez également déterminer quelles applications, quels développeurs, quels packs de produits d'API ou quels produits d'API ont enregistré une activité de transaction au cours d'une période donnée. Vous pouvez afficher ces informations séparément pour chaque type d'objet. Par exemple, vous pouvez afficher des informations spécifiques sur les applications qui accèdent aux API dans vos packs de produits d'API monétisés au cours d'une période donnée.
Pour afficher des informations sur l'activité des transactions, envoyez une requête GET à l'une des ressources suivantes :
| Ressource | Renvoie |
|---|---|
/organizations/{org_name}/applications-with-transactions |
Applications avec transactions |
/organizations/{org_name}/developers-with-transactions |
Développeurs avec transactions |
/organizations/{org_name}/products-with-transactions |
Produits avec transactions |
/organizations/{org_name}/packages-with-transactions |
Regroupements de produits d'API (ou packages d'API) avec transactions |
Lorsque vous envoyez la requête, vous devez spécifier une date de début et une date de fin pour la plage de dates en tant que paramètres de requête. Par exemple, la requête suivante renvoie les développeurs ayant effectué des transactions au cours du mois d'août 2015.
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers-with-transactions?START_DATE=2015-08-01&END_DATE=2015-08-31" \
-u email:password
La réponse doit se présenter comme suit (seule une partie de la réponse est affichée) :
{ "developer" : [ { "address" : [ { "address1" : "Dev Five Address", "city" : "Pleasanton", "country" : "US", "id" : "0917f15f-9521-4e69-9376-07aa7b7b32ca", "isPrimary" : true, "state" : "CA", "zip" : "94588" } ], "approxTaxRate" : 0.0900, "billingType" : "POSTPAID", "broker" : false, "developerRole" : [ ], "email" : "dev5@myorg.com", "hasSelfBilling" : false, "id" : "tJZG6broTpGGGeLV", "legalName" : "DEV FIVE", "name" : "Dev Five", "organization" : { ... }, "registrationId" : "dev5", "status" : "ACTIVE", "type" : "UNTRUSTED" }, { "address" : [ { "address1" : "Dev Seven Address", "city" : "Pleasanton", "country" : "US", "id" : "f86d8c9f-6ed1-4323-b050-6adf494096c9", "isPrimary" : true, "state" : "CA", "zip" : "94588" } ], "approxTaxRate" : 0.0900, "billingType" : "POSTPAID", "broker" : false, "developerRole" : [ ], "email" : "dev7@myorg.com", "hasSelfBilling" : false, "id" : "VI3l8m8IPAvJTvjS", "legalName" : "DEV SEVEN", "name" : "Dev Seven", "organization" : { ... }, "registrationId" : "dev7", "status" : "ACTIVE", "type" : "UNTRUSTED" }, ... ] }
Options de configuration des rapports pour l'API
Les options de configuration de rapport suivantes sont disponibles pour l'API :
| Nom | Description | Par défaut | Obligatoire ? |
|---|---|---|---|
name |
Nom du rapport. |
N/A | Oui |
description |
Description du rapport. |
N/A | Non |
mintCriteria |
Critères de configuration d'un rapport. Pour en savoir plus, consultez les options de configuration des critères. |
N/A | Non |
type |
Type de rapport. Les valeurs possibles sont les suivantes :
|
N/A | Oui |
Options de configuration des critères
Les options de configuration suivantes sont disponibles pour les rapports via la propriété mintCriteria :
| Nom | Description | Par défaut | Obligatoire ? |
|---|---|---|---|
appCriteria |
ID et organisation pour une application spécifique à inclure dans le rapport. Si cette propriété n'est pas spécifiée, toutes les applications sont incluses dans le rapport. |
N/A | Non |
billingMonth |
Remarque : Cette propriété n'est pas valide pour les rapports sur les revenus. Mois de facturation du rapport, tel que "JULY". |
ND | Oui |
billingYear |
Remarque : Cette propriété n'est pas valide pour les rapports sur les revenus. Année de facturation du rapport, telle que 2015. |
ND | Oui |
currCriteria |
ID et organisation pour une devise spécifique à inclure dans le rapport. Si cette propriété n'est pas spécifiée, toutes les devises acceptées sont incluses dans le rapport. |
N/A | Non |
currencyOption |
Devise du rapport. Les valeurs valides sont les suivantes :
|
N/A | Non |
devCriteria |
ID du développeur (adresse e-mail) et nom de l'organisation d'un développeur spécifique à inclure dans le rapport. Si cette propriété n'est pas spécifiée, tous les développeurs sont inclus dans le rapport. Exemple : "devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"my_org"}
]
|
N/A | Non |
devCustomAttributes |
Remarque : Cette propriété ne s'applique qu'aux rapports sur les revenus. Attributs personnalisés à inclure dans le rapport, s'ils sont définis pour un développeur. Exemple : "devCustomAttributes": [
"custom_attribute1",
"custom_attribute2",
...
]Remarque : Ne spécifiez pas les attributs prédéfinis |
N/A | Non |
fromDate |
Remarque : Cette propriété ne s'applique qu'aux rapports sur les revenus, les écarts et l'activité des transactions. Date de début du rapport, selon le fuseau UTC. |
N/A | Obligatoire pour les rapports sur les revenus, mais pas pour les autres types de rapports. |
groupBy |
Ordre dans lequel les colonnes sont regroupées dans le rapport. Les valeurs valides sont les suivantes :
|
N/A | Non |
monetizationPackageId |
ID d'un ou de plusieurs groupes de produits d'API à inclure dans le rapport. Si cette propriété n'est pas spécifiée, tous les bundles de produits d'API sont inclus dans le rapport. Remarque : Cette propriété n'est pas valide lorsque vous consultez l'activité des transactions ( |
N/A | Non |
pkgCriteria |
ID et organisation pour un bundle de produits d'API spécifique à inclure dans le rapport. Si cette propriété n'est pas spécifiée, tous les bundles de produits d'API sont inclus dans le rapport. Cette propriété peut être spécifiée à la place de la propriété Remarque : Cette propriété n'est pas valide lorsque vous consultez l'activité des transactions ( |
N/A | Non |
prevFromDate |
Remarque : Cette propriété ne s'applique qu'aux rapports sur les écarts. Date de début d'une période précédente au format UTC. Permet de créer un rapport pour une période précédente afin de le comparer à un rapport actuel. |
N/A | Non |
prevToDate |
Remarque : Cette propriété ne s'applique qu'aux rapports sur les écarts. Date de fin d'une période précédente au format UTC. Permet de créer un rapport pour une période précédente afin de le comparer à un rapport actuel. |
N/A | Non |
prodCriteria |
ID et organisation pour un produit d'API spécifique à inclure dans le rapport. Si cette propriété n'est pas spécifiée, tous les produits d'API sont inclus dans le rapport. Cette propriété peut être spécifiée à la place de la propriété Remarque : Cette propriété n'est pas valide lorsque vous consultez l'activité des transactions ( |
N/A | Non |
productIds |
ID d'un ou de plusieurs produits d'API à inclure dans le rapport. Si cette propriété n'est pas spécifiée, tous les produits d'API sont inclus dans le rapport. Les ID de produits d'API doivent être spécifiés au format |
N/A | Non |
pricingTypes |
Type de tarification du plan tarifaire à inclure dans le rapport. Les valeurs valides sont les suivantes :
Si cette propriété n'est pas spécifiée, les plans tarifaires de tous les types de tarification sont inclus dans le rapport. |
N/A | Non |
ratePlanLevels |
Type de plan tarifaire à inclure dans le rapport. Les valeurs valides sont les suivantes :
Si cette propriété n'est pas spécifiée, les plans tarifaires standard et spécifique au développeur sont inclus dans le rapport. |
N/A | Non |
showRevSharePct |
Indicateur qui spécifie si le rapport affiche les pourcentages de partage des revenus. Les valeurs valides sont les suivantes :
|
N/A | Non |
showSummary |
Indicateur qui précise si le rapport est un récapitulatif. Les valeurs valides sont les suivantes :
|
N/A | Non |
showTxDetail |
Remarque : Cette propriété ne s'applique qu'aux rapports sur les revenus. Indicateur qui spécifie si le rapport affiche des informations au niveau des transactions. Les valeurs valides sont les suivantes :
|
N/A | Non |
showTxType |
Indicateur qui spécifie si le rapport affiche le type de chaque transaction. Les valeurs valides sont les suivantes :
|
N/A | Non |
toDate |
Remarque : Cette propriété ne s'applique qu'aux rapports sur les revenus, les écarts et l'activité des transactions. Date de fin du rapport en UTC. Le rapport inclut les données collectées jusqu'à la fin de la journée précédant la date spécifiée. Les données collectées à la date de fin spécifiée seront exclues du rapport. Par exemple, si vous souhaitez que votre forfait expire le 31 décembre 2016, vous devez définir la valeur "toDate" sur "2017-01-01". Dans ce cas, le rapport inclura les données jusqu'à la fin de la journée du 31 décembre 2016, mais pas celles du 1er janvier 2017. |
N/A | Obligatoire pour les rapports sur les revenus, mais pas pour les autres types de rapports. |
transactionStatus |
État des transactions à inclure dans le rapport. Les valeurs valides sont les suivantes :
|
N/A | Non |
transactionCustomAttributes |
Attributs de transaction personnalisés à inclure dans les rapports récapitulatifs sur les revenus. Vous devez activer cette fonctionnalité dans votre organisation. Consultez Inclure des attributs de transaction personnalisés dans les rapports récapitulatifs sur les revenus. |
N/A | Non |
transactionTypes |
Type de transactions à inclure dans le rapport. Les valeurs valides sont les suivantes :
Si cette propriété n'est pas spécifiée, tous les types de transactions sont inclus dans le rapport. |
N/A | Non |