Como integrar o back-end do aplicativo

Nesta seção, descrevemos as etapas para integrar o back-end do aplicativo com o Google Cloud Marketplace. Com essa integração, é possível gerenciar as contas dos usuários e direitos, o que indica que os usuários compraram seu produto no Google Cloud Marketplace. Se você escolheu um modelo de preços com base no uso, integre seu back-end também para informar o uso ao Google.

Para um exemplo de integração de um aplicativo básico ao Google Cloud Marketplace e um tutorial do código de amostra, consulte o codelab para integrar um serviço gerenciado.

Para ver o código de amostra usado no codelab, consulte o repositório do GitHub.

Antes de começar

Como criar uma conta de serviço

Para integrar seu produto ao Google Cloud, você precisa criar uma conta de serviço no projeto que está usando para o produto. O aplicativo usa essa conta de serviço para interagir com as APIs do Partner do Google Cloud Marketplace e receber informações sobre as compras dos usuários.

Recomendamos que você use o Portal do Produtor para criar e vincular suas contas de serviço.

Se você estiver usando o Portal do parceiro, o Engenheiro de parceiros concederá o papel de Assinante do Pub/Sub a essa conta de serviço. Para ver as etapas detalhadas para criar uma conta de serviço, consulte Como criar e gerenciar contas de serviço.

Como usar o Portal do Produtor para integrar o back-end do aplicativo

Para acessar todas as informações necessárias à integração do back-end do aplicativo ao Google Cloud Marketplace em um só local, como contas de serviço e identificadores de nível de plano, veja a seção INTEGRAÇÃO DE FATURAMENTO do Portal do Produtor.

O link direto para o Portal do Produtor é:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Para acessar a seção INTEGRAÇÃO DE FATURAMENTO:

  1. Na lista de produtos, clique no nome do seu produto.

  2. NaVisão geral página do seu produto, vá paraIntegração técnica e clique emINTEGRAATIONO DE FATURAMENTO para começar.

Como criar e vincular contas de serviço no Portal do Produtor

A seção INTEGRAÇÃO DE FATURAMENTO do portal do Produtor para criar e vincular as contas de serviço usadas para interagir com as APIs do Partner e receber informações sobre as compras dos usuários.

O link direto para o Portal do Produtor é:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Nas etapas a seguir, use contas de serviço atuais ou crie novas contas de serviço. Se você criar uma nova conta de serviço, especifique o nome dela no campo Nome da conta de serviço e o código dela no campo ID da conta de serviço. e clique em CRIAR E LINK.

Para vincular suas contas de serviço:

  1. Na lista de produtos, clique no nome do seu produto.

  2. NaVisão geral página do seu produto, vá paraIntegração técnica e clique emINTEGRAATIONO DE FATURAMENTO para começar.

  3. Para fazer a integração com a API Partner Procurement, emVincular uma conta de serviço para chamar a API Procurement, clique emADICIONAR CONTA DE SERVIÇO É possível inserir uma conta de serviço atual no campo ou criar uma nova conta de serviço.

  4. Para a integração ao Pub/Sub, emVincular uma conta de serviço para se inscrever no tópico Pub/Sub, clique em ADICIONAR CONTA DE SERVIÇO. É possível inserir uma conta de serviço atual no campo ou criar uma nova conta de serviço.

  5. Para a integração à API Service Control, emAdicionar roles/servicemanagement.serviceController a uma conta de serviço, clique em ADICIONAR CONTA DE SERVIÇO. É possível inserir uma conta de serviço atual no campo ou criar uma nova.

Tarefas da conta de usuário

Em alto nível, seu aplicativo precisa lidar com o seguinte cenário:

  1. Um usuário faz uma solicitação ou alteração no Google Cloud Marketplace, como se inscrever no seu produto.

  2. O Google Cloud Marketplace envia uma notificação ao aplicativo pelo Pub/Sub, contendo informações sobre a solicitação no campo eventType. Por exemplo, se um usuário alterar seus direitos, eventType será ENTITLEMENT_PLAN_CHANGED.

    Veja a lista completa de possíveis eventTypes.

  3. Para aprovar a solicitação, seu aplicativo envia uma solicitação HTTP POST à API Partner Procurement.

Nas seções a seguir, descrevemos os tipos de solicitações é podem ser feitas pelos usuários e o que aplicativo precisa fazer para lidar com elas.

Para as chamadas de API descritas nesta seção, use este ponto de extremidade:

https://cloudcommerceprocurement.googleapis.com/

Criar uma conta para um novo usuário

Quando um usuário compra seu produto pela primeira vez, o Google Cloud Marketplace cria um recurso da conta que rastreia a relação com ele. Quando o recurso da conta é criado, você é notificado através do tópico Pub/Sub que foi criado para você. A mensagem do Pub/Sub está no seguinte formato:

{
  "eventId": "...",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

em que USER_ACCOUNT_ID é o ID da conta criado pelo Google Cloud Marketplace, e YOUR_PARTNER_ID é um código atribuído a você quando seu Partner Engineer permite o acesso à API Partner Procurement.

Simultaneamente, o usuário é direcionado para sua página de inscrição, onde cria uma conta no seu sistema. Para ver mais informações sobre como criar a página de inscrição, consulte Como integrar o front-end do aplicativo.

Depois que o usuário se inscrever com sucesso, seu aplicativo precisará chamar a API Partner Procurement e indicar que a conta foi aprovada. As contas são criadas no estado ACCOUNT_ACTIVE, mas têm uma entrada PENDING no campo approvals, chamada signup. Isso indica que o usuário ainda não se inscreveu. Para aprovar a conta após a inscrição do usuário, use a seguinte solicitação HTTP POST:

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

Para verificar o status de uma conta vinculada, use a seguinte solicitação HTTP GET:

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

A resposta está no seguinte formato:

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

Para uma lista dos possíveis estados da conta, consulte a referência da API providers.accounts.

Como gerenciar direitos

Quando os clientes escolhem um plano de preços para seu software, o Google cria um direitos, o que indica que o cliente comprou seu produto no Google Cloud Marketplace. Nesta seção, mostramos como criar e gerenciar direitos para seus clientes usando a API Partner Procurement.

Para mais detalhes sobre o gerenciamento de direitos, consulte a documentação de referência.

Como aprovar ou rejeitar um direito

Quando um cliente escolhe um plano de preços, o Google Cloud Marketplace cria um direito e envia a seguinte mensagem do Pub/Sub ao seu aplicativo:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

em que ENTITLEMENT_ID é um ID criado pelo Google Cloud Marketplace.

No seu sistema, atualize a conta do usuário para refletir que ele comprou um plano. Em seguida, para aprovar o direito, faça uma solicitação HTTP POST à API Partner Procurement e envie o ENTITLEMENT_ID que você está aprovando:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

Para rejeitar um direito, use o método reject na sua solicitação HTTP POST:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

Alterar um plano de direitos

Dependendo de como você configura seus planos de preços, seus clientes podem alterar o plano deles. Se um cliente selecionar um novo plano de preços, você receberá uma mensagem do Pub/Sub, no seguinte formato:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

Para aprovar a alteração do plano, faça a seguinte solicitação HTTP POST à API Partner Procurement:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

O corpo da solicitação precisa ter o plano que está sendo aprovado:

{
  "pendingPlanName": PLAN_NAME
}

Depois que a alteração for aprovada, você receberá outra mensagem do Pub/Sub quando a alteração entrar em vigor. Na mensagem, o campo eventType muda para ENTITLEMENT_PLAN_CHANGED. Para verificar o status de um plano, faça a seguinte solicitação HTTP GET à API Partner Procurement.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

A resposta é semelhante à seguinte, com o campo state indicando se o novo plano está ativo ou se a alteração do plano ainda está pendente:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

Enviar uma mensagem de status para os usuários

Se o intervalo do momento em que o usuário escolhe um plano de preços até seu back-end aprovar um direito for de algumas horas ou mais, recomendamos que você envie uma mensagem de status aos usuários. Nessa mensagem, indique o andamento da aprovação e, se disponível, quando você espera que a aprovação seja concluída.

Para fornecer uma mensagem de status, faça a seguinte solicitação HTTP POST à API Procurement:

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

No corpo da solicitação, forneça o texto da mensagem, semelhante ao seguinte exemplo:

{
  "message": "Approval expected in 2 days"
}

Como cancelar direitos

Se um usuário decidir cancelar um direito dele, você receberá uma notificação do Pub/Sub. De maneira similar à alteração de um plano, o cancelamento real pode entrar em vigor no final do ciclo de faturamento real.

A notificação está no seguinte formato:

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

Excluir um direito

Se um usuário fizer uma solicitação direta ou sair da plataforma do Google, os direitos dele serão cancelados e excluídos e a conta dele será excluída. Para proteger a privacidade do usuário, exclua os dados dele dos seus servidores quando receber a notificação.

Quando os direitos são cancelados e a conta é excluída, você recebe notificações semelhantes às seguintes:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

Lista de tipos de eventos para tarefas da conta

A seguir, é apresentada uma lista dos eventTypes que seu aplicativo pode receber em mensagens do Pub/Sub:

eventTypeDescrição
ACCOUNT_CREATION_REQUESTEDObsoleto
ACCOUNT_ACTIVEIndica que a conta do cliente foi criada.
ACCOUNT_DELETEDIndica que a conta do cliente foi excluída dos sistemas do Google Cloud.
ENTITLEMENT_CREATION_REQUESTEDIndica que um cliente selecionou um dos seus planos de preços. Isso também aciona um novo evento ENTITLEMENT_CREATION_REQUESTED a cada 24 horas até que você tome medidas na solicitação do cliente.
ENTITLEMENT_ACTIVEIndica que o plano escolhido de um cliente está ativo agora.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDIndica que um cliente escolheu um novo plano. Isso também acionará um novo evento ENTITLEMENT_PLAN_CHANGE_REQUESTED a cada 24 horas até que você tome medidas em relação à seleção do cliente.
ENTITLEMENT_PLAN_CHANGEDIndica que a alteração do plano de um cliente foi aprovada e as alterações entraram em vigor.
ENTITLEMENT_PLAN_CHANGE_CANCELLEDIndica o cancelamento da alteração do plano de um cliente devido à falta de aprovação ou ao retorno do cliente ao plano antigo.
ENTITLEMENT_PENDING_CANCELLATIONIndica o cancelamento do plano pelo cliente, pendente até o final do ciclo de faturamento.
ENTITLEMENT_CANCELLATION_REVERTEDIndica que o cancelamento pendente de um cliente foi revertido. Observe que os cancelamentos não podem ser revertidos após a finalização.
ENTITLEMENT_CANCELLEDIndica o cancelamento do plano de um cliente.
ENTITLEMENT_CANCELLINGIndica que o plano de um cliente está em processo de cancelamento.
ENCONTROIndica que o direito de um cliente foi renovado por outro período. Não é preciso fazer nada para concluir a renovação.
ENTITLEMENT_OFFER_ENDEDIndica que a oferta particular de um cliente terminou. Se o direito do cliente tiver sido cancelado, um evento ENTITLEMENT_CANCELLED separado será acionado. Se o direito do cliente ainda estiver ativo, o plano será revertido para o preço sem desconto.
ENTITLEMENT_DELETEDIndica que as informações sobre o plano de um cliente foram excluídas do Google Cloud Marketplace.

(Para preços baseados no uso) Informar o uso para o Google

Se você escolher preços com base no uso para seu produto, é necessário informar o uso do seu app à API Service Control.

Para ver uma apresentação do Service Control, consulte o Guia de primeiros passos.

Se você tiver acesso ao Portal do Produtor, recomendamos que use o Portal do Produtor para criar uma conta de serviço no Portal do Produtor para uso com o Service Control.

Se você não tiver acesso ao Portal do Produtor, seu Engenheiro de parceiros criará um serviço que corresponde à sua solução e dará acesso à conta de serviço para reportar o uso. .

Quando uma autorização é criada, você precisa chamar a API Partner Procurement para recuperar um usageReportingId, usando a seguinte solicitação HTTP GET:

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

A resposta contém informações sobre o direito, no seguinte formato:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

Para informar o uso, primeiro você precisa fazer uma chamada de API services.check para verificar a configuração do serviço. Na resposta, se o objeto checkErrors[] estiver vazio, faça uma chamada da API services.report para enviar o relatório de uso.

O relatório de uso é uma API do Service Control Operation. Veja a seguir um exemplo de relatório de uso para example-messaging-service que envia informações sobre o armazenamento que está sendo usado pelo cliente:

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report
{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }],
    "userLabels": {
      "cloudmarketplace.googleapis.com/resource_name": "order_history_cache",
      "cloudmarketplace.googleapis.com/container_name": "storefront_prod",
      "environment": "prod",
      "region": "us-west2"
    }
  }]
}

onde:

  • operationId é uma string exclusiva gerada pela instância de serviço. Use o mesmo operationId para suas operações check e report.

  • consumerId é o mesmo que o usageReportingId do direito.

  • startTime e endTime representam os horários de início e término do intervalo total da operação report. Na maioria dos casos, o startTime de uma operação report precisa ter o mesmo valor que endTime da operação report anterior.

    Se o serviço de um cliente for desativado antes do startTime de uma operação report, a chamada de API services.check enviará um erro no objeto checkErrors[], e o cliente não será cobrado para o intervalo correspondente.

  • MetricValueSet contém um ou mais intervalos de tempo intermediários e os valores de métrica atualizados correspondentes. Você define as métricas do serviço quando escolher e enviar o modelo de preços.

    Se você tiver acesso ao Portal do Produtor, verá e referencia os identificadores das suas métricas na seção Integração técnica do Portal do produtor.

  • userLabels são rótulos criados pelo usuário, definidos como strings de chave-valor que seguem requisitos de sintaxe específicos. Esses rótulos são encaminhados para as ferramentas de gerenciamento de custos do Faturamento do Cloud para atribuição. Para convenções de rotulagem recomendadas, consulte Práticas recomendadas para rotulagem de uso.

Se a API services.check retornar um ou mais dos erros a seguir, recomendamos que você interrompa a prestação do serviço para o cliente até que o erro seja resolvido:

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED

Práticas recomendadas para a rotulagem de uso

Para um determinado direito, todo o uso é atribuído a um único usageReportingId. No entanto, em alguns cenários, um usageReportingId pode ser compartilhado amplamente na organização de um cliente. Para oferecer compatibilidade com a atribuição detalhada de custos, recomendamos que todos os serviços anexem userLabels aos relatórios de uso. Os rótulos serão encaminhados para as ferramentas de gerenciamento de custos do Faturamento do Cloud, incluindo relatórios de custos e exportações de faturamento.

Se o serviço for compatível nativamente com um conceito de rótulos de recursos, recomendamos que você o encaminhe nos relatórios de uso. Observe que os rótulos precisarão estar em conformidade com os requisitos de sintaxe.

Além disso, o Google Cloud Marketplace usa as seguintes convenções de rótulo. É possível usá-los para identificar mais contexto para uso na plataforma de serviço nativa. Recomendamos que você inclua esses rótulos nos relatórios de uso por padrão.

Chave da etiquetaValor da etiquetaDescrição>
cloudmarketplace.googleapis.com/resource_name USER_SUPPLIED O nome do recurso associado a uma métrica de uso. Por exemplo, se a métrica estiver relatando valores de armazenamento do banco de dados, o valor desse rótulo será o nome do banco de dados.
cloudmarketplace.googleapis.com/container_name USER_SUPPLIED O nome de um contêiner de recursos. Por exemplo, se um recurso de banco de dados for pai por um contêiner de cluster, o valor desse rótulo será o nome do cluster.