Sobre os arquivos de exemplo do mecanismo do adaptador de cobrança
Aplica-se a: Windows Azure Pack
O Windows exemplo do adaptador de cobrança do Azure Pack consiste em um mecanismo principal do adaptador de cobrança e um código específico do sistema para interagir com um sistema de cobrança específico. Os arquivos de exemplo estão na pasta Cobrança. Este tópico discute o código-fonte de exemplo do projeto do mecanismo principal do adaptador de cobrança. Os arquivos de exemplo do mecanismo principal do adaptador de cobrança estão na pasta BillingAdapter\Billing no Windows pacote de exemplos do Azure Pack. Para obter informações sobre o código-fonte de exemplo específico do sistema, consulte Sobre os arquivos de exemplo específicos do sistema de adaptador de cobrança.
BillingAdapter
O mecanismo do adaptador de cobrança tem quatro "sub-mecanismos", cada um fornecendo uma funcionalidade diferente. Cada sub-mecanismo é completamente ortogonal para outros sub-mecanismos, o que significa que cada um tem sua própria configuração e cada um pode ser habilitado\desabilitado sem afetar outros sub-mecanismos. O projeto do mecanismo do adaptador de cobrança fornece quatro interfaces fortemente tipdas que correspondem a cada um dos sub-mecanismos. A implementação específica do sistema pode optar por implementar parte ou todas as interfaces e habilitar\desabilitar os sub-mecanismos correspondentes de acordo. Ao implementar a interface do respondente de preços, a interface do respondente de aprovação de cobrança também deve ser implementada.
As quatro interfaces são
IBillingNotificationProcessor
IBillingUsageProcessor
IBillingSubscriptionResponder
IBillingPricingResponder
Interface |
Descrição |
Arquivo de código-fonte |
|---|---|---|
Processador de Notificação de Cobrança |
Fornece eventos fortemente tipado correspondentes aos eventos Windows API do Serviço de Uso do Azure Pack. Implemente essa interface se você quiser receber notificações de evento do Windows Azure Pack e sincronizá-las com seu sistema de cobrança. Os eventos incluem planos, complementos e modificações de assinatura. Para obter mais informações sobre a API rest do Serviço de Uso, consulte Windows Referência de API REST de Uso do Serviço de Uso do Azure Pack. |
IBillingNotificationProcessor.cs |
Respondente de Preços de Cobrança |
Essa interface inclui eventos fortemente tipado para responder a consultas de preços em tempo real. Implemente essa interface se você quiser retornar informações de preços do sistema de cobrança no Windows Azure Pack. Um exemplo dessa implementação de interface pode ser encontrado no exemplo HostBill. Para obter mais informações sobre a API rest de preços, consulte Windows Referência da API REST de Preços do Serviço de Uso do Azure Pack. |
IBillingPricingResponder.cs |
Respondente da Assinatura de Cobrança |
Essa interface inclui eventos fortemente tipado para responder ao bloqueio de solicitações de aprovação de cobrança. Implemente essa interface se o sistema de cobrança incluir lógica para aprovar ou negar que um usuário crie ou exclua assinaturas de plano e assinaturas de complemento. Para obter mais informações sobre a API REST de Aprovação de Cobrança, consulte Windows Referência da API REST de Aprovação de Cobrança do Serviço de Uso do Azure Pack. |
IBillingSubscriptionResponder.cs |
Processador de Uso de Cobrança |
Fornece eventos fortemente tipado para recuperar registros de uso do locatário. Implemente essa interface para recuperar informações de uso de locatário agregadas para todos os provedores de recursos do Windows Azure Pack. Para obter mais informações sobre a API Rest de dados de uso do provedor de recursos, consulte Windows Referência de API REST de Uso do Provedor de Recursos Personalizado do Azure Pack. |
IBillingUsageProcessor.cs |
Controladores
O mecanismo principal do adaptador de cobrança fornece dois sub-mecanismos (Respondente de Preços de Cobrança e Respondente de Assinatura de Cobrança) para ouvir solicitações de entrada do sistema Windows Azure Pack. Essas solicitações são tratadas pelos controladores de API Web na pasta Controladores. Esses controladores convertem as solicitações REST de entrada em eventos fortemente tipado e os enviam para a implementação de interface apropriada (IBillingSubscriptionResponder e IBillingPricingResponder).
Notificação de evento e processamento de registro de uso
Cada um deles é um agendador que ativa periodicamente e consulta o sistema Windows Azure Pack para obter novas informações, convertendo-o em eventos fortemente tipado e chama o evento correspondente na interface apropriada (IBillingNotificationProcessor ou IBillingUsageProcessor). Ambos os agendadores executam uma lógica semelhante:
Verifique se o processador atual é atualmente o mestre. Se não, eles dormem por um tempo predefinido. Consulte a seção app.config para obter mais informações.
Recupere o estado atual do repositório de estado.
Leia novos eventos do sistema Windows Azure Pack.
Converta os eventos em eventos fortemente tipado e invoque a implementação de interface específica do sistema.
Manipule os erros.
Respondente de Preços de Cobrança
Para relatar erros da implementação IBillingPricingResponder, dois objetos de exceção são fornecidos, PricingNotFoundException e PricingUnknownException, que podem ser usados para indicar que o produto solicitado não foi encontrado ou que não há informações de preço para este produto.
Configuração
O adaptador de cobrança usa o arquivo app.config para alterar as configurações do adaptador de cobrança. Após um build bem-sucedido, o arquivo app.config será colocado ao lado do executável do adaptador de cobrança e o arquivo renomeado para ter o mesmo nome que o executável do adaptador de cobrança com um sufixo .config adicional (por exemplo, Microsoft.WindowsAzurePack.Samples.Billing.exe.config). Modificar esse arquivo requer a reinicialização do processo do adaptador de cobrança.
Observação
O arquivo app.config contém as configurações para o núcleo do adaptador de cobrança e a implementação específica do sistema. Se você fornecer sua própria implementação específica do sistema, poderá optar por armazenar as configurações específicas do sistema em outro lugar.
O seguinte descreve as configurações no arquivo app.config:
Utilitários - App.Config
O arquivo app.config contém campos que podem ser modificados conforme necessário para um adaptador de cobrança e Windows implantação do Azure Pack. As alterações de campo devem ser feitas após a compilação e antes de executar o binário. O seguinte descreve os campos de chave.
<connectionStrings>
Cadeias de conexão para os bancos de dados usados pelo adaptador de cobrança. A cadeia de conexão StateManage é usada pelo mecanismo de núcleo do adaptador de cobrança para armazenar seu estado interno. A cadeia de conexão IdentityMappingManager é usada pela implementação específica do sistema para armazenar o mapeamento entre Windows identidades do Azure Pack e as identidades do sistema de cobrança. Se você fornecer sua própria implementação específica do sistema, talvez não precise desse banco de dados.
<appSettings>
A seção appSettings contém as configurações do mecanismo de núcleo do adaptador de cobrança e a implementação específica do sistema. As configurações são agrupadas, com base em seu prefixo e controlam diferentes sub-mecanismos.
Veja a seguir as configurações do Assembly do Adaptador de Cobrança:
Setting |
Descrição |
|---|---|
BillingAdapter.Assembly |
O assembly do adaptador de cobrança que contém a implementação específica do sistema. |
BillingAdapter.Type |
O nome completo do tipo no BillingAdapter.Assembly que implementa as interfaces específicas do sistema. Se esse tipo não implementar uma interface específica, mas o subprojeto correspondente para essa interface estiver habilitado, ocorrerá um erro e o processo do adaptador de cobrança não será iniciado. |
Veja a seguir as configurações do aplicativo para o Processador de Notificação de Cobrança:
Configurações de Aplicativo |
Descrição |
|---|---|
NotificationProcessor.Enabled |
Definido como true se estiver implementando a interface NotificationProcessor; isso habilitará o agendador para o Processador de Notificação. |
NotificationProcessor.EndpointBaseAddress |
O Windows URI do ponto de extremidade REST da notificação de evento do Azure Pack. O Processador de Notificação de Eventos usará esse ponto de extremidade para ler notificações de evento do sistema Windows Azure Pack. |
NotificationProcessor.EndpointUsername, NotificationProcessor.EndpointPassword |
Nome de usuário e senha para o Windows ponto de extremidade de Notificação de Evento do Azure Pack. O Processador de Notificação de Eventos usará essas credenciais ao ler eventos do ponto de extremidade de notificação de evento WAP. |
NotificationProcessor.ReadBatchSize |
O tamanho máximo do lote que será usado ao ler notificações de evento dos pontos de extremidade de notificação de evento do Windows Azure Pack. Se você tiver problemas de desempenho de rede, considere alterar esse valor. |
NotficationProcessor.PollingIntervalSeconds |
A quantidade de tempo que o agendador dormirá entre tiques. O agendador não está sobreposto, portanto, o período de suspensão só começará quando uma leitura completa for concluída. |
NotificationProcessor.ErrorBackoffIntervalSeconds |
Após um erro, essa é a quantidade de tempo que o agendador dormirá antes de tentar novamente. |
NotificationProcessor.IsMasterExpirationInSeconds |
Somente uma instância do agendador tem permissão para ser executada em todos os processos e computadores. Esse agendador é chamado de mestre. Quando uma instância do agendador é selecionada para ser a instância mestra, ela continua executando ping no banco de dados de estado. Se o banco de dados mestre não fizer ping por um período maior que esse valor, outra instância do agendador tentará se tornar o mestre. A instância mestra executa ping no banco de dados de estado somente durante o processamento do agendador (ele não faz ping durante o tempo de suspensão do agendador), portanto, é recomendável que esse valor seja várias vezes maior do que o tempo máximo de suspensão possível para o agendador, que é o máximo de NotficationProcessor.PollingIntervalSeconds e NotificationProcessor.ErrorBackoffIntervalSeconds. Definir esse valor como um período muito longo levará a um failover mestre mais lento. |
Veja a seguir as configurações do aplicativo para o Processador de Uso de Cobrança:
Configurações de Aplicativo |
Descrição |
|---|---|
UsageProcessor.Enabled |
Definido como true se estiver implementando a interface UsageProcessor; isso habilitará o agendador para o Processador de Uso de Cobrança. |
UsageProcessor.EndpointBaseAddress |
O ponto de extremidade usado pelo Windows Pacote do Azure para fazer as chamadas à API Rest. O arquivo .config de exemplo tem um valor padrão, mas você deseja especificar seu próprio servidor de ponto de extremidade. |
UsageProcessor.EndpointUsername, UsageProcessor.EndpointPassword |
Nome de usuário e senha para o ponto de extremidade Windows Uso do Pacote do Azure. O Processador de Uso usará essas credenciais ao ler eventos do ponto de extremidade Windows Uso do Azure Pack. |
UsageProcessor.ReadBatchSize |
O tamanho máximo do lote que será usado ao ler notificações de evento dos pontos de extremidade de notificação de evento do Windows Azure Pack. Se você tiver problemas de desempenho de rede, considere alterar esse valor. |
UsageProcessor.PollingIntervalSeconds |
A quantidade de tempo que o agendador dormirá entre tiques. O agendador não está sobreposto, portanto, o período de suspensão só começará quando uma leitura completa for concluída. |
UsageProcessor.ErrorBackoffIntervalSeconds |
Após um erro, essa é a quantidade de tempo que o agendador dormirá antes de tentar novamente. |
UsageProcessor.IsMasterExpirationInSeconds |
Somente uma instância do agendador tem permissão para ser executada em todos os processos e computadores. Esse agendador é chamado de mestre. Quando uma instância do agendador é selecionada para ser a instância mestra, ela continua executando ping no banco de dados de estado. Se o banco de dados mestre não fizer ping por um período maior que esse valor, outra instância do agendador tentará se tornar o mestre. A instância mestra executa ping no banco de dados de estado somente durante o processamento do agendador (ele não faz ping durante o tempo de suspensão do agendador), portanto, é recomendável que esse valor seja várias vezes maior do que o tempo máximo de suspensão possível para o agendador, que é o máximo de UsageProcessor.PollingIntervalSeconds e UsageProcessor.ErrorBackoffIntervalSeconds. Definir esse valor como um período muito longo levará a um failover mestre mais lento. |
Veja a seguir as configurações aplicadas a todos os respondentes:
Configurações de Aplicativo |
Descrição |
|---|---|
Responders.EndpointBaseAddress |
O endereço base local para os pontos de extremidade de respondentes. O adaptador de cobrança criará um ouvinte usando esse endereço base. O mesmo ponto de extremidade base é usado para ambos os respondentes (o mecanismo do adaptador de cobrança acrescentará caminhos diferentes para cada respondente). Se HTTPS (Hypertext Transfer Protocol Secure) for usado, um certificado SSL precisará ser configurado fora de banda na mesma porta. Para obter mais informações, consulte https://msdn.microsoft.com/en-us/library/ms733791(v=vs.110).aspx. |
Responders.EndpointUsername, Responders.EndpointPassword |
Credenciais básicas de autenticação para o ponto de extremidade de respondentes. |
Responders.Notification.Enabled |
Definido como true para ativar o respondente da assinatura (API de Aprovação de Cobrança). A implementação específica do sistema do adaptador de cobrança deve implementar a interface IBillingSubscriptionResponder. |
Responders.Pricing.Enabled |
Definido como true para ativar o respondente de preços (API de preços). A implementação específica do sistema do adaptador de cobrança deve implementar a interface IBillingPricingResponder. |
Veja a seguir as configurações do aplicativo Adaptador de Cobrança:
Configurações de Aplicativo |
Descrição |
|---|---|
BillingAdapter.Assembly |
Caminho para o adaptador de cobrança. |
BillingAdapter.Type |
Caminho para o adaptador de cobrança. Se o código aqui não corresponder aos valores definidos para os valores "Habilitar" no app.config, haverá um erro ao executar. |
Por exemplo, o app.config fornecido contém a configuração de espaço reservado para os sistemas de cobrança WHMCS e HostBill. Em uma implantação de produção, não é necessário ter ambos. Você deve manter as configurações correspondentes à implementação específica do sistema do adaptador de cobrança. Se você implementar seu próprio adaptador, cabe a você decidir se deseja ter as configurações em app.config ou em outro lugar (em um banco de dados, por exemplo).
Algumas configurações a serem observadas são:
Configurações de Aplicativo |
Descrição |
|---|---|
WHMCS. ExpectedVersion /HostBill.ExpectedVersion |
Campo obrigatório. O mecanismo do adaptador de cobrança comparará esse valor de versão com a versão do sistema de cobrança configurada. Se eles não corresponderem, ele produzirá um erro e impedirá que o adaptador seja executado. A finalidade dessa verificação é impedir que o adaptador de cobrança opere em um sistema de cobrança não testado. |
WHMCS. MySqlConnectionString / HostBill.MySqlConnectionString |
Uma cadeia de conexão (com permissões de gravação) para o banco de dados MySql do sistema de cobrança. Ele é usado pela implementação específica do sistema do adaptador para atualizar o banco de dados do sistema de cobrança diretamente quando não há uma chamada de API correspondente. |
WHMCS. EndpointUsername, WHMCS EndPointPassword |
O nome de usuário e a senha do ponto de extremidade WHMCS. |
HostBill.ApiId, HostBIll.ApiKey |
O Identificador hostBill e a chave de API. |
WHMCS. ProductGroupName, HostBill.CategoryName |
Os planos são criados em um grupo\categoria nos sistemas de cobrança. Esse valor especificou o grupo\categoria a ser usado. O grupo\categoria deve existir (criado manualmente) antes de executar o processo do adaptador de cobrança. |
WHMCS. DefaultCurrencyCode |
Especifica o código de moeda padrão para WHMCS ao criar novos pedidos de assinatura. |
WHMCS. DefaultPaymentModule / HostBill.DefaultPaymentModule |
WHMCS. DefaultPaymentMethodModule \ HostBill.DefaultPaymentModule. Especifica a forma de pagamento padrão a ser usada ao fazer novos pedidos de assinatura. |
WHMCS. DefaultBillingCycle / HostBill.DefaultBillingCycle |
Especifica o ciclo de cobrança padrão para novos pedidos de assinatura, se ele não estiver definido nas configurações do usuário. |
WHMCS. EnableUserCreation/HostBill.EnableUserCreation |
Em ambientes de produção, todos os usuários do Azure Pack Windows devem existir previamente no sistema de cobrança. No entanto, para cenários de teste, pode ser útil criar usuários em tempo real, se eles não existirem no sistema de cobrança. Quando definido como True, se um usuário não existir no sistema de cobrança, ele será criado automaticamente quando um evento de assinatura for recebido do Windows Azure Pack. |
WHMCS. EnableOrderMailConfirmation |
Defina como true para enviar uma confirmação de email quando uma assinatura está sendo criada. |
Observação
No exemplo do adaptador de cobrança, ter EnableUserCreation definido como True fará com que o adaptador de cobrança crie contas de usuário dentro do sistema de cobrança "on-the-fly" à medida que processa eventos do Windows Azure Pack. Se False, ele rejeitará as operações se elas forem enviadas por meio da API em tempo real e interromperá o processamento se forem encontradas na API Rest.
Um provedor verdadeiro teria um sistema de gerenciamento de identidade para controlar a criação da conta de usuário. O ideal é que isso ocorra antes que os clientes possam comprar assinaturas no Windows Azure Pack, e o adaptador de cobrança nunca deve encontrar uma operação para uma conta de usuário que não existe no sistema de cobrança.
Para que o exemplo do adaptador de cobrança funcione "pronto para uso", essa opção é fornecida para criar contas de usuário à medida que o exemplo processa eventos. As contas são criadas somente com um endereço de email. Todos os outros campos estão vazios.