Conecte e visualize todos os seus dados no Looker Studio

1. Introdução

O Looker Studio permite que você crie painéis interativos e em tempo real com visualizações de dados incríveis sem pagar nada. Busque dados de diversas fontes e crie relatórios ilimitados no Looker Studio, com recursos completos de edição e compartilhamento. A captura de tela abaixo é um exemplo de painel do Looker Studio:

( Clique aqui para ver este exemplo de relatório no Looker Studio)

Os conectores da comunidade são um recurso do Looker Studio que permite usar o Apps Script para criar conectores para qualquer fonte de dados acessível pela Internet. Os conectores da comunidade são criados pela própria comunidade do Looker Studio. Isso significa que qualquer pessoa pode criar conectores da comunidade. Também é possível compartilhar conectores da comunidade com outras pessoas para que elas possam acessar os próprios dados no Looker Studio.

Os conectores da comunidade podem ser usados em diferentes casos de uso:

• Você está visualizando dados de uma plataforma comercial (por exemplo, mídias sociais, marketing, análises etc.)
• Você está visualizando dados corporativos no local (por exemplo, dados de vendas de um banco de dados MySQL no local)
• Você está oferecendo aos clientes uma forma de visualizar os dados do seu serviço
• Você está criando uma plataforma de relatórios de botões de pressão
• Você estiver visualizando seus próprios dados de uma fonte da Web (por exemplo, criando seu painel do Google Fit)

O que você vai aprender

• Como funciona um conector da comunidade do Looker Studio
• Como usar o Google Apps Script para criar um conector da comunidade
• Como usar os conectores da comunidade no Looker Studio

O que é necessário

• Acesso à Internet e a um navegador da Web
• Uma Conta do Google
• Conhecer as APIs da Web e JavaScript básicas

2. Pesquisa rápida

Por que você escolheu este codelab?

Tenho interesse na visualização de dados em geral. Quero saber mais sobre o Looker Studio Quero criar meu próprio conector da comunidade. Estou tentando integrar o Looker Studio a outra plataforma. Tenho interesse nas soluções do Google Cloud.

Como você planeja usar este codelab/tutorial?

Somente deslizar Ler e fazer os exercícios

Qual é seu nível de familiaridade com o Looker Studio?

Nunca ouvi falar Sei o que é, mas não uso. Uso regularmente. Sou um usuário especialista.

Qual é a melhor descrição para sua experiência?

Desenvolvedor Analista de negócios / financeiro / de dados Cientista de dados / engenheiro de dados Especialista em marketing / mídias sociais / análise digital Designer Outro

Passe para a próxima página para enviar as informações da pesquisa.

3. Visão geral dos conectores da comunidade

Os conectores da comunidade do Looker Studio permitem conexões diretas do Looker Studio com qualquer fonte de dados acessível pela Internet. Você pode se conectar a plataformas comerciais, conjuntos de dados públicos ou seus próprios dados privados no local. Os conectores da comunidade podem buscar dados por meio de APIs Web, APIs JDBC, arquivos simples (CSV, JSON, XML) e serviços do Apps Script.

Considere um cenário em que você publicou um pacote em npm e quer acompanhar a contagem de downloads do pacote ao longo do dia. Neste codelab, você criará um conector da comunidade que busca dados usando a API NPM download count count. Depois, o conector da comunidade pode ser usado no Looker Studio para criar um painel que mostra as contagens de downloads.

4. Fluxo de trabalho dos conectores da comunidade

Em um conector da comunidade básico, você definirá quatro funções:

• getAuthType()
• getConfig()
• getSchema()
• getData()

Dependendo da etapa atual do fluxo de trabalho, o Looker Studio executa essas funções do conector e usa a resposta nas próximas etapas. O vídeo abaixo oferece uma visão geral de:

• Como funciona um conector da comunidade
• Etapas diferentes no fluxo de trabalho
• Quando funções diferentes são chamadas
• Quando o Looker Studio mostra interfaces do usuário diferentes
• Ações esperadas do usuário em diferentes etapas

É possível retomar o codelab após assistir ao vídeo.

Não é necessário memorizar este fluxo de trabalho. Basta dar uma olhada para ter uma ideia do que acontece em um conector. Você sempre pode voltar a este diagrama.

Na próxima etapa, você começará a criar seu conector no Google Apps Script. Será necessário alternar entre a interface do Apps Script e este codelab.

5. Configurar seu projeto do Apps Script

Etapa 1: acesse o Google Apps Script.

Etapa 2: crie um novo projeto do Apps Script clicando em + New project na seção do canto superior esquerdo.

Você verá um projeto shell com uma função myFunction em branco no arquivo Code.gs.

Etapa 3:exclua a função myFunction.

Etapa 4:dê um nome ao projeto:

1. Clique em Untitled project no canto superior esquerdo da página.
2. Digite um título para o projeto.

Comece a escrever o código do conector no arquivo Code.gs.

6. Definir getAuthType()

O Looker Studio vai chamar a função getAuthType() quando precisar saber o método de autenticação usado pelo conector. Essa função retornará o método de autenticação exigido pelo conector para autorizar o serviço de terceiros.

Para o conector de download de NPM que você está criando, não é necessário fazer a autenticação com nenhum serviço de terceiros, já que a API que você está usando não requer autenticação. Copie o seguinte código e adicione ao seu arquivo Code.gs:

Code.gs

var cc = DataStudioApp.createCommunityConnector();

function getAuthType() {
  var AuthTypes = cc.AuthType;
  return cc
    .newAuthTypeResponse()
    .setAuthType(AuthTypes.NONE)
    .build();
}

Você indica que seu conector não requer autenticação de terceiros (AuthTypes.NONE). Para acessar todos os métodos de autenticação compatíveis, consulte a referência AuthType().

7. Definir getConfig()

Os usuários do seu conector precisarão configurá-lo antes de começar a usá-lo. A resposta da função getConfig() define as opções de configuração que os usuários vão ver. O Looker Studio chama a função getConfig() para coletar os detalhes de configuração do conector. Com base na resposta fornecida por getConfig(), o Looker Studio vai renderizar a tela de configuração do conector e mudar determinados comportamentos.

Na tela de configuração, você pode fornecer informações ou obter entradas do usuário usando os seguintes elementos de formulário:

TEXTINPUT	Elemento de entrada	Uma caixa de texto de uma única linha.
TEXTAREA	Elemento de entrada	Uma caixa de área de texto com várias linhas.
SELECT_SINGLE	Elemento de entrada	Um menu suspenso para opções de seleção única.
SELECT_MULTIPLE	Elemento de entrada	Um menu suspenso para opções de seleção múltipla.
CHECKBOX	Elemento de entrada	Uma única caixa de seleção que pode ser usada para capturar valores booleanos.
INFO	Elemento de exibição	Uma caixa de texto simples estática que pode ser usada para fornecer instruções ou informações ao usuário.

Use o elemento INFO para fornecer instruções ao usuário e um elemento TEXTINPUT para receber o nome do pacote de entrada do usuário. Na resposta getConfig(), você vai agrupar esses elementos de formulário na chave configParams.

Como a API que você está usando para se conectar requer data como parâmetro, defina dateRangeRequired como true na resposta getConfig(). Isso informa ao Looker Studio para incluir períodos em todas as solicitações de dados. Se sua fonte de dados não exige data como parâmetro, ela pode ser omitida.

Adicione o seguinte código getConfig() ao arquivo Code.gs, abaixo do código já existente para getAuthType():

Code.gs

function getConfig(request) {
  var config = cc.getConfig();
  
  config.newInfo()
    .setId('instructions')
    .setText('Enter npm package names to fetch their download count.');
  
  config.newTextInput()
    .setId('package')
    .setName('Enter a single package name')
    .setHelpText('e.g. googleapis or lighthouse')
    .setPlaceholder('googleapis');
  
  config.setDateRangeRequired(true);
  
  return config.build();
}

Com base nesses configParams, quando você usa o conector no Looker Studio, é exibida uma tela de configuração como a seguinte. Falaremos mais sobre isso depois.

Vamos para a próxima função: getSchema().

8. Definir getSchema()

O Looker Studio chama a função getSchema() para receber o esquema associado à configuração selecionada pelo usuário para o conector. Com base na resposta fornecida por getSchema(), o Looker Studio vai mostrar a tela de campos para o usuário listando todos os campos do conector.

Para qualquer configuração específica do seu conector, o esquema é uma lista de todos os campos para os quais o conector pode fornecer dados. Um conector pode retornar um esquema diferente, com campos diferentes de acordo com várias configurações. O esquema pode conter campos que você busca na fonte da API, campos calculados no Apps Script e campos calculados no Looker Studio usando uma fórmula de campo calculado. Ele fornece os metadados sobre cada campo no esquema, incluindo:

• Nome do campo
• Tipo de dados do campo
• Informações semânticas

Consulte as referências getSchema() e Field posteriormente para saber mais.

Dependendo de como o conector faz a busca, o esquema pode ser fixo ou calculado dinamicamente quando getSchema() é chamado. Os parâmetros de configuração de getConfig() definidos pelo usuário serão fornecidos no argumento request da função () getSchema.

Neste codelab, você não precisa acessar o argumento request. Você vai saber mais sobre o argumento request ao escrever o código para a função getData() no próximo segmento.

No seu conector, o esquema é fixo e contém os três campos a seguir:

packageName	Nome do pacote npm que o usuário fornece
downloads	Contagem de downloads do pacote npm
day	Data da contagem de downloads

Veja abaixo o código getSchema() do seu conector. A função auxiliar getFields() abstrai a criação dos campos, já que essa funcionalidade é necessária para getSchema() e getData(). Adicione o código abaixo ao arquivo Code.gs:

Code.gs

function getFields(request) {
  var cc = DataStudioApp.createCommunityConnector();
  var fields = cc.getFields();
  var types = cc.FieldType;
  var aggregations = cc.AggregationType;
  
  fields.newDimension()
    .setId('packageName')
    .setType(types.TEXT);
  
  fields.newMetric()
    .setId('downloads')
    .setType(types.NUMBER)
    .setAggregation(aggregations.SUM);
  
  fields.newDimension()
    .setId('day')
    .setType(types.YEAR_MONTH_DAY);
  
  return fields;
}

function getSchema(request) {
  var fields = getFields(request).build();
  return { schema: fields };
}

Com base nesse esquema, os seguintes campos vão aparecer na tela de campos do Looker Studio quando você usar o conector nessa plataforma. Falaremos mais sobre isso depois, quando você testar o conector.

Vamos para nossa última função, getData().

9. Definir getData() : parte 1

O Looker Studio chama a função getData() sempre que ela precisa buscar dados. Com base na resposta fornecida por getData(), o Looker Studio vai renderizar e atualizar os gráficos no painel. getData() pode ser chamado durante estes eventos:

• O usuário adiciona um gráfico ao painel
• O usuário edita um gráfico
• O usuário visualiza o painel
• O usuário edita um filtro ou controle de dados associado
• O Looker Studio precisa de uma amostra de dados

Não é necessário copiar códigos desta página, porque você vai copiar o que estiver

getData()

em uma etapa posterior.

Noções básicas sobre o objeto request

O Looker Studio transmite o objeto request a cada chamada de getData(). Revise a estrutura do objeto request abaixo. Isso ajudará você a escrever o código da função getData().

Estrutura de objetos request

{
  configParams: object,
  scriptParams: object,
  dateRange: {
    startDate: string,
    endDate: string
  },
  fields: [
    {
      name: Field.name
    }
  ]
}

• O objeto configParams vai conter valores de configuração para os parâmetros definidos em getConfig() e configurados pelo usuário.
• O objeto scriptParams contém informações relevantes para a execução do conector. Você não precisa usá-lo para este codelab.
• dateRange contém o período solicitado, se solicitado na resposta getConfig().
• fields contém a lista de nomes de campos para os quais os dados são solicitados.

Para seu conector, um exemplo de request da função getData() pode ter esta aparência:

{
  configParams: {
    package: 'jquery'
  },
  dateRange: {
    startDate: '2017-07-16',
    endDate: '2017-07-18'
  },
  fields: [
    {
      name: 'day',
    },
    {
      name: 'downloads',
    }
  ]
}

Para a chamada getData() no request acima, apenas dois campos estão sendo solicitados, mesmo que o esquema do conector tenha campos adicionais. A próxima página contém o exemplo de resposta para esta chamada getData() e a estrutura geral da resposta getData().

Observação

Neste codelab, não estamos usando o parâmetro request para getSchema(). Para getSchema(), o parâmetro request vai conter apenas configParams e scriptParams.

10. Definir getData() : parte 2

Na resposta getData(), é necessário fornecer o esquema e os dados para os campos solicitados. Você vai dividir o código em três segmentos:

• Criar esquema para campos solicitados.
• Busque e analise dados da API.
• Transformar os dados analisados e filtrar os campos solicitados.

Não é necessário copiar códigos desta página, porque você vai copiar o que estiver

getData()

código na próxima página.

Esta é a estrutura do getData() para seu conector.

function getData(request) {

  // TODO: Create schema for requested fields.
  
  // TODO: Fetch and parse data from API.
  
  // TODO: Transform parsed data and filter for requested fields.

  return {
    schema: <filtered schema>,
    rows: <transformed and filtered data>
  };
}

Criar esquema para campos solicitados

// Create schema for requested fields
  var requestedFieldIds = request.fields.map(function(field) {
    return field.name;
  });
  var requestedFields = getFields().forIds(requestedFieldIds);

Buscar e analisar dados da API

O URL da npm API terá este formato:

https://api.npmjs.org/downloads/point/{start_date}:{end_date}/{package}

Crie o URL da API usando os request.dateRange.startDate, request.dateRange.endDate e request.configParams.package fornecidos pelo Looker Studio. Em seguida, busque os dados da API usando UrlFetchApp(Classe do Apps Script: reference). Em seguida, analise a resposta buscada.

  // Fetch and parse data from API
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ];
  var response = UrlFetchApp.fetch(url.join(''));
  var parsedResponse = JSON.parse(response).downloads;

Transformar os dados analisados e filtrar os campos solicitados

A resposta da API NPM terá o seguinte formato:

{
  downloads: [
    {
    day: '2014-02-27',
    downloads: 1904088
    },
    ..
    {
    day: '2014-03-04',
    downloads: 7904294
    }
  ],
  start: '2014-02-25',
  end: '2014-03-04',
  package: 'somepackage'
}

Transforme a resposta da API npm e forneça a resposta getData() no formato a seguir. Se esse formato não estiver claro, veja o exemplo de resposta no parágrafo a seguir.

{
  schema: [
    {
      object(Field)
    }
  ],
  rows: [
    {
      values: [string]
    }
  ]
}

Na resposta, retorne o esquema apenas para os campos solicitados usando a propriedade schema. Para retornar os dados, use a propriedade rows como uma lista de linhas. Para cada linha, a sequência de campos em values precisa corresponder à sequência de campos em schema. Com base em nosso exemplo anterior de request, a resposta para getData() ficará assim:

{
  schema: requestedFields.build(),
  rows: [
    {
      values: [ 38949, '20170716']
    },
    {
      values: [ 165314, '20170717']
    },
    {
      values: [ 180124, '20170718']
    },
  ]
}

Você já criou o subconjunto do esquema. Use a função a seguir para transformar os dados analisados e filtrar os campos solicitados.

function responseToRows(requestedFields, response, packageName) {
  // Transform parsed data and filter for requested fields
  return response.map(function(dailyDownload) {
    var row = [];
    requestedFields.asArray().forEach(function (field) {
      switch (field.getId()) {
        case 'day':
          return row.push(dailyDownload.day.replace(/-/g, ''));
        case 'downloads':
          return row.push(dailyDownload.downloads);
        case 'packageName':
          return row.push(packageName);
        default:
          return row.push('');
      }
    });
    return { values: row };
  });
}

11. Definir getData() : parte 3

O código getData() combinado vai ficar parecido com o exemplo abaixo. Adicione o código abaixo ao arquivo Code.gs:

Code.gs

function responseToRows(requestedFields, response, packageName) {
  // Transform parsed data and filter for requested fields
  return response.map(function(dailyDownload) {
    var row = [];
    requestedFields.asArray().forEach(function (field) {
      switch (field.getId()) {
        case 'day':
          return row.push(dailyDownload.day.replace(/-/g, ''));
        case 'downloads':
          return row.push(dailyDownload.downloads);
        case 'packageName':
          return row.push(packageName);
        default:
          return row.push('');
      }
    });
    return { values: row };
  });
}

function getData(request) {
  var requestedFieldIds = request.fields.map(function(field) {
    return field.name;
  });
  var requestedFields = getFields().forIds(requestedFieldIds);

  // Fetch and parse data from API
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ];
  var response = UrlFetchApp.fetch(url.join(''));
  var parsedResponse = JSON.parse(response).downloads;
  var rows = responseToRows(requestedFields, parsedResponse, request.configParams.package);

  return {
    schema: requestedFields.build(),
    rows: rows
  };
}

Você concluiu o arquivo Code.gs. Em seguida, atualize o manifesto.

12. Atualizar o manifesto

No editor do Apps Script, selecione Configurações do projeto > Mostrar "appsscript.json" arquivo de manifesto no editor.

Isso vai criar um novo arquivo de manifesto appsscript.json.

Substitua o arquivo appscript.json pelo seguinte:

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",

  "dataStudio": {
    "name": "npm Downloads - From Codelab",
    "logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20logo/npm-logo-red.png",
    "company": "Codelab user",
    "companyUrl": "https://developers.google.com/looker-studio/",
    "addonUrl": "https://github.com/googledatastudio/example-connectors/tree/master/npm-downloads",
    "supportUrl": "https://github.com/googledatastudio/community-connectors/issues",
    "description": "Get npm package download counts.",
    "sources": ["npm"]
  }
}

Salve o projeto do Apps Script.

Parabéns! Você criou seu primeiro conector da comunidade e ele está pronto para ser testado.

13. Testar o conector no Looker Studio

Usar a implantação

Etapa 1: no ambiente de desenvolvimento do Apps Script, clique em Implantar > Testar implantações para abrir a caixa de diálogo "Testar implantações".

A implantação padrão, Implantação principal, será listada.

Etapa 2:clique em Copy para copiar o Head Deployment ID.

Etapa 3:para carregar seu conector no Looker Studio, substitua <HEAD_DEPLOYMENT_ID> no link a seguir com o ID de implantação principal do seu conector e siga o link no navegador:

https://lookerstudio.google.com/datasources/create?connectorId=<HEAD_DEPLOYMENT_ID>

Autorizar o conector

Novos usuários do Looker Studio:se você nunca usou o Looker Studio, será necessário autorizar a ferramenta e concordar com os Termos e Condições. Conclua o processo de autorização. Ao usar o Looker Studio pela primeira vez, você também vai encontrar uma caixa de diálogo para atualizar suas preferências de marketing. Inscreva-se para receber avisos de produtos e ficar por dentro das novidades sobre recursos, atualizações e avisos de produtos por e-mail.

Depois do carregamento, você verá uma solicitação para autorizar o conector.

Clique em "Autorizar" e dê a autorização necessária ao conector.

Importante: talvez você veja o seguinte aviso ao autorizar o conector: "O Google não verificou este app". Como você é o autor do conector, é seguro continuar o fluxo de autorização clicando em Avançado -> Acesse <nome do projeto> (não seguro) na parte de baixo da caixa de diálogo.

Configurar o conector

Quando a autorização for concluída, a tela de configuração vai aparecer. Digite "Lighthouse" na área de entrada de texto e clique em Conectar no canto superior direito.

Confirmar o esquema

Você verá a tela de campos. Clique em Criar relatório no canto superior direito.

Crie seu painel

Você vai entrar no ambiente do painel do Looker Studio. Clique em Adicionar ao relatório.

No Looker Studio, sempre que um usuário acessa um conector e adiciona uma configuração, uma fonte de dados é criada na conta do Looker Studio desse usuário. Pense em uma fonte de dados como uma instanciação do conector com base em uma configuração específica. Com base no conector e na configuração selecionada pelo usuário, uma fonte de dados retorna uma tabela com um conjunto específico de campos. Os usuários podem criar várias fontes de dados no mesmo conector. Uma fonte de dados pode ser usada em vários relatórios, e o mesmo relatório pode utilizar várias fontes.

Agora, adicione um gráfico de série temporal. No menu, clique em Inserir > Série temporal. Em seguida, coloque a série temporal no canvas. Você verá um gráfico de série temporal da contagem de downloads de npm para o pacote selecionado. Adicione um controle de filtro de data e visualize o painel conforme mostrado abaixo.

Pronto! Você acabou de criar seu primeiro conector da comunidade! Chegamos ao final deste codelab. Agora, vamos conferir os próximos passos.

14. Próximas etapas

Aprimore o conector que você criou

Faça melhorias no conector que você acabou de criar:

• No Looker Studio, se você não informar um nome de pacote na tela de configuração do seu conector, uma mensagem de erro vai aparecer quando você desenhar o gráfico de série temporal. Tente adicionar uma validação de entrada ou uma opção padrão à configuração do seu conector.
• Tente adicionar suporte à consulta de vários nomes de pacotes ao mesmo tempo nas configurações do conector. Dica: a API npm download count é compatível com a entrada de vários nomes de pacotes separados por vírgula.
• Você encontra soluções para ambos no nosso código do conector npm.

Faça mais com os conectores da comunidade

• Consulte a referência da API do conector e do manifesto.
• Confira o exemplo de código do conector no nosso Repositório de código aberto para entender as práticas recomendadas.
• Conclua o Codelab da clasp para desenvolver conectores da comunidade no ambiente local.
• Depois de criar um conector da comunidade completo, considere as opções de publicação disponíveis.
• Crie uma visualização da comunidade para o Looker Studio.

Outros recursos

Confira abaixo vários recursos que podem ser acessados para ajudar você a se aprofundar no material abordado neste codelab.

Tipo de recurso	Recursos do usuário	Recursos para desenvolvedores
Documentação	Central de Ajuda	Documentação para desenvolvedores
Notícias e Atualizações	Inscreva-se no Looker Studio > Configurações do usuário	Lista de e-mails do desenvolvedor
Fazer perguntas	Fórum de usuários	Stack Overflow [looker-studio]
Vídeos	DataVis DevTalk (link em inglês)
Exemplos	Galeria de relatórios Galeria de conectores	Repositório de código aberto