API OVHcloud : configuration de l'analyse des données de facturation

Objectif

Ce guide fournit des instructions pas à pas pour configurer plusieurs endpoints de l'API Billing d'OVHcloud. Vous apprendrez à récupérer les données de facturation et à les intégrer dans vos applications pour un suivi financier précis et simplifié.

Vue d'ensemble

L'API OVHcloud prend en charge plusieurs configurations d'endpoints, vous permettant de récupérer et d'intégrer des données provenant de ressources interconnectées. Ce guide propose un parcours complet pour configurer et utiliser les endpoints de l'API Billing d'OVHcloud. En suivant ces étapes, vous serez en mesure de récupérer, traiter et analyser vos informations de facturation de manière programmatique et efficace.

Prérequis

Avant de commencer, assurez-vous de disposer de :

• Un compte OVHcloud actif avec accès à la facturation
• Des identifiants d'API, à savoir :
  • Application Key (App Key)
  • Application Secret (App Secret)
  • Consumer Key
• Un accès au Developer Portal de l'API OVHcloud
• Une compréhension de base des interactions avec les endpoints d'API

Configuration pas à pas des endpoints de facturation

1. Initialiser la connexion à l'API

Configurez votre connexion à l'API OVHcloud en suivant le processus de configuration de l'authentification détaillé dans la documentation du connecteur API OVHcloud. Cela implique d'obtenir et de saisir de façon sécurisée votre Application Key, votre Application Secret et votre Consumer Key via l'interface utilisateur du connecteur. Pour des instructions complètes sur l'obtention et la configuration de ces identifiants, consultez la section API Connection Details de la documentation du connecteur.

2. Définir les endpoints de facturation

2.1. Récupérer les ID des factures du compte

• Endpoint : /me/bill
• Objectif : récupérer une liste de tous les ID de factures de votre compte

Étapes :

1. Sélectionnez « Add New Endpoint » dans le connecteur
2. Saisissez /me/bill comme chemin d'endpoint
3. Configurez les paramètres de requête (par ex. filtrage par année) - pour cet exemple, nous avons utilisé la clé date.from et la valeur 2023, pour récupérer les enregistrements de l'année 2023.
4. Assurez-vous que l'endpoint a un nom unique bills_ids_from_2023
5. Cliquez sur « Confirm » puis « Save »

Valider les données de l'endpoint

1. Naviguez vers l'onglet Analyzer
2. Extrayez les métadonnées du nouvel endpoint
3. Vérifiez que les enregistrements de factures sont correctement récupérés

2.2. Récupérer les ID des détails des factures du compte

• Endpoint : /me/bill/{billId}/details
• Objectif : récupérer la liste des ID pour chaque ligne de détail de facture

Étapes :

1. Cliquez sur « Add Endpoint »
2. Saisissez /me/bill/{billId}/details comme chemin d'endpoint
3. Configurez la sélection multiple d'endpoints
4. Reliez à l'endpoint des factures précédent
5. Sélectionnez {billId} comme paramètre de chemin
6. Assurez-vous que l'endpoint a un nom unique bills_details_ids_from_2023
7. Enregistrez la configuration

En revenant au modal principal en cliquant sur l'onglet Settings, vous remarquerez que les champs paramètre de chemin et endpoint ne sont désormais plus modifiables. Cela s'explique par le fait que leurs valeurs sont dérivées d'un autre endpoint. Si vous devez apporter des modifications, retournez simplement dans la section des endpoints multiples et sélectionnez « No multiple endpoint » dans le menu déroulant de sélection d'endpoint.

2.3. Récupérer les détails des factures du compte

• Endpoint : /me/bill/{billId}/details/{detailsID}
• Objectif : récupérer les détails de chaque ligne de facture

Étapes :

1. Cliquez sur « Add Endpoint »
2. Saisissez /me/bill/{billId}/details/{detailsID} comme chemin d'endpoint
3. Configurez la sélection multiple d'endpoints
4. Reliez à l'endpoint précédent des ID de détails de factures
5. Sélectionnez {billId} et {detailsID} comme paramètres de chemin
6. Assurez-vous que l'endpoint a un nom unique bills_details_from_2023
7. Enregistrez la configuration

2.4. Récupérer les ID des services

• Endpoint : /services
• Objectif : récupérer les ID de tous les services de vos comptes

Étapes :

1. Cliquez sur « Add Endpoint »
2. Saisissez /services comme chemin d'endpoint
3. Assurez-vous que l'endpoint a un nom unique services_ids
4. Enregistrez la configuration

2.5. Récupérer les informations des services

• Endpoint : /services/{serviceId}
• Objectif : récupérer les informations sur vos services pour enrichir les données du pipeline

Étapes :

1. Cliquez sur « Add Endpoint »
2. Saisissez /services/{serviceId} comme chemin d'endpoint
3. Configurez la sélection multiple d'endpoints
4. Reliez à l'endpoint précédent des ID de services
5. Sélectionnez {serviceId} comme paramètre de chemin
6. Assurez-vous que l'endpoint a un nom unique services
7. Enregistrez la configuration

La configuration des endpoints est maintenant terminée, vous devriez voir ce qui suit :

3. Extraction des métadonnées

Les endpoints étant maintenant établis, naviguez vers l'outil analyzer au sein des Connectors. Une fois là, sélectionnez les endpoints que vous venez de configurer. Laissez au système le temps d'initier et de terminer les jobs de traitement associés à ces endpoints.

3.1. Reformater les données

Les données extraites des sources peuvent être modifiées pour correspondre exactement au format souhaité, ou pour les répartir en buckets via les blueprints. C'est ce que nous allons faire pour 2 endpoints :

• bills_details_from_2023
• services

3.1.1. Reformater les détails des factures

Le champ periodstart provenant de l'API est une valeur au format YYYY-MM-DD, où le DD peut être n'importe quel jour du mois, selon le jour où vous avez acheté le service. Nous allons utiliser un blueprint pour remplacer ce jour et le fixer au premier jour de chaque mois.

Cliquez en haut à droite de l'analyse de données sur New Rule, puis sélectionnez Date format.

Vous êtes maintenant sur la configuration du blueprint, veuillez remplir comme suit :

• Attribute : periodstart
• Current Date Format : %Y-%m-%d
• Replace by : %Y-%m-01
• Condition : Is not null

Cliquez sur confirm, vous pouvez maintenant voir que periodstart possède 1 blueprint.

3.1.2. Reformater les services

De nombreux champs datetime provenant de l'endpoint services contiennent l'information de fuseau horaire. Nous souhaitons supprimer cette information de fuseau horaire de la date, nous allons donc reformater toutes les dates avec le blueprint Date Format, comme vu précédemment.

Allez sur l'endpoint services, cliquez sur New rule, sélectionnez Date format.

Vous êtes maintenant sur la configuration du blueprint, veuillez remplir comme suit :

• Attribute : billing_next_billingdate
• Current Date Format : %Y-%m-%dT%H:%M:%S%z
• Replace by : %Y-%m-%dT%H:%M:%S
• Condition : All

Vous pouvez répéter l'opération pour les attributs suivants :

• billing_expirationdate
• billing_lifecycle_current_terminationdate
• billing_lifecycle_current_creationdate
• billing_renew_current_nextdate

4. Importer vos données dans le lakehouse

Les sources de données étant maintenant configurées, nous pouvons procéder à la construction des tables. Vous pouvez aller dans le Lakehouse Manager, puis la section Tables. Cliquez sur le + puis sur Create from a Connectors source.

La première table sera peuplée à l'aide de la source de données bill_details_from_2023. Vous pouvez renommer la table après avoir cliqué sur next en raw_bills_details, puis cliquer sur create.

Vous pouvez maintenant également importer les services dans une table dédiée :

5. Ajouter un tag sur les services

Afin de catégoriser les dépenses, nous souhaitons catégoriser les services avec des tags, qui peuvent représenter soit vos environnements techniques (par ex. production, dev), soit les départements de votre entreprise, ou même vos clients.

Afin d'extraire la première liste de services à catégoriser, vous pouvez aller dans la section Explorer à l'intérieur du Lakehouse Manager.

Dans Data, sélectionnez domain, cliquez sur select et remplacez par select_distinct, puis cliquez sur RUN.

Vous devriez obtenir un résultat comme celui-ci :

Vous pouvez maintenant cliquer sur Download puis As a CSV. Vous disposerez alors d'un premier fichier CSV contenant toutes les ressources à taguer. Vous pouvez l'ouvrir, renommer la colonne select_distinct_domain en domain, puis ajouter une seconde colonne tag et, pour chaque domaine que vous souhaitez taguer, ajouter la valeur souhaitée. Vous devriez obtenir un fichier CSV comme celui-ci :

Il est maintenant temps d'ajouter une nouvelle source de données dans les Connectors avec ce fichier CSV, et de créer une table dans le lakehouse à partir de celui-ci. Vous pouvez aller dans Connectors -> sources -> New Source -> File Upload. Vous pouvez nommer votre nouvelle source Domains Tagged, ajouter le fichier CSV et cliquer sur le bouton create.

Vous pouvez maintenant retourner sur l'analyzer pour vérifier que les données sont correctement évaluées, et ajouter également un blueprint sur les tags, afin de remplacer les valeurs vides par unknown. Cliquez sur new rule, Replace By. Remplissez le formulaire comme suit :

• Attribute : tag
• Replace by : unknown
• Condition : Equal
• Equal : laisser vide

Confirmez le blueprint.

Vous pouvez maintenant retourner dans le Lakehouse Manager et la section Tables, et créer une table à partir de cette nouvelle source. Veillez à nommer la table domains_tags.

6. Créer une table d'agrégation

Nous disposons maintenant de nombreuses informations sur nos services, leurs factures ainsi que leurs tags. Nous allons construire une table d'agrégation pour relier toutes ces informations entre elles.

Dans la section Lakehouse Manager et Tables, cliquez sur le + puis sur Create a new empty table. Nommez-la : enriched_bills_details.

Vous devriez maintenant disposer des tables suivantes dans votre lakehouse :

• services
• domains_tags
• raw_bills_details
• enriched_bills_details

Nous allons glisser certains champs depuis les tables que nous avons créées à partir des sources, et les déposer dans enriched_bills_details. Les champs à glisser-déposer sont :

• Depuis raws_bills_details :
  • domain
  • periodstart
  • totalprice_value
• Depuis domains_tags :
  • tag
• Depuis services :
  • resource_displayname
  • resource_product_name
  • resource_product_description

Votre table enriched_bills_details devrait maintenant ressembler à ceci :

Vous pouvez maintenant cliquer sur Build pour construire cette nouvelle table. Maintenant que nous avons la structure de cette nouvelle table, nous allons créer un job pour extraire les données des 3 tables précédentes et les charger dans cette nouvelle table. Nous devons maintenant aller dans la section Data Processing Engine et Actions. Cliquez sur New Action et sélectionnez Aggregate.

Nous allons maintenant mapper des champs provenant de différentes tables vers enriched_bills_details ; pour cela, vous devez d'abord sélectionner les sources et la destination :

• Sources :
  • raws_bills_details
  • services
  • domains_tags
• Destination : enriched_bills_details

Pour les sources, nous devons expliquer comment les données des 3 tables sont liées entre elles via la syntaxe SQL JOIN. Nous allons donc ajouter les jointures suivantes :

• Entre raws_bills_details et services :

raws_bills_details.domain = services.resource_name

• Entre raws_bills_details et domains_tags :

raws_bills_details.domain = domains_tags.domain

Pour terminer l'aggregate, nous devons configurer comment sélectionner et regrouper les attributs des tables dans enriched_bills_details. Mappez les attributs comme indiqué dans la capture d'écran ci-dessous.

Vous pouvez maintenant créer l'aggregate, et lancer l'action.

7. Préparer les requêtes et construire le Dashboard

Maintenant que toutes les données sont prêtes à être exploitées, nous pouvons aller dans l'Analytics Manager et Queries. Créons quelques requêtes.

Évolution des coûts par rapport au mois précédent

Pour la requête :

• Data : totalprice_value sum FROM enriched_bills_details
• Scale : periodstart
• Order by : periodstart desc

Pour la visualisation :

• En tant que metric
• Personnalisation : activer tous les boutons bascule

Répartition des coûts par tag

Pour la requête :

• Data : totalprice_value sum FROM enriched_bills_details
• Scale : tag

Pour la visualisation :

• En tant que pie chart
• Personnalisation :
  • Show category
  • Show % of total
  • Position : outside
  • Hide legend

Répartition des coûts par produit

Pour la requête :

• data : totalprice_value sum FROM enriched_bills_details
• scale : resource_displayname

Pour la visualisation :

• En tant que pie chart
• Personnalisation :
  • Show category
  • Show % of total
  • Position : outside
  • Hide legend

Répartition des coûts par type de produit

Pour la requête :

• Data : totalprice_value sum FROM enriched_bills_details
• Scale : resource_productdescription

Pour la visualisation :

• En tant que pie chart
• Personnalisation :
  • Show category
  • Show % of total
  • Position : outside
  • Hide legend

Coût par mois et par tag

Pour la requête :

• Data : totalprice_value sum FROM enriched_bills_details
• Scale : periodstart resource_product_description tag
• Filter on : periodstart Not null
• Order by : periodstart asc

Pour la visualisation :

• En tant que bar charts
• Personnalisation :
  • Display stacked
  • Hide legend
  • X-axis : regroup by periodstart

Créer le Dashboard

Vous pouvez maintenant aller dans la section dashboard, en créer un nouveau et y placer tous vos graphiques en cliquant sur le bouton +.

En haut du dashboard, vous pouvez également ajouter des filtres pour faciliter la navigation dans les données. Envisagez d'ajouter les filtres suivants :

• periodstart
• tag
• resource_product_description

Conclusion

En suivant ces étapes, vous pouvez configurer et utiliser efficacement l'endpoint de l'API Billing d'OVHcloud pour récupérer, traiter et analyser vos informations de facturation de manière programmatique.

Aller plus loin

Si vous avez besoin d'une formation ou d'une assistance technique pour la mise en oeuvre de nos solutions, contactez votre commercial ou cliquez sur ce lien pour obtenir un devis et demander une analyse personnalisée de votre projet à nos experts de l’équipe Professional Services.

Posez vos questions, faites-nous part de vos commentaires et interagissez directement avec l’équipe qui développe la Data Platform sur le canal Discord dédié.

Si vous avez besoin d'une assistance concernant vos services OVHcloud, créez une demande depuis notre centre d'aide.

Rejoignez notre communauté d'utilisateurs.