OsDevelopers podem usar a API SDM para conferir e gerenciar dispositivos Google Nest em nome de users. A API SDM valida que o user gerencie os dispositivos que estão sendo acessados, que o user consentiu com a developer leitura ou gravação das características de cada dispositivo e que o developer foi colocado na lista de permissões de acesso a cada característica.
Para usar a API SDM no gerenciamento de dispositivos, o developer precisa ser autorizado pelo user.
Para conferir um tutorial do processo de autorização, consulte a página Autorizar uma conta do Device Access Guia de início rápido.
Para receber ajuda com a solução de problemas de autorização, consulte Erros de autorização.
Fluxo do OAuth
A API SDM usa um fluxo de três etapas do Google OAuth para user autorização:
- Quando a user quer autorizar a developer para gerenciar dispositivos Nest, o developer envia o user para o PCM, onde o user faz login na Conta do Google.
- O user seleciona as permissões a serem concedidas para o developer no PCM.
- O user concede consentimento por meio do OAuth, concedendo ao developer um código de autorização.
- O developer usa o código de autorização para recuperar um token de acesso.
- O developer usa o token de acesso com chamadas à API SDM para gerenciamento de dispositivos.
Para saber mais sobre o OAuth do Google e como fazer a configuração, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.
Gerente de conexões de parceiros (PCM)
O PCM é fornecido pela API SDM. É uma visualização que lista todas as estruturas, dispositivos e opções de acesso que o user pode conceder ao developer. O user escolhe o que conceder acesso durante o processo de autorização e mantém o controle desse acesso.
As opções selecionadas no PCM são mapeadas para grupos de características, que são coleções de características às quais o developer terá acesso. Alguns grupos de atributos são vinculados, dependendo do tipo de integração que o developer oferece ao user. O user precisa conceder permissões para esses grupos de atributos vinculados para ativar essa integração. Caso contrário, o usuário pode conceder permissões para grupos de características individuais e não vinculadas, conforme desejar.
Ativar PCM
Para ativar a visualização PCM para um user, substitua o endpoint padrão do OAuth 2.0 da API do Google por esse novo endpoint OAuth para a solicitação de autorização:
https://nestservices.google.com/partnerconnections/project-id/auth
Use estes parâmetros no URL:
Parâmetro | Descrição |
---|---|
redirect_uri |
O URI para direcionar o user após a autorização bem-sucedida. |
client_id |
O ID do cliente OAuth 2.0 do seu projeto do Google Cloud. Verifique se ele é o mesmo associado ao ID Project . Um ID do cliente OAuth precisa ser válido e exclusivo para um projecte não pode ser compartilhado com outros projects. |
access_type |
Valor a ser usado: offline |
prompt |
Valor a ser usado: consent |
response_type |
Valor a ser usado: code Um código de autorização é esperado em retorno. |
scope |
Valor a ser usado: https://www.googleapis.com/auth/sdm.service
O escopo da API SDM. |
state |
Opcional. Um valor opaco usado pelo cliente developer para manter o estado entre a solicitação e o callback. |
Exemplo de URL do PCM:
https://nestservices.google.com/partnerconnections/
2f6989ca-c756-4625-8cdc-d5b1edfb2dcd/auth?
redirect_uri=https://www.example.com/api/link/M258KP8OWYZDVQ&
client_id=418235700063-sdkiav89orn5r1nvrcr5t210qqjimq8l.apps.googleusercontent.com&
access_type=offline&
prompt=consent&
response_type=code&
scope=https://www.googleapis.com/auth/sdm.service
Depois que o user concede a permissão, um código de autorização é retornado
como o parâmetro code
no URI de redirecionamento. Use esse código para receber um token de
acesso.
Adicionar PCM ao app
No app, adicione a visualização PCM usando este URL:
https://nestservices.google.com/partnerconnections
Quando o user faz login, essa página mostra todos osDevice Access developers vinculados, além de uma lista de todas as estruturas e dispositivos com alternâncias para conceder e revogar permissões. O user também pode desconectar uma conexão de parceiro por parceiro nessa página.
Apps não verificados
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.
Tokens de acesso
Todas as chamadas para a API SDM para gerenciar estruturas e dispositivos autorizados precisam usar o token de acesso exclusivo concedido ao developer pelo user durante a autorização. Os tokens de acesso têm curta duração e precisam ser atualizados regularmente para garantir o acesso contínuo.
Se a user revogar posteriormente developer o acesso a uma estrutura ou um dispositivo, o token de acesso vai expirar imediatamente e não poderá ser atualizado, e o developer não poderá mais chamar a API SDM em nome disso user.
Revogar a autorização da conta
Há várias maneiras de revogar a autorização de uma conta do Google. O método preferencial é o usuário usar o Partner Connections Manager (PCM) para modificar as permissões da conta. Consulte Modificar as permissões da conta para mais informações. Um token de acesso também pode ser revogado pelos seguintes métodos:
O usuário pode revogar em https://myaccount.google.com/permissions.
O desenvolvedor pode transmitir o token de acesso ao endpoint
https://oauth2.googleapis.com/revoke
. Para saber mais sobre o OAuth do Google e a revogação de tokens, consulte Revogar um token.
Visualizações da Web incorporadas
Uma nova política de navegadores seguros proíbe solicitações do Google OAuth em bibliotecas de navegador incorporadas, comumente chamadas de WebViews incorporadas. Todas as visualizações da Web incorporadas serão bloqueadas. As bibliotecas com WebView incorporado são problemáticas porque permitem que um desenvolvedor malicioso intercepte e altere as comunicações entre o Google e os usuários. As WebViews incorporadas não só afetam a segurança da conta, mas a usabilidade do aplicativo.
Se essa política afetar você, consulte o artigo de suporte Próximas alterações de segurança no endpoint de autorização do OAuth 2.0 do Google em WebViews incorporados.