Desmistificando a API de Alterações do Google Drive - Emptor

Não faz muito tempo lançamos nossa nova integração com o Google Sheets, fornecendo uma interface de usuário para nossa API de verificação de antecedentes. Nossos clientes realmente gostam dessa nova forma de interagir com nossa API, pois reduz sua carga de trabalho e simplifica o processo de revisão. Os clientes recebem uma planilha e voilá — eles não precisam construir nada para utilizar nosso sistema. Eles podem colocar os dados do perfil na planilha fornecida e os resultados são publicados assim que a verificação de antecedentes for concluída para cada perfil. Não é foguete espacial - queremos tornar tudo o mais fácil possível para nossos clientes.

Como nossa infraestrutura de produtos é construída em serviços diferentes da Google Cloud Platform, trazê-los para nossa pilha de desenvolvimento trouxe alguns desafios para nós durante o desenvolvimento dessa ferramenta. Levou algumas semanas de planejamento antes de chegarmos à conclusão de que nossa principal preocupação era encontrar uma maneira de dar a nossos clientes o poder de instanciar quantas execuções de verificação de antecedentes forem necessárias da forma mais limpa e simples possível.

Com esse objetivo em mente, desenvolvemos um complemento do Google Sheets que permite que os clientes iniciem o processo. No entanto, não funcionou de acordo com nossas expectativas e precisávamos de um complemento privado com o Google Sheets compartilhado fora de nossa organização GCP. Infelizmente, descobrimos que isso não é possível com o conjunto de recursos atual oferecido por um complemento do Google Sheets.

Em seguida, construímos uma solução baseada em sondagem que verifica todas as planilhas de todos os nossos clientes a cada poucos minutos. Mas essa solução é eficiente apenas com um pequeno número de planilhas, devido ao fato de que a API do Google Sheets oferece uma cota muito limitada (ou seja, 100 solicitações/100 segundos). Começamos a enfrentar problemas de escalabilidade à medida que incorporávamos mais clientes a este novo produto e concluímos que precisávamos de um sistema que verificasse apenas certas planilhas, aquelas que tiveram alterações feitas pelo proprietário da planilha.

Para atingir nosso novo objetivo, mergulhamos na API de alterações do Google Drive, que parecia promissora. A API do Google Drive oferece dois métodos para ler as alterações, embora, na verdade, ela forneça apenas um método, e o segundo método é projetado para ser integrado ao primeiro método para evitar fazer solicitações desnecessárias.

Método #1: Sondagem com Changes.list

Este é um método bastante direto. No entanto, requer sondagem do mesmo ponto de extremidade continuamente para receber as alterações. Eis como funciona:

Recupere o token da página inicial usando o ponto de extremidade Changes.getStartPageToken. Ele retorna o seguinte objeto JSON em resposta:
```
{
    "kind": "drive#startPageToken",
    "startPageToken": "string"
}
```

Use esse token para recuperar os itens de alteração usando o ponto de extremidade Changes.list. Isso também fornecerá um token da próxima página. Ele retorna o seguinte objeto JSON em resposta:

{
    "kind": "drive#changeList",
    "nextPageToken": "string",
    "newStartPageToken": "string",
    "changes": [ "changes Resource" ]
}

Onde cada item de alteração é como o seguinte objeto JSON:

{
    "kind": "drive#change",
    "type": "string",
    "changeType": "string",
    "time": "datetime",
    "removed": "boolean",
    "fileId": "string",
    "file": "files Resource",
    "teamDriveId": "string",
    "driveId": "string",
    "teamDrive": "teamdrives Resource",
    "drive": "drives Resource"
}

Repita a Etapa 2 com o token da próxima página recebido na Etapa 2.

A única parte complicada deste método é que, para continuar recebendo as alterações, o sistema precisa fazer solicitações contínuas com os tokens nextPageToken. É um loop infinito.

Método #2: Notificações push com Changes.watch

Este método adiciona uma camada acima do primeiro método, usando uma URL de webhook para corrigir esse loop infinito. Com este método, não precisamos mais fazer sondagem. Sempre que ocorrer uma alteração, o Google fará uma solicitação HTTP POST vazia para a URL do webhook que registramos. Eis como funciona:

Registre seu domínio no Google Search Console usando o método de domínio. O método de prefixo de URL não funcionará, pois seu domínio também precisa ser registrado com seu projeto GCP, que não é compatível com prefixo de URL.
Registre sua URL usando o ponto de extremidade Changes.watch.

A partir deste ponto, para cada alteração que ocorrer, o Google fará uma solicitação HTTP POST com corpo vazio para a URL que você acabou de registrar. Ele retorna o seguinte objeto JSON na resposta para registrar a URL do Webhook:

{
    "kind": "api#channel",
    "id": "string",
    "resourceId": "string",
    "resourceUri": "string",
    "token": "string",
    "expiration": "long",
    "type": "string",
    "address": "string",
    "payload": "boolean",
    "params": { "(key)": "string" }
}

Observe que esta etapa precisa ser integrada ao primeiro método. Para cada solicitação POST que sua URL receber, ela precisa fazer uma única solicitação ao ponto de extremidade Changes.list para realmente obter a lista de alterações e, em seguida, processá-las. Em outras palavras, este é o ponto em que o primeiro método começa. Mas, em vez de fazer sondagem, ele só faz a solicitação quando há notificações.

Se você deseja cancelar o registro de sua URL do webhook e parar de receber as notificações de alteração, você pode fazer uma solicitação HTTP POST para Channels.stop para fazer isso.

Comparação dos Dois Métodos

Título	Notificações push	Sondagem
Sondagem	– Não é necessária	– Necessária
Obtenção de Alterações	– Para cada alteração, a URL do webhook registrado é chamada sem nenhum item de alteração	– Fazer uma solicitação de sondagem retorna uma lista de itens de alteração, com a opção de limitar o número de alterações recebidas por solicitação
Expiração do Webhook	– O registro do webhook expira após uma semana; o tempo limite padrão é definido para uma hora	– Sem expiração
Itens de Alteração Duplicados	– Alterações duplicadas são possíveis. Observe que provavelmente haverá um período de “sobreposição” de tempo em que os dois canais de notificação para o mesmo recurso estão ativos.	– Cada token é uma referência a uma lista de itens de alteração. Deve ser responsabilidade do ponto de extremidade retornar itens de alteração não duplicados
URL do Webhook	– Uma URL de webhook acessível publicamente precisa ser registrada com a API	– Nenhuma URL de webhook é necessária
Critério do Item de Alteração	– Abrir um arquivo não é considerado um item de alteração	– Abrir um arquivo é considerado um item de alteração. Isso ocorre devido à alteração nas informações de metadados que armazenam valores de data/hora
Itens de Alteração Antigos	– Inclui apenas as alterações feitas após o registro do webhook	– Cerca de 2 meses de alterações antigas são recuperadas se um novo token de página inicial for usado. Isso pode ser evitado armazenando e usando o último token usado

Infelizmente, esses métodos não fornecem informações sobre a alteração real que foi feita. Embora inclua o fileId no item de alteração, também não especifica quem fez a alteração ou em que momento ela foi feita. Por exemplo, não diz: “John modificou a Coluna 3 da Linha 5 do arquivo XYZ em 14 de agosto de 2020 às 5:00 da manhã”. Ele apenas diz que “O arquivo XYZ tem uma alteração”.

Felizmente, a API do Google Drive também fornece a API de Revisões, que pode nos ajudar a descobrir mais detalhes sobre a alteração que ocorreu. Com ela, um histórico de revisões pode ser recuperado para um arquivo específico usando o ponto de extremidade Revisions.list, onde cada item de revisão se parece com isso:

{
    "kind": "api#channel",
    "id": "string",
    "resourceId": "string",
    "resourceUri": "string",
    "token": "string",
    "expiration": "long",
    "type": "string",
    "address": "string",
    "payload": "boolean",
    "params": { "(key)": "string" }
}

Hurra! Agora sabemos o último modifiedTime e o usuário que o modificou (via lastModifyingUser).

Mas espere, e se o último item de revisão na lista de revisões tiver sido adicionado à lista, logo antes de você recuperá-lo? E se o item de revisão que você estava procurando vier antes disso? E se o tempo que você recebeu o item de alteração fosse muito depois de quando a alteração realmente aconteceu? Como podemos ter certeza de que recebemos a alteração a tempo? Como sabemos se o histórico de revisões contém exatamente o item que esperamos processar? A lista de perguntas continua e não há respostas óbvias.

A API do Google Drive pode funcionar para muitos problemas, mas os problemas que precisamos resolver exigem vários recursos que acreditamos atualmente estarem faltando nesta API. Precisamos de uma maneira de poder receber o item de alteração quando ele ocorrer, juntamente com todas as informações relevantes relacionadas a ele. A API do Google Drive parecia ser uma ferramenta promissora, mas depois de passarmos algum tempo pesquisando todos os seus segredos obscuros, descobrimos que ela atualmente não pode atender às nossas necessidades. Além disso, os recursos (custo e tempo) necessários para construir uma solução com base nos recursos existentes da API do Google Drive são muito mais caros do que seus benefícios.

O Google Sheets é ótimo para nossos clientes e estamos trabalhando atualmente para trazer um sistema avançado para nossos clientes com uma interface de usuário robusta que eventualmente substituirá essa integração. Ele fornecerá uma experiência amigável ao consumidor de nossa API com vários novos recursos. Junto com isso, também lançaremos um wrapper Python de código aberto para nossa API para permitir que nossos clientes construam suas próprias soluções personalizadas usando nossa API.

Esperamos que você agora tenha uma compreensão um pouco melhor de como a API do Google Drive funciona e como ela pode (ou não) atender às suas necessidades.

Realize verificações de antecedentes na LATAM com a Emptor.