À propos des exemples de fichiers du moteur de base de l’adaptateur de facturation
S’applique à : Windows Azure Pack
L’exemple d’adaptateur de facturation Azure Pack Windows se compose d’un moteur principal de carte de facturation et d’un code spécifique au système pour interagir avec un système de facturation spécifique. Les exemples de fichiers se trouvent dans le dossier Facturation. Cette rubrique décrit l’exemple de code source du projet de moteur de l’adaptateur de facturation principal. Les exemples de fichiers de moteur de l’adaptateur de facturation se trouvent sous le dossier BillingAdapter\Billing dans le package d’exemples Azure Pack Windows. Pour plus d’informations sur l’exemple de code source spécifique au système, consultez About the Billing Adapter System Specific Sample Files.
BillingAdapter
Le moteur de l’adaptateur de facturation comporte quatre « sous-moteurs », chacun fournissant une fonctionnalité différente. Chaque sous-moteur est complètement orthogonal à d’autres sous-moteurs, ce qui signifie que chacun a sa propre configuration et que chacun peut être activé\désactivé sans affecter d’autres sous-moteurs. Le projet de moteur d’adaptateur de facturation fournit quatre interfaces fortement typées correspondant à chacun des sous-moteurs. L’implémentation spécifique au système peut choisir d’implémenter une partie ou toutes les interfaces et d’activer\désactiver les sous-moteurs correspondants en fonction. Lors de l’implémentation de l’interface du répondeur de tarification, l’interface du répondeur d’approbation de facturation doit également être implémentée.
Les quatre interfaces sont
IBillingNotificationProcessor
IBillingUsageProcessor
IBillingSubscriptionResponder
IBillingPricingResponder
Interface |
Description |
Fichier source |
|---|---|---|
Processeur de notification de facturation |
Fournit des événements fortement typés correspondant aux événements de l’API Azure Pack Usage Service Windows. Implémentez cette interface si vous souhaitez recevoir des notifications d’événements de Windows Azure Pack et les synchroniser avec votre système de facturation. Les événements incluent le plan, les modules complémentaires et les modifications d’abonnement. Pour plus d’informations sur l’API REST du service d’utilisation, consultez Windows informations de référence sur l’API REST Utilisation du service d’utilisation d’Azure Pack. |
IBillingNotificationProcessor.cs |
Répondeur de tarification de facturation |
Cette interface inclut des événements fortement typés pour répondre aux requêtes de tarification en temps réel. Implémentez cette interface si vous souhaitez retourner des informations de tarification à partir de votre système de facturation dans Windows Azure Pack. Vous trouverez un exemple de cette implémentation d’interface dans l’exemple HostBill. Pour plus d’informations sur l’API REST de tarification, consultez Windows informations de référence sur l’API REST de tarification du service d’utilisation d’Azure Pack. |
IBillingPricingResponder.cs |
Répondeur d’abonnement de facturation |
Cette interface inclut des événements fortement typés pour répondre au blocage des demandes d’approbation de facturation. Implémentez cette interface si votre système de facturation inclut une logique d’approbation ou de refus d’un utilisateur créant ou supprimant des abonnements de plan et des abonnements de module complémentaire. Pour plus d’informations sur l’API Rest d’approbation de facturation, consultez Windows informations de référence sur l’API REST d’approbation de facturation du service d’utilisation Azure Pack. |
IBillingSubscriptionResponder.cs |
Processeur d’utilisation de la facturation |
Fournit des événements fortement typés pour récupérer les enregistrements d’utilisation du locataire. Implémentez cette interface pour récupérer des informations d’utilisation agrégées du locataire pour tous les fournisseurs de ressources Azure Pack Windows. Pour plus d’informations sur l’API REST des données d’utilisation du fournisseur de ressources, consultez Windows informations de référence sur l’API REST d’utilisation du fournisseur de ressources personnalisé Azure Pack. |
IBillingUsageProcessor.cs |
Controllers
Le moteur principal de l’adaptateur de facturation fournit deux sous-moteurs (répondeur de tarification de facturation et répondeur d’abonnement de facturation) pour écouter les demandes entrantes du système Azure Pack Windows. Ces requêtes sont gérées par les contrôleurs d’API web dans le dossier Contrôleurs. Ces contrôleurs convertissent les requêtes REST entrantes en événements fortement typés et les envoient à l’implémentation d’interface appropriée (IBillingSubscriptionResponder et IBillingPricingResponder).
Traitement des enregistrements de notification et d’utilisation des événements
Chacun d’eux est un planificateur qui se réveille régulièrement et interroge le système azure Pack Windows pour obtenir de nouvelles informations, en le convertissant en événements fortement typés et en appelant l’événement correspondant sur l’interface appropriée (IBillingNotificationProcessor ou IBillingUsageProcessor). Les deux planificateurs effectuent une logique similaire :
Vérifiez que le processeur actuel est actuellement le maître. Si ce n’est pas le cas, ils dorment pendant une période prédéfinie. Pour plus d’informations, consultez la section app.config.
Récupérez l’état actuel à partir du magasin d’état.
Lisez les nouveaux événements du système Azure Pack Windows.
Convertissez les événements en événements fortement typés et appelez l’implémentation de l’interface spécifique au système.
Gérez les erreurs éventuelles.
Répondeur de tarification de facturation
Pour signaler des erreurs à partir de l’implémentation IBillingPricingResponder, deux objets d’exception sont fournis, PricingNotFoundException et PricingUnknownException, qui peuvent être utilisés pour indiquer que le produit demandé n’a pas été trouvé ou qu’il n’existe aucune information tarifaire pour ce produit.
Configuration
L’adaptateur de facturation utilise le fichier app.config pour modifier les paramètres de l’adaptateur de facturation. Après une génération réussie, le fichier app.config est placé à côté de l’exécutable de l’adaptateur de facturation et le fichier renommé pour avoir le même nom que l’exécutable de l’adaptateur de facturation avec un suffixe .config supplémentaire (par exemple, Microsoft.WindowsAzurePack.Samples.Billing.exe.config). La modification de ce fichier nécessite le redémarrage du processus de l’adaptateur de facturation.
Notes
Le fichier app.config contient les paramètres du cœur de l’adaptateur de facturation et de l’implémentation spécifique au système. Si vous fournissez votre propre implémentation spécifique au système, vous pouvez choisir de stocker vos paramètres spécifiques au système ailleurs.
Les éléments suivants décrivent les paramètres du fichier app.config :
Utilitaires - App.Config
Le fichier app.config contient des champs qui peuvent être modifiés en fonction des besoins pour un adaptateur de facturation et Windows déploiement d’Azure Pack. Les modifications de champ doivent être effectuées après la compilation et avant d’exécuter le fichier binaire. L’exemple suivant décrit les champs clés.
<connectionStrings>
Chaînes de connexion pour les bases de données utilisées par l’adaptateur de facturation. La chaîne de connexion StateManage est utilisée par le moteur principal de l’adaptateur de facturation pour stocker son état interne. La chaîne de connexion IdentityMappingManager est utilisée par l’implémentation spécifique au système pour stocker le mappage entre Windows identités Azure Pack et les identités système de facturation. Si vous fournissez votre propre implémentation propre au système, vous n’avez peut-être pas besoin de cette base de données.
<appSettings>
La section appSettings contient les paramètres du moteur principal de l’adaptateur de facturation et de l’implémentation spécifique au système. Les paramètres sont regroupés, en fonction de leur préfixe et contrôlent différents sous-moteurs.
Voici les paramètres d’assembly de l’adaptateur de facturation :
Paramètre |
Description |
|---|---|
BillingAdapter.Assembly |
Assembly de l’adaptateur de facturation contenant l’implémentation spécifique au système. |
BillingAdapter.Type |
Nom complet du type dans BillingAdapter.Assembly qui implémente les interfaces spécifiques au système. Si ce type n’implémente pas d’interface spécifique, mais que le sous-moteur correspondant pour cette interface est activé, une erreur se produit et le processus de l’adaptateur de facturation ne démarre pas. |
Voici les paramètres d’application pour le processeur de notification de facturation :
Paramètre d'application |
Description |
|---|---|
NotificationProcessor.Enabled |
Défini sur true si l’implémentation de l’interface NotificationProcessor ; cela active le planificateur pour le processeur de notification. |
NotificationProcessor.EndpointBaseAddress |
URI du point de terminaison REST de notification d’événements Azure Pack Windows. Le processeur de notification d’événements utilise ce point de terminaison pour lire les notifications d’événements à partir du système Windows Azure Pack. |
NotificationProcessor.EndpointUsername, NotificationProcessor.EndpointPassword |
Nom d’utilisateur et mot de passe pour le point de terminaison de notification d’événements Azure Pack Windows. Le processeur de notification d’événements utilise ces informations d’identification lors de la lecture d’événements à partir du point de terminaison de notification d’événements WAP. |
NotificationProcessor.ReadBatchSize |
Taille de lot maximale qui sera utilisée lors de la lecture des notifications d’événements à partir des points de terminaison de notification d’événements Azure Pack Windows. Si vous rencontrez des problèmes de performances réseau, envisagez de modifier cette valeur. |
NotficationProcessor.PollingIntervalSeconds |
Durée pendant laquelle le planificateur dormira entre les cycles. Le planificateur ne se chevauche pas, par conséquent, la période de veille ne commence qu’une fois qu’une lecture complète est terminée. |
NotificationProcessor.ErrorBackoffIntervalSeconds |
Après une erreur, il s’agit de la durée pendant laquelle le planificateur est en veille avant de réessayer. |
NotificationProcessor.IsMasterExpirationInSeconds |
Une seule instance du planificateur est autorisée à s’exécuter sur tous les processus et machines. Ce planificateur est appelé maître. Lorsqu’une instance du planificateur est sélectionnée pour être l’instance principale, elle effectue un test ping sur la base de données d’état. Si la base de données master n’effectue pas de test ping pendant une période plus longue que cette valeur, une autre instance du planificateur tente de devenir le maître. L’instance principale effectue un test ping sur la base de données d’état uniquement pendant le traitement du planificateur (elle ne effectue pas de test ping pendant les mises en veille du planificateur), il est donc recommandé de faire en sorte que cette valeur soit plusieurs fois supérieure à la durée de veille maximale possible pour le planificateur, qui est le maximum de NotficationProcessor.PollingIntervalSeconds et NotificationProcessor.ErrorBackoffIntervalSeconds. La définition de cette valeur sur une période trop longue entraîne un basculement maître plus lent. |
Voici les paramètres d’application pour le processeur d’utilisation de la facturation :
Paramètre d'application |
Description |
|---|---|
UsageProcessor.Enabled |
Défini sur true si l’implémentation de l’interface UsageProcessor ; cela active le planificateur pour le processeur d’utilisation de la facturation. |
UsageProcessor.EndpointBaseAddress |
Point de terminaison utilisé par Windows Azure Pack pour effectuer les appels d’API Rest. L’exemple .config fichier a une valeur par défaut, mais vous souhaiterez spécifier votre propre serveur de point de terminaison. |
UsageProcessor.EndpointUsername, UsageProcessor.EndpointPassword |
Nom d’utilisateur et mot de passe pour le point de terminaison d’utilisation Windows Azure Pack. Le processeur d’utilisation utilise ces informations d’identification lors de la lecture d’événements à partir du point de terminaison d’utilisation Windows Azure Pack. |
UsageProcessor.ReadBatchSize |
Taille de lot maximale qui sera utilisée lors de la lecture des notifications d’événements à partir des points de terminaison de notification d’événements Azure Pack Windows. Si vous rencontrez des problèmes de performances réseau, envisagez de modifier cette valeur. |
UsageProcessor.PollingIntervalSeconds |
Durée pendant laquelle le planificateur dormira entre les cycles. Le planificateur ne se chevauche pas, par conséquent, la période de veille ne commence qu’une fois qu’une lecture complète est terminée. |
UsageProcessor.ErrorBackoffIntervalSeconds |
Après une erreur, il s’agit de la durée pendant laquelle le planificateur est en veille avant de réessayer. |
UsageProcessor.IsMasterExpirationInSeconds |
Une seule instance du planificateur est autorisée à s’exécuter sur tous les processus et machines. Ce planificateur est appelé maître. Lorsqu’une instance du planificateur est sélectionnée pour être l’instance principale, elle effectue un test ping sur la base de données d’état. Si la base de données master n’effectue pas de test ping pendant une période plus longue que cette valeur, une autre instance du planificateur tente de devenir le maître. L’instance maître effectue un test ping sur la base de données d’état uniquement pendant le traitement du planificateur (elle n’effectue pas de test ping pendant les mises en veille du planificateur), il est donc recommandé que cette valeur soit plusieurs fois supérieure à la durée de veille maximale possible pour le planificateur, qui est le maximum d’UsageProcessor.PollingIntervalSeconds et UsageProcessor.ErrorBackoffIntervalSeconds. La définition de cette valeur sur une période trop longue entraîne un basculement maître plus lent. |
Les paramètres suivants sont appliqués à tous les répondeurs :
Paramètre d'application |
Description |
|---|---|
Responders.EndpointBaseAddress |
Adresse de base locale pour les points de terminaison des répondeurs. L’adaptateur de facturation crée un écouteur à l’aide de cette adresse de base. Le même point de terminaison de base est utilisé pour les deux répondeurs (le moteur de l’adaptateur de facturation ajoute des chemins différents pour chaque répondeur). Si le protocole HTTPS (Hypertext Transfer Protocol Secure) est utilisé, un certificat SSL doit être configuré hors bande sur le même port. Pour plus d’informations, consultez https://msdn.microsoft.com/en-us/library/ms733791(v=vs.110).aspx. |
Responders.EndpointUsername, Responders.EndpointPassword |
Informations d’identification d’authentification de base pour le point de terminaison des répondeurs. |
Responders.Notification.Enabled |
Définissez la valeur true pour activer le répondeur d’abonnement (API d’approbation de facturation). L’implémentation propre au système de l’adaptateur de facturation doit implémenter l’interface IBillingSubscriptionResponder. |
Responders.Pricing.Enabled |
Définissez la valeur true pour activer le répondeur de tarification (API de tarification). L’implémentation propre au système de l’adaptateur de facturation doit implémenter l’interface IBillingPricingResponder. |
Voici les paramètres d’application de l’adaptateur de facturation :
Paramètre d'application |
Description |
|---|---|
BillingAdapter.Assembly |
Chemin d’accès à l’adaptateur de facturation. |
BillingAdapter.Type |
Chemin d’accès à l’adaptateur de facturation. Si le code ici ne correspond pas aux valeurs définies pour les valeurs « Activer » dans le app.config, une erreur s’affiche lors de l’exécution. |
Par exemple, le app.config fourni contient un paramètre d’espace réservé pour les systèmes de facturation WHMCS et HostBill. Dans un déploiement de production, il n’est pas nécessaire d’avoir les deux. Vous devez conserver les paramètres correspondant à votre implémentation propre au système de l’adaptateur de facturation. Si vous implémentez votre propre adaptateur, il vous incombe de décider si les paramètres doivent être app.config ou ailleurs (dans une base de données par exemple).
Voici quelques paramètres à noter :
Paramètre d'application |
Description |
|---|---|
WHMCS. ExpectedVersion / HostBill.ExpectedVersion |
Champ obligatoire. Le moteur de l’adaptateur de facturation compare cette valeur de version à la version configurée du système de facturation. S’ils ne correspondent pas, il génère une erreur et empêche l’exécution de l’adaptateur. L’objectif de cette vérification est d’empêcher l’adaptateur de facturation de fonctionner sur un système de facturation non testé. |
WHMCS. MySqlConnectionString / HostBill.MySqlConnectionString |
Chaîne de connexion (avec autorisations d’écriture) à la base de données MySql du système de facturation. Il est utilisé par l’implémentation propre au système d’adaptateur pour mettre à jour la base de données système de facturation directement lorsqu’il n’existe pas d’appel d’API correspondant. |
WHMCS. EndpointUsername, WHMCS EndPointPassword |
Nom d’utilisateur et mot de passe du point de terminaison WHMCS. |
HostBill.ApiId, HostBIll.ApiKey |
Identificateur HostBill et clé API. |
WHMCS. ProductGroupName, HostBill.CategoryName |
Les plans sont créés sous un groupe\catégorie dans les systèmes de facturation. Cette valeur a spécifié le groupe\catégorie à utiliser. Le groupe\catégorie doit exister (créé manuellement) avant d’exécuter le processus de l’adaptateur de facturation. |
WHMCS. DefaultCurrencyCode |
Spécifie le code monétaire par défaut pour WHMCS lors de la création de commandes d’abonnement. |
WHMCS. DefaultPaymentModule / HostBill.DefaultPaymentModule |
WHMCS. DefaultPaymentMethodModule \ HostBill.DefaultPaymentModule. Spécifie le mode de paiement par défaut à utiliser lors du placement de nouvelles commandes d’abonnement. |
WHMCS. DefaultBillingCycle / HostBill.DefaultBillingCycle |
Spécifie le cycle de facturation par défaut pour les nouvelles commandes d’abonnement, s’il n’est pas défini dans les paramètres utilisateur. |
WHMCS. EnableUserCreation / HostBill.EnableUserCreation |
Dans les environnements de production, tous les utilisateurs d’Azure Pack Windows doivent exister au préalable dans le système de facturation. Toutefois, pour les scénarios de test, il peut être utile de créer des utilisateurs à la volée, s’ils n’existent pas dans le système de facturation. Lorsqu’il a la valeur True, si un utilisateur n’existe pas dans le système de facturation, il est automatiquement créé lorsqu’un événement d’abonnement est reçu de Windows Azure Pack. |
WHMCS. EnableOrderMailConfirmation |
Définissez la valeur true pour envoyer une confirmation de courrier lorsqu’un abonnement est créé. |
Notes
Dans l’exemple d’adaptateur de facturation, la valeur True de EnableUserCreation entraîne la création de comptes d’utilisateur dans le système de facturation « à la volée » car elle traite les événements de Windows Azure Pack. Si la valeur est false, elle rejette les opérations si elles sont envoyées via l’API en temps réel et arrêtent le traitement s’ils se trouvent dans l’API Rest.
Un vrai fournisseur aurait un système de gestion des identités en place pour contrôler la création du compte d’utilisateur. Dans l’idéal, cela se produit avant que les clients ne soient autorisés à acheter des abonnements dans Windows Azure Pack, et l’adaptateur de facturation ne doit jamais rencontrer d’opération pour un compte d’utilisateur qui n’existe pas dans le système de facturation.
Pour que l’exemple d’adaptateur de facturation fonctionne « out-of-the-box », cette option est fournie pour créer des comptes d’utilisateur en tant qu’exemple de processus d’événements. Les comptes sont créés avec une adresse e-mail uniquement. Tous les autres champs sont vides.