Autorizar uma conta

Com os projetos do Google Cloud e do Device Access criados, você pode autorizar uma Conta do Google com um dispositivo Google Nest compatível para a API SDM.

Para conferir estruturas e dispositivos, vincule uma Conta do Google ao seu projetoDevice Access usando o PCM. O PCM permite que o user conceda permissão para que developers acessem as estruturas e os dados do dispositivo.

Neste guia, você vai atuar como user e developer.

  1. Abra o link a seguir em um navegador da Web, substituindo:

    1. project-id pelo ID Device Access Project
    2. oauth2-client-id com o ID do cliente OAuth2 das suas credenciais do Google Cloud
    https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service
  2. Se você tiver feito login no Google com várias contas recentemente, talvez uma tela inicial Escolher uma conta seja mostrada com uma lista das suas Contas do Google. Se sim, selecione a Conta do Google vinculada aos dispositivos que você quer autorizar para Device Access.
  3. A tela Permissões do Google Nest é o PCM. Aqui, você pode conceder permissões de estrutura e dispositivo. Ative as permissões para sua casa (Etapa 1) e todos os dispositivos nela que têm suporte da API SDM (Etapa 2), depois clique em Próxima.
  4. Na tela Choose an account to continue to Project Name, em que Project Name é o nome do seu projeto do Google Cloud, selecione a Conta do Google que você quer autorizar para a API SDM. Use a mesma Conta do Google de antes.
  5. Depois de escolher uma conta, você pode receber uma tela de aviso informando que o Google não verificou este app. Nesse caso, para continuar, clique na opção Advanced e em Go to Project Name (unsafe). Consulte O Google não verificou este app para mais informações.
  6. Na tela Grant Project name permission, clique em Allow para conceder ao projeto permissão de acesso à sua Conta do Google.
  7. Na tela Confirmar suas escolhas, verifique se as permissões que você quer conceder estão marcadas e clique em Permitir para confirmar.

  8. Você será redirecionado para https://www.google.com. O código de autorização será retornado como o parâmetro code no URL, que precisa estar neste formato:

    https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
  9. Copie o código de autorização.

Receber um token de acesso

Use o código de autorização para recuperar um token de acesso que pode ser usado para chamar a API SDM.

  1. Abra um terminal e execute o seguinte comando curl, substituindo:

    1. oauth2-client-id e oauth2-client-secret com o ID e a chave secreta do cliente OAuth2 das suas Credenciais do Google Cloud
    2. authorization-code pelo código que você recebeu na etapa anterior
    curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'

  2. O Google OAuth retorna dois tokens, um de acesso e outro de atualização.

    {
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}
     Copie os dois valores. O token de acesso é usado para chamar a API SDM, e o token de atualização é usado para receber um novo token de acesso.

Fazer uma chamada de lista de dispositivos

A autorização não é concluída até que você faça a primeira chamada devices.list com o novo token de acesso. Essa chamada inicial finaliza o processo de autorização e ativa os eventos se você já tiver configurado uma assinatura do Pub/Sub.

Use curl para fazer esta chamada para o endpoint devices:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

Uma chamada bem-sucedida retorna uma lista de dispositivos vinculados ao seu projeto Device Access. Cada dispositivo tem uma lista exclusiva de características disponíveis:

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

Como usar um token de atualização

Os tokens de acesso para a API SDM são válidos apenas por uma hora, conforme observado no parâmetro expires_in retornado pelo Google OAuth. Se o token de acesso expirar, use o token de atualização para conseguir um novo.

O comando é semelhante ao do token de acesso, exceto pelo uso de um grant_type diferente.

  1. Abra um terminal e execute o seguinte comando curl, substituindo:

    1. oauth2-client-id e oauth2-client-secret com o ID e a chave secreta do cliente OAuth2 das suas Credenciais do Google Cloud
    2. refresh-token com o código que você recebeu ao receber o token de acesso.
    curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'

  2. O Google OAuth retorna um novo token de acesso.

    {
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

Solução de problemas

Para saber mais sobre o OAuth do Google, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

O token de atualização continua expirando

Os tokens de atualização podem parar de funcionar após sete dias se o ID do cliente não for aprovado. A validade de sete dias do token não está relacionada a aprovações comerciais ou do sandbox. Uma conta de serviço ou de usuário precisa ter o ID do cliente OAuth 2.0 aprovado e colocado em produção para ter uma vida útil mais longa do token. Consulte Validade do token de atualização para mais informações.

Acesso negado

Se você tiver configurado a tela de consentimento do OAuth no Google Cloud e o tipo de usuário for Externo, você vai receber um erro "Acesso negado" se tentar vincular uma conta do Google que não está listada como usuário de teste no seu app. Adicione a conta do Google à seção Usuários de teste na tela de consentimento do OAuth.

Erro do Partner Connections Manager (PCM)

Para receber ajuda com erros encontrados ao acessar o PCM, consulte Referência de erros do Gerenciador de conexões de parceiros (PCM).

O Google não verificou este app

A API SDM usa um escopo restrito, o que significa que todos os apps que usam esse escopo durante a autorização serão "não verificados", a menos que a verificação da API OAuth seja concluída. A verificação da API OAuth não é necessária ao usar Device Access para uso pessoal.

Talvez você veja uma tela "O Google não verificou este app" durante o processo de autorização, que aparece se o escopo sdm.service não estiver configurado na tela de consentimento do OAuth no Google Cloud. Para ignorar essa tela, clique na opção Advanced e depois em Go to Project Name (unsafe).

Consulte a Tela de app não verificado para mais informações.

Cliente inválido

Ao tentar acessar um token de acesso ou de atualização, você vai receber um erro "Cliente inválido" se fornecer um segredo de cliente OAuth 2.0 incorreto. Verifique se o valor client_secret que você está usando nas chamadas de token de acesso e de atualização é o do ID do cliente OAuth 2.0 que está sendo usado, conforme encontrado na página Credenciais do Google Cloud.

Solicitação inválida, escopo obrigatório ausente

Depois de conceder permissões no PCM, você pode encontrar um erro "Solicitação inválida" de "Parâmetro obrigatório ausente: escopo". Verifique se o valor de scope que você está usando nas chamadas de autorização é o mesmo que você definiu para o cliente OAuth 2.0, como encontrado na página Credenciais do Google Cloud.

Falha na correspondência do URI de redirecionamento

Durante a autorização, você pode encontrar um erro de "Redirect uri mismatch". Verifique se o valor de redirect_uri que você está usando nas chamadas de autorização é o mesmo que você definiu para o cliente OAuth 2.0, conforme encontrado na página Credenciais do Google Cloud.

Modificar as permissões da conta

Para modificar as permissões concedidas a um projeto Device Access ou desconectá-lo inteiramente, acesse o PCM:

https://nestservices.google.com/partnerconnections

Essa página mostra todos os serviços de desenvolvedores de terceiros (projetosDevice Access ) conectados à sua conta. Selecione o Device Access projeto que você quer mudar. Use a próxima tela para modificar as permissões conforme necessário.

Para revogar apenas permissões específicas de um serviço autorizado, ative as permissões que você quer revogar e clique na seta de retorno para salvar.

Para desconectar um serviço autorizado por completo, clique em Desvincular sua Conta do Google para revogar todas as permissões e tokens de acesso que o projeto recebeu para a conta.

Se o PCM não mostrar o serviço desejado, talvez seja necessário fazer uma chamada de lista de dispositivos primeiro.

Referência rápida

Use esta referência para implementar rapidamente as etapas de autorização de um user e vincular a Conta do Google .

Para usar esta referência rápida, edite cada variável de marcador de posição nos exemplos de código com os valores da sua integração específica e copie e cole conforme necessário:

1 PCM

Abra o link a seguir em um navegador da Web, substituindo:

  1. project-id pelo ID Device Access Project
  2. oauth2-client-id com o ID do cliente OAuth2 das suas credenciais do Google Cloud
https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service

2 Código de autenticação

Você será redirecionado para https://www.google.com. O código de autorização é retornado como o parâmetro code no URL, que precisa estar neste formato:

https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service

3 Token de acesso

Use o código de autorização para recuperar um token de acesso que pode ser usado para chamar a API SDM.

Abra um terminal e execute o seguinte comando curl, substituindo:

  1. oauth2-client-id e oauth2-client-secret com o ID e a chave secreta do cliente OAuth2 das suas Credenciais do Google Cloud
  2. authorization-code pelo código que você recebeu na etapa anterior

O Google OAuth retorna dois tokens, um de acesso e outro de atualização.

Solicitação

curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'

Resposta

{
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

4 Chamada de API

A autorização não é concluída até que você faça a primeira chamada devices.list com o novo token de acesso. Essa chamada inicial finaliza o processo de autorização e ativa os eventos se você já tiver configurado uma assinatura do Pub/Sub.

É necessário usar uma das chamadas de API listadas para o escopo especificado para concluir a autorização.

sdm.service

dispositivo

Consulte a referência da API devices.list para mais informações.

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

5 Token de atualização

Os tokens de acesso para a API SDM são válidos por apenas uma hora, conforme observado no parâmetro expires_in retornado pelo Google OAuth. Se o token de acesso expirar, use o token de atualização para conseguir um novo.

Abra um terminal e execute o seguinte comando curl, substituindo:

  1. oauth2-client-id e oauth2-client-secret com o ID e a chave secreta do cliente OAuth2 das suas Credenciais do Google Cloud
  2. refresh-token com o código que você recebeu ao receber o token de acesso.

O Google OAuth retorna um novo token de acesso.

Solicitação

curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Resposta

{
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}
Anterior
1. Começar
Próxima
3. Usar a API