Recentemente, precisei extrair dados da API do GitHub e publicá-los em uma planilha do Google para poder compartilhar alguns gráficos sobre a carga de trabalho de revisão de código. Esta postagem é sobre como fiz a autenticação funcionar.

Escrevi um script Node.js porque meu caso de uso era muito complexo para BASH e parecia muito temporário para Go. Inicialmente, o script gerou dados CSV ad hoc que eu poderia copiar manualmente para o Planilhas Google usando o recurso Colar como CSV. Depois de algumas rodadas de cópia manual, eu queria usar meu tempo com sabedoria: estimei que conseguiria fazer uma integração com o Planilhas funcionar em algumas horas e, se assim fosse, isso seria
provavelmente terá retorno dentro de alguns meses.

Além disso: O Planilhas não é meu banco de dados. É minha IU de relatório de dados. Não use o Planilhas como banco de dados.

Levei cerca de 4 horas para fazer isso funcionar, porque a autenticação é difícil. Esta postagem mostra o caminho mais direto para uma solução funcional.

É fácil se distrair com a complexidade de criar um aplicativo oAuth e, embora eu goste especialmente de usar uma conta de serviço dos meus serviços em nuvem, isso é
menos conveniente ao executar localmente.

O truque que aprendi é que a configuração de credenciais padrão do aplicativo da CLI gcloud pode operar como uma espécie de proxy OAuth para o código do Google Workspace, expandindo a forma como ele autentica sua conta com o Google para incluir mais algumas permissões (escopos OAuth).

? Autenticação local com CLI gcloud

Para fazer solicitações de API ao Planilhas Google, ative a API Sheets em seu projeto do Cloud:

$> gcloud services enable sheets.googleapis.com

Operation "operations/acat.p2-480745230567-02564c8d-c6ba-4f60-90bd-13f33e41f0fe" finished successfully.

Defina suas credenciais padrão do aplicativo, reivindicando também alguns escopos OAuth não padrão para que a credencial possa ser usada com planilhas:

$> gcloud auth application-default login --scopes \
   'https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets'

Isso acionará um fluxo OAuth que envolve visitar uma página da web em seu navegador. Dependendo da configuração do terminal, isso pode exibir uma URL ou até mesmo abrir a página.

Quando esse escopo for concedido ao gcloud, o código que pode acessar suas credenciais locais terá acesso de leitura/gravação a todos os seus dados do Planilhas Google. Você pode executar novamente este comando sem os escopos personalizados para ativar e desativar esse acesso conforme necessário.

?️ Inicializar um cliente Node para Planilhas Google

import {google} from 'googleapis';

function sheetsClient() {
    const authConfig = new google.auth.GoogleAuth({
        scopes: [
            // Only 'spreadsheets' scope is needed in the code.
            // gcloud CLI also needs 'cloud-platform' and 'drive'.
            'https://www.googleapis.com/auth/spreadsheets'
        ],
    });
    const auth = await authConfig.getClient();
    return google.sheets({version: 'v4', auth});
}

? Anexar dados à planilha

O exemplo da documentação sobre como anexar dados à planilha
(clique na guia Node.js) funcionou bem. No entanto, não consegui entender como fazer a autenticação funcionar a partir daí. O exemplo funcionou quando entendi o truque acima para adicionar os escopos OAuth ausentes às minhas credenciais de ambiente de desenvolvimento.

Fiz algumas alterações para facilitar a reutilização do cliente, parametrizar a solicitação de maneira diferente e enfatizar como queria que os dados fossem tratados pelo Planilhas.

Meu código para anexar dados à planilha, aproveitando o código de inicialização do cliente acima:

let client;

async function appendDataToSheet(spreadsheetId, tab, values) {
    if (!client) {
        client = sheetsClient();
    }

    try {
        const result = await client.spreadsheets.values.append({
            spreadsheetId,
            range: `${tab}!A2:AG`,
            // Use my data as provided.
            valueInputOption: 'RAW',
            // Inserts rows as part of appending to reduce overwrites.
            insertDataOption: 'INSERT_ROWS',
            requestBody: { values },
        });
        console.log(`${result.data.updates.updatedCells} cells appended.`);
    } catch(e) {
        // Show the error, do not stop. Cross-reference the error with terminal output
        // and decide case-by-case to re-run the script or manually copy data.
        console.error(e);
    }
}

Estou usando "anexar" porque meu script coleta métricas mensais e anexar me permite adicionar novas linhas sem remover as linhas anteriores.

Aqui está um exemplo de como chamar a função appendDataToSheet():

const values = [
  // Each nested array is a spreadsheet row.
  [1, 2, 3, 4, 'luggage'],
  [4, 5, 6, 'N/A', 'sticks'],
];
appendDataToSheet(
  'HPDkfqdu6rfIq5-4uTGDqz2tvmPxDZMul27JFexample',
  'Exported Data Tab',
  values
);

Existem algumas boas dicas sobre como trabalhar com a API do Planilhas nos documentos, como a sugestão de não enviar mais de uma solicitação de API por segundo por planilha. Descobri da maneira mais difícil: substituindo os dados de uma primeira solicitação pelos dados de uma segunda.

? Envie!

Se eu prosseguir com a produção disso, posso passar a usar
Cloud Scheduler e trabalhos do Cloud Run. Deixe-me saber se você gostaria de ler sobre isso.

Foto da capa de Glib Albovsky no Unsplash