Como integrar o back-end do seu aplicativo

Nesta seção, descrevemos as etapas para integrar o back-end do seu 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 uma explicação passo a passo do código de exemplo, 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

  • Configure o acesso à API Partner Procurement do Cloud Commerce, conforme descrito em Como integrar seu aplicativo: configuração.
  • Se você escolheu um esquema de preços baseado no uso, verifique se o Partner Engineer criou um serviço com que você pode relatar o uso.

Tarefas da conta de usuário

Em um nível alto, 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 na sua solução.

  2. O Google Cloud Marketplace envia uma notificação ao seu aplicativo por 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_CHANGE.

    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.

As seções a seguir descrevem os tipos de solicitações que os usuários podem fazer e o que seu 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 sua solução pela primeira vez, o Google Cloud Marketplace cria um recurso de conta que rastreia o relacionamento do usuário com você. 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": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

Em que USER_ACCOUNT_ID é o ID da conta criado pelo Google Cloud Marketplace.

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 seu aplicativo.

Depois que o usuário se inscreveu com sucesso, seu aplicativo precisa chamar a API 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, o que indica que o usuário ainda não se inscreveu. Para aprovar a conta depois que o usuário se inscreveu, use a seguinte solicitação HTTP POST:

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

em que YOUR_PARTNER_ID é um código atribuído a você quando seu Partner Engineer permite o acesso à API Partner Procurement.

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.

Criar um direito

Quando os clientes escolhem um plano de preços para seu software, o Google cria um direito que indica que o cliente comprou sua solução no Google Cloud Marketplace.

Quando um cliente escolhe um plano, a seguinte mensagem do Pub/Sub é enviada ao seu aplicativo:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "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

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",
  "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:

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"
}

Cancelar direitos

Se um usuário decidir cancelar um direito, você receberá uma notificação do Pub/Sub. Da mesma maneira que a alteração de um plano, o cancelamento pode entrar em vigor no final do ciclo de faturamento atual.

A notificação está no seguinte formato:

{
  "eventId": "...",
  // If the entitlement is cancelled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "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",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "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.
ENTITLEMENT_ACTIVEIndica que o plano escolhido de um cliente está ativo agora.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDIndica que um cliente escolheu um novo plano.
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 que a alteração do plano de um cliente foi cancelada porque não foi aprovada ou eles retornaram ao plano antigo.
ENTITLEMENT_PENDING_CANCELLATIONIndica que um cliente cancelou seu plano e o cancelamento está 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 que o plano de um cliente foi cancelado.
ENTITLEMENT_CANCELLINGIndica que o plano de um cliente está em processo de cancelamento.
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 o preço baseado no uso para sua solução, é preciso informar o uso do seu aplicativo à API Service Control.

Seu Partner Engineer cria um serviço que corresponde à sua solução e concede à sua conta de serviço acesso para informar o uso desse serviço.

Para ver uma introdução ao Service Control, consulte o Guia de primeiros passos.

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 da 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 Operation, que contém um MetricValueSet para suas métricas de preços. O Operation também inclui um campo consumerId, que é definido como USAGE_REPORTING_ID do direito.

A seguir, é apresentado um exemplo de um 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" }]
    }]
  }]
}

Informe o uso do seu aplicativo por hora. Verifique se startTime e endTime estão corretos para o uso. Se o serviço do usuário tiver sido desativado antes do startTime, a API services.check enviará um erro no objeto checkErrors[] e o cliente não será cobrado pelo período.

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