Conecte e visualize todos os seus dados no Looker Studio

1. Introdução

Com o Looker Studio, você pode criar painéis interativos e dinâmicos com visualizações de dados incríveis sem custos financeiros. Extraia seus dados de várias fontes e crie relatórios ilimitados no Looker Studio, com recursos completos de edição e compartilhamento. A captura de tela a seguir é 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 com qualquer fonte de dados acessível pela Internet. Os Conectores da Comunidade são criados pela comunidade do Looker Studio. Isso significa que qualquer pessoa pode criar conectores da comunidade. Você também pode compartilhar Conectores da Comunidade com outras pessoas para que elas acessem os próprios dados no Looker Studio.

É possível usar os conectores da comunidade em diferentes casos de uso:

• Você está visualizando dados de uma plataforma comercial (por exemplo, redes sociais, marketing, análise etc.)
• Você está visualizando dados corporativos locais (por exemplo, dados de vendas de um banco de dados MySQL local).
• Você oferece uma maneira para que seus clientes visualizem os dados do seu serviço
• Você está criando uma plataforma de relatórios com um botão de envio
• Você está 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
• Familiaridade com JavaScript básico e APIs da Web

2. Pesquisa rápida

Por que você escolheu este codelab?

I am interested in data visualization in general. 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?

Apenas leitura dinâmica Ler e fazer os exercícios

Como você classificaria seu conhecimento do Looker Studio?

Nunca ouvi falar Sei o que é, mas não uso. Uso com frequência. Sou um usuário avançado.

Qual opção descreve melhor sua formação?

Desenvolvedor Analista de negócios / finanças / dados Cientista de dados / engenheiro de dados Especialista em marketing / redes sociais / análise digital Designer Outro

Você pode passar para a próxima página para enviar as informações da pesquisa.

3. Visão geral dos conectores da comunidade

Com os conectores da comunidade do Looker Studio, é possível criar conexões diretas do Looker Studio com qualquer fonte de dados acessível pela Internet. É possível se conectar a plataformas comerciais, conjuntos de dados públicos ou seus próprios dados particulares locais. Os Conectores da comunidade podem buscar dados usando APIs da Web, APIs JDBC, arquivos simples (CSV, JSON, XML) e serviços do Apps Script.

Considere um cenário em que você publicou um pacote no npm e quer acompanhar a contagem de downloads do pacote ao longo do tempo por dia. Neste codelab, você vai criar um conector da comunidade que busca dados usando a API de contagens de downloads de pacotes npm. O conector da comunidade pode ser usado no Looker Studio para criar um painel e visualizar as contagens de downloads.

4. Fluxo de trabalho do conector da comunidade

Em um conector da comunidade básico, você define 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 etapas subsequentes. O vídeo abaixo mostra uma visão geral de:

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

Você pode retomar o codelab depois de assistir o vídeo.

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

Na próxima etapa, você vai começar a criar seu conector no Google Apps Script. Você vai precisar alternar entre a interface do Apps Script e este codelab.

5. Configurar o projeto do Apps Script

Etapa 1:acesse o Google Apps Script.

Etapa 2:crie um projeto do Apps Script clicando em + Novo projeto na seção superior esquerda.

Você vai encontrar um projeto de 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. Insira 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 precisa retornar o método de autenticação exigido pelo conector para autorizar o serviço de terceiros.

Para o conector de download do npm que você está criando, não é necessário fazer a autenticação com nenhum serviço de terceiros, já que a API usada não exige autenticação. Copie o código a seguir e adicione ao arquivo Code.gs:

Code.gs

var cc = DataStudioApp.createCommunityConnector();

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

Aqui, você está indicando que seu conector não exige autenticação de terceiros (AuthTypes.NONE). Para conferir todos os métodos de autenticação compatíveis, consulte a referência AuthType().

7. Definir getConfig()

Os usuários do conector precisam configurá-lo antes de começar a usar. 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 receber 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 o comportamento de alguns deles.

Na tela de configuração, você pode fornecer informações ou receber 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 multilinha.
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 várias seleções.
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 dar 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 do formulário na chave configParams.

Como a API a que você está se conectando exige a data como parâmetro, defina dateRangeRequired como true na resposta getConfig(). Isso informa ao Looker Studio para fornecer períodos com todas as solicitações de dados. Se sua fonte de dados não exige data como parâmetro, você pode omiti-la.

Adicione o seguinte código getConfig() ao arquivo Code.gs, abaixo do código 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, uma tela de configuração como esta aparece. Mas vamos falar 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 ao usuário, listando todos os campos no conector.

Para qualquer configuração específica do 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 com base em várias configurações. O esquema pode conter campos buscados da sua fonte de API, campos calculados no Apps Script e campos calculados no Looker Studio usando uma fórmula de campo calculado. O conector 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 depois para saber mais.

Dependendo de como o conector 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 para a função getSchema().

Para este codelab, não é necessário acessar o argumento request. Você vai aprender mais sobre o argumento request ao escrever o código para a função getData() no próximo segmento.

Para seu conector, o esquema é fixo e contém os seguintes três campos:

packageName	Nome do pacote npm fornecido pelo usuário.
downloads	Contagem de downloads do pacote npm.
day	Data da contagem de downloads

Confira 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 seguinte código 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, você pode esperar ver os seguintes campos na tela de campos do Looker Studio ao usar o conector no Looker Studio. Mas 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 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 acessa o painel
• O usuário edita um filtro ou um controle de dados associado
• O Looker Studio precisa de uma amostra de dados

Não é necessário copiar nenhum código desta página, já que você vai copiar o

getData()

código em uma etapa posterior.

Como entender o objeto request

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

Estrutura do objeto 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 vai conter informações relevantes para a execução do conector. Não é necessário usar isso neste codelab.
• dateRange vai conter o período solicitado se ele for incluído na resposta getConfig().
• fields vai conter a lista de nomes dos 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 são solicitados, mesmo que o esquema do conector tenha outros campos. A próxima página vai conter o exemplo de resposta para essa chamada getData() e a estrutura geral de 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(), você precisa fornecer o esquema e os dados dos campos solicitados. Você vai dividir o código em três segmentos:

• Crie o esquema para os campos solicitados.
• Buscar e analisar dados da API.
• Transformar dados analisados e filtrar os campos solicitados.

Não é necessário copiar nenhum código desta página, já que você vai copiar o

getData()

código na próxima página.

Esta é a estrutura de 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 os 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 API npm estará neste formato:

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

Crie o URL da API usando 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: referência). 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 dados analisados e filtrar os campos solicitados

A resposta da API npm estará no 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 seguinte formato. Se esse formato não estiver claro, confira 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. Você vai retornar os dados usando 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 no exemplo anterior de request, esta é a aparência da resposta para getData():

{
  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 assim: Adicione o seguinte código 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 arquivo de manifesto "appsscript.json" 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 um teste.

13. Testar seu 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 Copiar para copiar o ID da implantação principal.

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

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

Autorizar o conector

Usuários iniciantes do Looker Studio:se você nunca usou o Looker Studio, será necessário autorizar o acesso e concordar com os termos e condições. Conclua o processo de autorização. Ao usar o Looker Studio pela primeira vez, talvez você veja uma caixa de diálogo para atualizar suas preferências de marketing. Inscreva-se em Comunicados de produtos se quiser receber por e-mail informações sobre os recursos, atualizações e avisos de produtos mais recentes.

Depois de carregado, você vai receber uma solicitação para autorizar o conector.

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

Importante: ao autorizar o conector, talvez você veja o seguinte aviso: "O Google não verificou este app". Como você é o autor do conector, é seguro continuar o fluxo de autorização clicando em Avançado -> Acessar <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

A tela "Campos" vai aparecer. Clique em Criar relatório no canto superior direito.

Crie seu painel

Você vai estar 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 nova configuração, uma fonte de dados é criada na conta do 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 vai retornar uma tabela de dados com um conjunto específico de campos. Os usuários podem criar várias fontes de dados com o mesmo conector. Uma fonte de dados pode ser usada em vários relatórios, e o mesmo relatório pode usar 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 na tela. Um gráfico de série temporal com a contagem de downloads do npm para o pacote selecionado vai aparecer. Adicione um controle de filtro de data e confira o painel, conforme mostrado abaixo.

Pronto! Você acabou de criar seu primeiro conector da comunidade. E, com isso, chegamos ao fim deste codelab. Agora, vamos ver quais são as próximas etapas.

14. Próximas etapas

Melhorar o conector criado

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

• No Looker Studio, se você não fornecer um nome de pacote na tela de configuração do conector, uma mensagem de erro vai aparecer ao criar o gráfico de série temporal. Tente adicionar validação de entrada ou uma opção padrão à configuração do conector.
• Tente adicionar suporte para consultar vários nomes de pacotes ao mesmo tempo na configuração do conector. Dica: a API de contagens de downloads de pacotes npm aceita a entrada de vários nomes de pacotes separados por vírgula.
• Você pode encontrar soluções para ambos no 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 um exemplo de código de conector no nosso repositório de código aberto para entender as práticas recomendadas.
• Conclua o codelab do clasp para desenvolver conectores da comunidade no seu 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 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 para desenvolvedores
Fazer perguntas	Fórum de usuários	Stack Overflow [looker-studio]
Vídeos	DataVis DevTalk
Exemplos	Galeria de relatórios Galeria de conectores	Repositório de código aberto