Usando os comandos Slash do Slack para enviar dados do Slack para o Google Sheets

Como trabalho em casa, a maioria das minhas interações diárias de trabalho acontece pelo Slack. É o meu equivalente ao bebedouro. Um lugar para sair e discutir ideias com os amigos.

Faço parte de um canal de recomendações de livros. As pessoas compartilham livros o tempo todo, mas eles desaparecem rapidamente, perdidos em um mar de mensagens.

Eu precisava de uma maneira de registrar os livros recomendados pelas pessoas.

Então, criei um pequeno aplicativo do Slack para enviar dados de recomendação de livros diretamente para uma planilha do Google, usando o Google Apps Script.

Ao final deste tutorial, o senhor terá criado seu próprio aplicativo Slack para registrar dados em uma planilha do Google.

Aqui está ele em ação:

O que são os comandos Slack Slash?

Os Slack Slash Commands permitem que os usuários acionem uma interação com seu aplicativo diretamente da caixa de mensagens no Slack.

Digite a barra na caixa de mensagens do Slack e você verá a lista de comandos de barra padrão:

Por exemplo, /active, /away, /archive, /invite, /mute, /shrug

são todos exemplos de Slack Slash Commands.

Até o final deste tutorial, o senhor terá criado seu próprio Slash Command, que também aparecerá nesta lista:

Confira a seção Documentação do Slack para saber mais sobre os Comandos Slash.

Usando Slash Commands do Slack para enviar dados para o Google Sheets

Configuração inicial com o Google Sheets e o Apps Script

Obviamente, para que isso funcione, o senhor precisa de um Google Sheet para atuar como armazenamento de dados, portanto, a primeira etapa é criar um novo Google Sheet. Usaremos o Script de aplicativos, a linguagem de script baseada em Javascript, para adicionar funcionalidade a essa Planilha do Google.

Em seguida, abra o editor Apps Script no menu Ferramentas: Tools > Script editor

Exclua o código myFunction() padrão e substitua-o pelas linhas a seguir:

function doPost(e) {
  if (typeof e !== 'undefined') {
    var ss = SpreadsheetApp.getActiveSpreadsheet();
    var sheet = ss.getSheetByName('Sheet1');
    sheet.getRange(1,1).setValue(JSON.stringify(e));
  }
}

Quando seu aplicativo Slack envia ao aplicativo Google Apps Script uma solicitação HTTP POST, o Apps Script executa essa função doPost(e), que cola os dados como uma string na célula A1 da Planilha 1 da sua Planilha Google.

Antes de fazer isso, porém, o senhor precisará publicar esse projeto do Apps Script como um Web App.

Na janela do Script Editor, selecione Publish > Deploy as web app…

O senhor precisa definir o acesso para “Qualquer pessoa, mesmo anônima“, caso contrário, o senhor verá um 401_client_error message no Slack quando o senhor tenta usar o comando Slash.

Quando o senhor clica em Deploy, é solicitado a autorizar seu aplicativo.

Quando isso for concluído, o senhor verá um pop-up de confirmação com o URL do aplicativo Web atual. Copie-o, pois o senhor precisará dele mais tarde no aplicativo Slack.

Mais tarde, ao fazer alterações no código do script, o senhor precisará voltar para Publish > Deploy as web app… para criar uma nova versão e atualizá-la:

Ok, essa é a configuração do Google Sheet (por enquanto). Vamos voltar ao Slack e criar um novo aplicativo.

Criando seu aplicativo do Slack

Vá para a seção Página inicial da API do Slack e clique em “Start Building” (Iniciar criação). (O senhor terá que fazer login, caso ainda não o tenha feito).

Na janela pop-up “Create a Slack App” (Criar um aplicativo Slack), dê um nome ao seu aplicativo e escolha o Slack Workspace ao qual ele está anexado.

Quando o aplicativo tiver sido criado, você deverá escolher “Slash Commands” na seção Recursos e depois Criar novo comando

Na nova janela, defina o comando de barra (por exemplo, /book) e cole o URL do aplicativo do Google como URL de solicitação:

Clique em Salvar.

O último passo é “Instalar o aplicativo em seu espaço de trabalho“, que está na seção Configurações > Informações básicas na barra lateral.

Clique em Install App e, na tela seguinte, o senhor precisará autorizar o aplicativo.

Quando isso for feito, o senhor verá duas marcas de seleção verdes abaixo de Basic Information (Informações básicas) do seu aplicativo:

Essa é toda a configuração feita! Fácil, não é?

Vamos testá-lo!

Envio de dados do Slack para o Planilhas Google

No espaço de trabalho do aplicativo Slack, digite o comando Slash e o título de um livro, por exemplo:

/book the innovator’s dilemma (o dilema do inovador)

Esperamos que o senhor receba uma bagunça de HTML de aparência feia de volta na sua caixa de mensagens do Slack. Vamos corrigir isso daqui a pouco.

Mas volte a olhar para sua Planilha do Google. O senhor deve ver uma longa sequência de dados na célula A1, com informações sobre o seu canal do Slack e o título do livro.

Bum! É isso que o senhor quer.

Essa é a parte mais difícil. O restante são apenas detalhes. (Mas, como sabemos, o diabo está nos detalhes, certo?)

O que falta fazer:

• Enviar uma mensagem de confirmação de volta ao Slack
• Analisar o pacote JSON para extrair os dados relevantes (por exemplo, quem postou a recomendação e o que ela era)

Envio de uma mensagem de retorno para o Slack

No momento, o script não envia uma resposta de volta ao Slack para confirmar o recebimento dos dados. O usuário recebe um monte de HTML de aparência feia com uma mensagem de erro. Obviamente, isso não é bom.

O senhor deseja enviar uma confirmação de volta ao Slack para evitar isso. O senhor também pode personalizar essa mensagem de retorno com algum texto útil.

Adicione esta linha ao código original:

function doPost(e) {
    if (typeof e !== 'undefined') {
        var ss = SpreadsheetApp.getActiveSpreadsheet();
        var sheet = ss.getSheetByName('Sheet1');
        sheet.getRange(1, 1).setValue(JSON.stringify(e));
    }
    return ContentService.createTextOutput(':books::nerd_face: Thank you for your book recommendation! :tada:');
}

Não se esqueça de criar um nova versão e atualizar seu aplicativo Web através do Publish > Deploy as a web app… menu.

O :books:, :nerd_face: e :tada: são convertidas em emojis no Slack, de modo que o usuário agora recebe uma mensagem de confirmação de recebimento:

Analisando os dados em sua planilha do Google

De volta à planilha do Google, se o senhor observar a longa sequência de dados na célula A1, poderá ver todos os campos necessários aninhados sob a chave de parâmetro.

Portanto, o senhor precisa se apossar disso:

var parameter = e.parameter;

Depois, é só procurar para obter o que o senhor precisa, por exemplo:

var bookName = parameter.text;

O código completo do seu aplicativo agora deve ser parecido com o seguinte:

function doPost(e) {
  if (typeof e !== 'undefined') { 
    var ss = SpreadsheetApp.getActiveSpreadsheet(); 
    var sheet = ss.getSheetByName('Sheet1');
    var lastRow = sheet.getLastRow();


    // extract the relevant data
    var parameter = e.parameter;
    var teamDomain = parameter.team_domain;
    var channelName = parameter.channel_name;
    var userName = parameter.user_name;
    var bookName = parameter.text;
    var date = new Date();
    var slackDetails = [date,teamDomain,channelName,userName,bookName];

    // paste the slack details to the sheet
    sheet.getRange(lastRow + 1,1,1,5).setValues([slackDetails]);
  }
  return ContentService.createTextOutput(':books::nerd_face: Thank you for your book recommendation! :tada:');
}

Novamente, o senhor precisará criar uma nova versão e atualizar o aplicativo Web.

Para publicar dados na Planilha do Google, o senhor precisa definir o intervalo e, em seguida definir os valores, usando uma notação de matriz dupla [ [ ] ]. Cada matriz interna é uma linha de dados.

Tente postar uma recomendação de livro novamente, e o resultado em sua Planilha do Google será parecido com este:

Muito melhor!

Esse é o aplicativo básico pronto. Mas ele ainda não é particularmente útil.

Para torná-lo mais útil, vamos criar o aplicativo:

• Chame a API do Google Books para obter detalhes adicionais (por exemplo, capa do livro, autor, número de páginas, link de visualização, etc.)
• Enviar uma mensagem de resposta abrangente para o Slack.

Obtendo dados de livros da API de livros do Google

A ideia aqui é enviar o título do livro para a API do Google Books para obter alguns dados adicionais, a fim de tornar o arquivo mais útil. Podemos conectar Google Sheets a APIs externas usando o Apps Script.

É claro que há muitas maneiras de estruturar seu código, mas eu separei a chamada para a API do Google Books em uma função separada e a chamei com o título do livro como argumento.

O coração dessa nova função é a chamada para a API do Google Books:

// function to get book details
function getBookDetails(bookName) {
  // empty array to hold book data
  var bookData = [];
  try {
    // call google books api
    var url="https://www.googleapis.com/books/v1/volumes?q=" + encodeURI(bookName) + '&country=US';
    var response = UrlFetchApp.fetch(url);
    var results = JSON.parse(response);

    // choose first book
    var book = results.items[0]; 

    // Get the book info
    var title = book.volumeInfo.title || 'No Data Found';
    var subtitle = book.volumeInfo.subtitle || 'No Data Found';
    var authors = book.volumeInfo.authors.join() || 'No Data Found'; // join to put multiple authors into string

    // add book data to array 
    bookData.push(title,subtitle,authors);
  }
  catch (e) {
    Logger.log("Hmm, something went wrong. Hint: " + e);
  }

 // return to main function
 return bookData;
}

Os dados retornados da API do Google Books são uma matriz de correspondências resultantes de uma pesquisa pelo nome do livro que o senhor forneceu.

O script seleciona o primeiro resultado de livro (ei, quando o senhor terminar este tutorial, por que não adicionar botões na mensagem de retorno para permitir que o usuário escolha qual livro?) e, em seguida, analisa os campos relevantes. Esses dados são enviados de volta à função principal para que possam ser adicionados ao seu Google Sheet.

Atualize a função principal para incluir uma chamada para a função getBookDetails e, em seguida, concatene os arrays de dados do Slack e do Book e atualize as referências de intervalo para colar os dados no Sheets (porque nossa linha agora tem mais campos).

// retrieve the book details
var bookData = getBookDetails(bookName);

// combine arrays
var fullData = slackDetails.concat(bookData);

// paste the slack details to the sheet
sheet.getRange(lastRow + 1,1,1,fullData.length).setValues([fullData]);

Quando o senhor atualiza e publica uma nova versão, é solicitado a autorizar o arquivo Apps Script a se conectar a um serviço externo (API do Google Books).

Agora tente publicar um novo título de livro por meio do Slack e o senhor obterá um resultado como este no Planilhas Google:

Uma nova linha de dados com informações adicionais sobre o livro!

O senhor pode aprimorar sua Planilha Google adicionando títulos e formatação.

Outro toque interessante é pegar o URL da miniatura do livro e exibi-lo na Planilha Google usando a função IMAGEM.

O código completo para esse exemplo, incluindo essas adições, é o seguinte disponível aqui no GitHub.

Envio de uma mensagem mais complexa de volta ao Slack

Em vez de apenas uma única linha de texto na resposta atual, o senhor pode enviar respostas muito mais ricas de volta ao Slack (e até mesmo adicionar interatividade, como botões etc.).

Nesse caso do Apps Script, o senhor pode criar um objeto JSON e enviá-lo de volta como uma string para o Slack.

O código para isso é:

var result = { 
  'text': ':books::nerd_face: Thank you for your book recommendation! :tada:', 
  'attachments': [
    {
      'title': bookData[0],
      'author_name': bookData[2],
      'image_url': bookData[3]
    }
  ]
}l

return ContentService.createTextOutput(JSON.stringify(result)).setMimeType(ContentService.MimeType.JSON);

Agora, seus usuários verão uma mensagem de resposta mais agradável na janela do Slack:

Mensagens de resposta atrasadas?

O Slack espera uma resposta a um comando Slash dentro de 3.000 milissegundos (3 segundos), caso contrário, o usuário verá uma mensagem de erro “O tempo limite foi atingido”.

Portanto, se o senhor receber dados do Slack e quiser fazer outras coisas com eles, há o risco de atingir esse limite de tempo limite.

Para lidar com isso, os Slack Slash Commands fornecem um URL de resposta atrasada no pacote de dados que o senhor recebe. A ideia é que seu aplicativo envie uma resposta imediata para dizer que recebeu os dados (“Ei, recebi a recomendação do livro!”) e, mais tarde, possa responder ao URL de resposta quando tiver concluído outras tarefas.

No entanto, o Google Apps Script é síncrono, portanto, infelizmente, não há uma maneira de usar esse padrão de resposta atrasada.

No entanto, neste exemplo, a chamada para a API do Google Books é extremamente rápida, pois os dados envolvidos são muito pequenos e, portanto, tudo acontece instantaneamente.

No entanto, vale a pena saber disso para outros aplicativos, onde isso pode ser necessário.

É isso que eu digo.

Hora de escolher um novo livro para ler…