Como integrar seu suporte

Nesta seção, descrevemos o fluxo de trabalho de suporte quando você pretende fornecer suporte como parte de sua solução.

Seu sistema precisa ser integrado ao Google para que você possa fornecer suporte aos clientes que adquiriram suas soluções por meio do Google. A integração se baseia nos seguintes itens que o Google fornece a você:

  • uma chave para verificar se um usuário está qualificado para receber suporte como parte do processo de inscrição;

  • uma API de assinatura que receberá a chave para consultar periodicamente o status da qualificação de um usuário ao suporte.

Como receber o ID de suporte do usuário

A integração de suporte gira em torno de um código de conta externo, que os usuários veem como o código de suporte deles.

Os usuários fornecem os respectivos códigos de suporte das seguintes maneiras:

  • Você cria um fluxo de trabalho de suporte e fornece um URL para o início do fluxo de trabalho. Em seguida, o Google envia a você o código de conta externa no URL.
  • Ao criar sua solução no Portal do Google Partners, é possível selecionar a opção para exibir um botão em que os usuários podem clicar para ver o próprio ID de suporte. Eles podem copiar e enviar o ID do suporte por e-mail, inseri-lo em um formulário da Web ou lê-lo para um representante de suporte por telefone.

Se você implementar o fluxo de trabalho de suporte, ele precisará do código de conta externa como parte do URL. O código da conta externa pode fazer parte do caminho do URL ou ser um valor do parâmetro de consulta, como nos exemplos abaixo:

# External account ID in path
http://example.com/mysupportpage/{external_account_id}?someparameter=yes

# External account ID as a query parameter
http://example.com/mysupportpage?eid={external_account_id}&something_else

O texto {external_account_id} no URL é substituído pelo ID da conta externa. Se você tem várias soluções listadas no Google Cloud Marketplace, convém incluir um parâmetro de consulta para identificar a solução a que se destina o URL.

Como usar a API de assinaturas

Munido do ID da conta externa do usuário, use a API de assinaturas fornecida pelo Google para verificar se sua conta está qualificada para o suporte a qualquer momento. A elegibilidade é rastreada com a verificação de entidades denominadas assinaturas.

Cada assinatura tem um número de ID de assinatura exclusivo, e uma assinatura é criada por cliente para cada solução listada no Cloud Marketplace. Portanto, também é possível consultar uma assinatura por ID de assinatura para receber mais detalhes sobre o histórico de um cliente com sua solução, como data de início, data de término e assim por diante.

Como acessar a API de assinaturas

A API de assinaturas é uma API não pública, portanto, para ter acesso, desenvolvedores e projetos precisam ser incluídos na lista de permissões.

Para colocar na lista de permissões e configurar, siga estes passos:

  1. Envie uma lista de endereços de e-mail para desenvolvedores que precisam acessar a documentação da API para o engenheiro de parceiros do Google Cloud Marketplace ou para cloud-partner-onboarding@google.com. Esses endereços precisam ser exatamente os que os desenvolvedores usarão para fazer login em http://console.developers.google.com. Os desenvolvedores serão adicionados ao grupo que concede permissão para acessar a documentação da API de assinaturas.

  2. Envie o ID do projeto de sua solução ao engenheiro de parceiros do Google Cloud Marketplace e solicite permissão para o ID chamar a API. Vários projetos podem ser incluídos na lista de permissões, se necessário.

  3. Ative a API Cloud Billing expandindo o menu próximo ao canto superior esquerdo de https://console.developers.google.com, clicando em APIs e serviços e, em seguida, procurando e ativando a API Cloud Billing.

  4. Crie uma conta de serviço do OAuth2 associada ao projeto e envie o endereço de e-mail dessa conta para o engenheiro de parceiros do Google Cloud Marketplace. Esse usuário será incluído na lista de permissões para ler todas as suas assinaturas e será usado para autorizar todas as solicitações, exceto as feitas por solicitação de permissão do cliente usando uma caixa de diálogo do OAuth.

Por não ser uma API pública, a API de assinatura não está incluída na biblioteca de cliente do Python por padrão. Se você planeja usar a biblioteca de cliente do Python com esta API, precisa também entrar em contato com o engenheiro de parceiros do Google para receber ajuda para acessar o arquivo de descoberta.

Na inicialização de exemplo a seguir, o nome do arquivo de descoberta é definido para o caminho em que foi feito o download do arquivo de descoberta.

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery = f.read()
   f.close()

   # Construct a service from the local documents
   service = build_from_document(discovery,
         base="https://www.googleapis.com/",
         http=http)

A biblioteca de cliente também aceita autenticação OAuth, tanto para credenciais do cliente quanto para contas de serviço do OAuth2. Para mais informações, consulte a documentação do OAuth 2.0 na Biblioteca de cliente de APIs do Google para Python.

Como consultar a API de assinaturas

Para receber permissão de acesso a dados de assinaturas, crie uma conta de serviço OAuth2 e nos informe a conta que pretende usar para autorizar solicitações à API. Em seguida, o Google concederá acesso a essa conta de serviço para ler as assinaturas de todos os clientes. Para mais informações, consulte Uso do OAuth 2.0 para aplicativos de servidor para servidor.

A API é uma API RESTful somente leitura que retorna recursos de assinatura, que podem ser usados para ver as seguintes informações:

  • name: um identificador para um recurso de assinatura único.
  • externalAccountId: um identificador de uma única conta de faturamento.
  • version: um número de versão que é atualizado sempre que o registro é modificado. Isso pode ser usado para detectar facilmente quaisquer alterações desde a última leitura.
  • status: um dos seguintes valores:
    • ACTIVE: a assinatura está ativa no momento e o cliente está apto a receber suporte. Uma assinatura é considerada ativa quando a conta tem uma VM ativa nos últimos 30 dias.
    • COMPLETE: a assinatura não está mais ativa, porque o cliente não tem nenhuma VM ativa em execução com sua solução e não teve nos últimos 30 dias.

  • subscribedResources: uma lista dos recursos abrangidos pela assinatura.
  • startDate: a data em que a assinatura começou, expressa como uma string no formato RFC 3339.
  • endDate: a data em que a assinatura terminou (se tiver terminado), expressa como uma string no formato RFC 3339.
  • Rótulo do carimbo de data/hora do último sinal de funcionamento (com chave): o valor deste rótulo indica o carimbo de data/hora do último sinal de funcionamento de qualquer máquina virtual executando a solução. Por exemplo: cloudmarketplacepartner.googleapis.com/last_heartbeat_us

Quando um cliente clica no link para acessar seu site pelo Console do Google Cloud, é necessário verificar se o cliente está autorizado a usar o link fazendo as seguintes solicitações:

  1. Liste as assinaturas referentes ao código de conta externa.
  2. Encontre a assinatura ativa da solução.
  3. Veja as informações da assinatura usando o código da assinatura.

Se o cliente for um usuário autorizado, a solicitação será bem-sucedida. Caso contrário, a chamada retornará um código de erro não autorizado (HTTP 403).

Isso exige que você solicite a permissão do cliente para ler os dados de assinatura dele durante o processo de inscrição usando um fluxo de solicitação do OAuth padrão.

Solicitações posteriores para atualizar os dados da assinatura usam sua conta de serviço criada anteriormente.

Fluxo de registro de suporte ao cliente

Depois que um cliente tiver implantado a solução por meio do Cloud Marketplace ou pelas APIs Compute Engine, o Console do Google Cloud mostrará um link para seu site a fim de concluir o registro de suporte. O link incluirá o código da conta externa que será usado para essa conta.

É recomendável que o site permita que o cliente crie uma conta e forneça as informações de contato necessárias. O Google não fornecerá nenhuma informação de identificação pessoal do cliente a você. Você é responsável por manter um mapeamento entre a conta do cliente e o ID da conta externa fornecido pelo Google.