Configurar o Google Cloud e o OAuth

O acesso à API Google Health é fornecido pelo Google Cloud. Para ativar a API e autorizar uma Conta do Google, você precisa de um projeto do Google Cloud.

Se você já é um desenvolvedor da API Fitbit ou está começando a usar a API Google Health API, conclua esta etapa para fazer chamadas à API.

Criar um projeto e um cliente OAuth

Use o botão Ativar a API e receber um ID do cliente OAuth 2.0 para ativar a API Google Health e receber um ID do cliente OAuth 2.0:

  1. Se você já tem um projeto na nuvem do Google Cloud que quer usar na API Google Health, faça login na conta de admin desse projeto. Em seguida, selecione o projeto na lista de projetos disponíveis depois de clicar no botão. Caso contrário, crie um novo projeto.
  2. Selecione Servidor da Web quando perguntar "De onde você está chamando?".
  3. Insira https://www.google.com como o valor de URIs de redirecionamento autorizados. Um URI de redirecionamento é necessário para receber um código de autorização usando o OAuth 2.0.
  4. Quando a configuração estiver concluída, copie os valores do ID do cliente OAuth 2.0 e da chave secreta do cliente e faça o download do JSON de credenciais para sua máquina local.
Ativar a API e receber um ID do cliente OAuth 2.0

Se você quiser configurar manualmente seu projeto do Google Cloud ou verificar a configuração e recuperar suas credenciais novamente:

  1. Ative a API Google Health na página de ativação da API.
  2. Receba um ID do cliente OAuth 2.0 na página "Credenciais".

Para mais informações sobre como configurar o OAuth 2.0 usando o console do Google, consulte Usar o OAuth 2.0 para acessar as APIs do Google.

Adicionar usuários de teste

Por padrão, os clientes OAuth recém-criados estão em um estado não verificado com um limite de 100 usuários para fins de teste e produção. Para ativar a autorização durante esse período, adicione manualmente o endereço de e-mail de cada usuário à lista de usuários de teste na configuração do projeto.

Atualize a lista de usuários de teste na Público-alvo página:

  1. Nessa página, o "Status de publicação" precisa estar definido como Teste e o "Tipo de usuário" como Externo.
  2. Na seção "Usuários de teste", clique em + Adicionar usuários. Insira o endereço de e-mail de todos os usuários de teste que podem conceder permissão ao seu app para acessar os dados de saúde.
  3. Clique em Salvar.

Para oferecer suporte a mais de 100 usuários com a API Google Health, é necessário concluir uma análise de segurança de terceiros. Mais informações estão disponíveis na Central de Ajuda da verificação de apps OAuth.

Adicionar escopos

É necessário especificar os escopos que seu cliente pode chamar na página "Acesso a dados":

  1. Nessa página, clique em Adicionar ou remover escopos.
  2. Na coluna "API", pesquise "API Google Health". Selecione os escopos necessários para seu aplicativo.
  3. Depois de selecionar todos os escopos necessários, clique em Atualizar para voltar à página "Acesso a dados".
  4. Clique em Salvar.

Antes de selecionar os escopos, revise a implementação deles.

Você terminou de configurar o ID do cliente e agora pode fazer chamadas para a API Google Health.

Atualizar escopos

Você pode pedir ao usuário para autorizar novamente seu app definindo o parâmetro de solicitação como consentimento na solicitação de autenticação. Quando prompt=consent é incluído, a tela de permissão é exibida sempre que o app solicita a autorização de escopos de acesso, mesmo que todos os escopos tenham sido concedidos anteriormente ao projeto das APIs do Google.

Para adicionar ou mudar escopos usando o parâmetro prompt=consent, siga estas etapas:

  1. Identifique a lista completa de escopos de que seu aplicativo precisa. Isso inclui os escopos atuais e todos os novos que você precisa adicionar.

  2. Modifique o parâmetro de escopo no URL de autorização para incluir a lista atualizada de valores de escopo separados por espaço.

  3. Anexe prompt=consent aos parâmetros de URI de autenticação. Isso força o servidor de autorização a pedir o consentimento do usuário antes de retornar informações ao cliente.

    O exemplo a seguir mostra uma solicitação HTTPS GET para o endpoint de autorização do OAuth 2.0 do Google solicitando vários escopos com prompt=consent anexado:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Quando o usuário segue o link atualizado, uma página de consentimento é exibida com todos os escopos solicitados. Depois que o usuário clica em "Continuar" ou "Permitir", você recebe um novo código de autorização que pode ser trocado por tokens que abrangem o conjunto completo de escopos.

    Inclua prompt=consent somente quando necessário, como quando você precisa receber um novo token de atualização ou quando os escopos solicitados mudaram.

Bibliotecas de cliente OAuth2

A lista de bibliotecas de cliente OAuth2 disponíveis usadas para integração com frameworks populares pode ser encontrada em Usar o OAuth 2.0 para acessar as APIs do Google.

Tokens de atualização

Para manter o acesso de longo prazo às APIs do Google sem exigir a reautenticação constante do usuário, seu aplicativo precisa usar um token de atualização. Para detalhes abrangentes de implementação, incluindo as solicitações e os parâmetros HTTP específicos necessários, consulte a documentação da plataforma de identidade do Google.

Para trocar um token de atualização por um token de acesso, faça uma chamada HTTPS POST para o endpoint de token do OAuth 2.0 do Google. O snippet a seguir mostra um exemplo de solicitação e resposta:

Solicitação

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Resposta

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Quando atualizar um token

Atualize os tokens de atualização sob demanda como parte da progressão natural de uma sessão ativa do usuário quando os tokens de acesso expiram ou estão perto de expirar. Evite atualizar tokens em lote (por exemplo, usando um job ou serviço cron programado para atualizar tokens de todos os usuários em um horário fixo).

Não é recomendável atualizar tokens em lote pelos seguintes motivos:

  • A atualização em lote impede o alinhamento das atualizações de token com padrões de sincronização de usuários ativos. Embora seja possível usar a chamada "Receber dispositivos" para conferir o último horário de sincronização de um usuário, isso exige um escopo OAuth adicional que os usuários não são obrigados a aprovar.
  • O processamento em lote atualiza tokens que não precisam ser atualizados, causando uma sobrecarga de processamento redundante para seus sistemas e para os servidores do Google.
  • Se ocorrer um problema de rede ou uma interrupção do servidor durante uma atualização em lote, todos os tokens de usuário afetados serão impactados de uma só vez. A atualização de tokens individualmente durante a progressão natural das sincronizações do usuário isola o impacto de falhas temporárias em um único usuário.
  • O diagnóstico de problemas é mais difícil com jobs em lote. Como as solicitações em lote acontecem com menos frequência e geram uma grande quantidade de entradas de registro de uma só vez, é mais difícil identificar o início de um incidente.
  • Picos de alta simultaneidade em solicitações de token durante execuções em lote aumentam a probabilidade de atingir limites de taxa ou de erros de autenticação intermitentes.

Comportamento do token durante o teste

Esteja ciente de como os tokens de atualização se comportam dependendo do status de publicação do seu projeto do Google Cloud:

  • Modo de teste:se a tela de permissão OAuth estiver configurada com um status de publicação "Teste", os tokens de atualização emitidos serão baseados no tempo e expirarão após 7 dias. Durante esse período, você vai receber um único token de atualização que permanece válido e pode ser usado para receber novos tokens de acesso até atingir a data de validade.
  • Modo publicado:depois que o app é movido para o status "Em produção", os tokens de atualização geralmente não expiram, a menos que sejam revogados ou permaneçam não utilizados por um período prolongado (normalmente seis meses).

Para uma experiência do usuário integrada, publique o aplicativo antes que ele seja movido para um ambiente de produção para evitar expirações de token de sete dias.

Proteção entre contas (API RISC)

Ative o compartilhamento e a coordenação de riscos e incidentes (RISC, na sigla em inglês) se quiser receber notificações sobre mudanças nos tokens de eventos ou na vinculação de contas, como contas desconectadas ou tokens revogados, para limpar os tokens armazenados e atualizar o status da conexão da interface. A ativação da API RISC é opcional.

Para ativar a API RISC no seu projeto do Google Cloud:

  1. Abra a página da API RISC no console do Google Cloud. Verifique se o projeto usado para a API Google Health está selecionado.
  2. Leia os Termos do RISC e verifique se você entende os requisitos.
  3. Clique em Ativar se você concordar com os termos.

Depois de ativar a API, crie e registre um endpoint HTTPS para receber e validar os tokens de eventos enviados pelo Google.

Para mais informações sobre a proteção entre contas e o RISC, consulte Proteger contas de usuário com a proteção entre contas.