1. Introdução
Com o Google Data Studio, você cria painéis dinâmicos e interativos com visualizações de dados incríveis sem custos financeiros. As visualizações da comunidade são um recurso do Data Studio que permite criar visualizações personalizadas com JavaScript que se integram aos seus relatórios do Data Studio.
O que você vai aprender
Neste codelab, você vai aprender a:
- Como funciona uma visualização da comunidade do Google Data Studio
- Como criar uma visualização da comunidade com nossa ferramenta de modelo de linha de comando
- Como usar bibliotecas de visualização JavaScript para criar visualizações da comunidade
- Como integrar sua visualização da comunidade a um painel do Data Studio
O que é necessário
Para concluir este codelab, você vai precisar de:
- Acesso à Internet, um navegador da Web, um terminal e seu editor de texto favorito
- Uma Conta do Google
- Acesso a um bucket do Cloud Storage
- Familiaridade com JavaScript, Node.js e a linha de comando
Este codelab pressupõe que você:
- Você já criou uma visualização da comunidade (TODO link first codelab)
- Conhecer o Google Cloud Storage
Para começar, faça uma cópia deste relatório clicando em 
no canto superior direito. Mantenha-o aberto em outra guia enquanto faz o codelab.
2. Pesquisa rápida
Por que você escolheu este codelab?
Como você planeja usar este codelab/tutorial?
Como você classificaria sua experiência com o Data Studio?
Qual opção descreve melhor sua formação?
Acesse a próxima página para enviar as informações da pesquisa.
3. Desenvolvimento de visualizações da comunidade com dscc-gen
dscc-gen
O dscc-gen é uma ferramenta de linha de comando que oferece modelos e fluxos de trabalho opinativos para visualizações e conectores da comunidade. O modelo de visualização da comunidade oferece uma visualização funcional e um fluxo de trabalho que permite ver imediatamente as mudanças no código de visualização, além de scripts para validar, criar e implantar suas visualizações.
Configuração
O dscc-gen usa gsutil em scripts de implantação e npm e webpack para criar código JavaScript de visualização da comunidade.
- Instale o npm no computador local.
- Siga o guia de início rápido do gsutil e configure um bucket do Cloud Storage.
- Navegue até um diretório local onde você quer localizar o projeto.
4. Iniciar um novo projeto de visualização da comunidade dscc-gen
Abra um terminal e execute o comando:
npx @google/dscc-gen viz
O dscc-gen vai pedir um nome de projeto, um local de armazenamento do GCS "dev" e um local de armazenamento "prod". Insira o local como um URI com o protocolo gs, por exemplo, gs://my-gs-project/example-dev. Um "local" pode ser um bucket do Cloud Storage ou uma pasta dentro desse bucket. Os dois locais de armazenamento precisam ser diferentes. A ferramenta vai validar se você tem acesso aos valores inseridos. Se os locais não existirem, eles serão criados para você.
Depois que o dscc-gen cria uma visualização da comunidade, ele mostra instruções sobre como começar. O terminal vai ficar assim (sua entrada em itálico em negrito):
$ npx @google/dscc-gen viz
npx: installed 345 in 14.957s
? Project name barchart
? What is your GCS dev directory? gs://community-visualizations-codelab/barchart-dev
? What is your GCS prod directory? gs://community-visualizations-codelab/barchart-prod
Installing dependencies...
Created new community viz: barchart
cd barchart and npm run start to begin working on your viz!
Você vai editar os arquivos em src/, especificamente index.js, index.json e index.css, para escrever sua visualização.
Os arquivos em dist/ permitem que você pré-visualize sua visualização localmente em um navegador. webpack.config.js é usado para executar a visualização localmente. README.md oferece uma visão geral dos arquivos e comandos de modelo.
5. Visualizar a visualização localmente
Siga as instruções sugeridas e execute os seguintes comandos no terminal:
cd <folder name>
npm run start
Um navegador vai abrir uma página da Web parecida com esta:
Saiba mais na próxima etapa.
6. [Info] Como o fluxo de trabalho dscc-gen deve funcionar
O modelo de visualização dscc-gen vem com uma visualização funcional e instruções sobre como usar o modelo. Esta é a principal funcionalidade:
Atualize sua mensagem local:uma mensagem de exemplo está incluída no modelo, mas provavelmente não reflete o caso de uso que você quer oferecer suporte. Baixe dados de amostra que reflitam a visualização que você quer criar.
Fluxo de trabalho de desenvolvimento local: usando os dados de Atualizar seus dados locais, escreva e teste seu código localmente.
Crie e implante sua visualização:crie o código e faça upload dele para seus buckets do Google Cloud Storage.
Carregue a visualização no Data Studio:adicione a visualização ao seu relatório do Data Studio.
7. Definir uma configuração
O arquivo de configuração é o contrato entre você (o desenvolvedor de visualizações) e o editor de relatórios que usa a visualização. Ele define as opções disponíveis depois que a visualização é carregada no Data Studio.
Para essa visualização de gráfico de barras, a configuração terá uma dimensão e uma métrica, além de um elemento de estilo que permite ao editor de relatórios mudar o estilo do gráfico de barras.
Substitua o conteúdo de src/index.json pelo seguinte: Inclua todos os colchetes. Se você estiver digitando novamente, preste atenção à diferença entre colchetes e chaves e à estrutura de aninhamento.
index.json
{
"data": [
{
"id": "concepts",
"label": "Concepts",
"elements": [
{
"id": "dimension",
"label": "Dimensions",
"type": "DIMENSION",
"options": {
"min": 1,
"max": 1
}
},
{
"id": "metric",
"label": "Metric",
"type": "METRIC",
"options": {
"min": 1,
"max": 1
}
}
]
}
],
"style": [
{
"id": "barStyling",
"label": "Bar Styles",
"elements": [
{
"id": "barColor",
"label": "Bar Color",
"type": "FILL_COLOR",
"defaultValue": {
"color": "#1E555C"
}
}
]
}
]
}
8. Baixar mensagem atualizada
Para atualizar os dados armazenados localmente, execute:
npm run update_message
O terminal vai ficar assim:
barchart $ npm run update_message
> @ update message /Users/Code/barchart
> dscc-scripts viz update_message -f object
Copying file://build/index.js [Content-Type=application/javascript]...
Copying file://build/index.css [Content-Type=text/css]...
Copying file://build/manifest.json [Content-Type=application/json]...
Copying file://build/index.json [Content-Type=application/json]...
\ [4 files][ 48.5 KiB/ 48.5 KiB]
Operation completed over 4 objects/48.5 KiB.
Viz deployed to gs://community-visualizations-codelabs/barchart-dev
Esse comando implanta uma visualização no Data Studio que imprime os dados recebidos em uma visualização local. Os scripts imprimem o local de implantação da visualização (destacado acima). Você vai usar esse local para carregar sua visualização no Data Studio.
Para carregar a visualização, abra o relatório que você copiou antes.
- Acesse "Editar alerta".
- Clique em "Visualizações e componentes da comunidade" na barra de ferramentas.
- Clique em "Explorar mais".
- Clique em "Criar sua própria visualização"
- Insira o caminho do manifesto (o local
gs://...impresso no terminal) e clique em "Enviar".
- Clique no card renderizado para adicioná-lo ao relatório.
A visualização vai renderizar um JSON semelhante a este:
Copie toda a mensagem clicando com o botão direito do mouse e selecionando "Selecionar tudo". Depois, substitua o conteúdo de src/localMessage.js pelo que você acabou de copiar. Salve o arquivo.
A visualização em execução localmente no navegador não vai mais aparecer, e se você olhar no console, vai encontrar um erro.
9. Escrever JavaScript para um gráfico de barras
Primeiro, execute o comando a seguir para adicionar d3.js como uma dependência.
npm install d3
Em seguida, substitua src/index.js pelo código abaixo. As mudanças da última etapa estão em negrito.
src/index.js
const d3 = require('d3');
const dscc = require('@google/dscc');
const local = require('./localMessage.js');
// change this to 'true' for local development
// change this to 'false' before deploying
export const LOCAL = true;
const drawViz = (message) => {
const margin = { left: 20, right: 20, top: 20, bottom: 20 };
const height = dscc.getHeight() - 10;
const width = dscc.getWidth();
const chartHeight = height - margin.top - margin.bottom;
const chartWidth = width - margin.left - margin.right;
// remove existing svg
d3.select("body")
.selectAll("svg")
.remove();
// make a canvas
const svg = d3
.select("body")
.append("svg")
.attr("width", width)
.attr("height", height);
// make an svg for the bar chart
const chartSvg = svg
.append("svg")
.attr("x", margin.left)
.attr("y", margin.top)
.attr("width", chartWidth)
.attr("height", chartHeight);
// xScale to distribute bars
const xScale = d3
.scaleBand()
.domain(message.tables.DEFAULT.map(d => d.dimension[0]))
.range([0, chartWidth])
.paddingInner(0.3);
// yScale to size bars
const yScale = d3
.scaleLinear()
.domain([0, d3.max(message.tables.DEFAULT.map(d => d.metric[0]))])
.range([0, chartHeight]);
// add bars
const bars = chartSvg
.append("g")
.attr("class", "bars")
.selectAll("rect.bars")
.data(message.tables.DEFAULT)
.enter()
.append("rect")
.attr("x", d => xScale(d.dimension[0]))
.attr("y", d => chartHeight - yScale(d.metric[0]))
.attr("width", xScale.bandwidth())
.attr("height", d => yScale(d.metric[0]));
// add text
const text = svg
.append("g")
.selectAll("text")
.data(message.tables.DEFAULT)
.enter()
.append("text")
.attr(
"x",
d => xScale(d.dimension[0]) + xScale.bandwidth() / 2 + margin.left
)
.attr("y", height - margin.bottom / 4)
.attr("text-anchor", "middle")
.text(d => d.dimension[0]);
};
// renders locally
if (LOCAL) {
drawViz(local.message);
} else {
dscc.subscribeToData(drawViz, {transform: dscc.objectTransform});
}
Se o servidor local ainda estiver em execução, verifique o navegador. A página da Web de desenvolvimento local agora vai mostrar um gráfico de barras, como o abaixo.
10. Atualizar o manifesto (opcional)
O manifesto da visualização contém metadados sobre ela, além do local do JavaScript, da configuração e do CSS da visualização. Atualize os valores no manifesto. Eles serão usados para fornecer ao usuário final informações sobre a visualização.
Edite src/manifest.json para descrever sua visualização. Confira um exemplo de manifesto abaixo.
src/manifest.json
{
"name": "Bar Chart",
"organization": "[My name]",
"description": "Bar chart",
"logoUrl": "https://storage.googleapis.com/community-visualizations-codelabs/barchart/bar_chart.png",
"organizationUrl": "https://github.com/googledatastudio/",
"supportUrl": "http://github.com/googledatastudio/community-visualizations",
"privacyPolicyUrl": "http://github.com/googledatastudio/community-visualizations",
"termsOfServiceUrl": "http://github.com/googledatastudio/community-visualizations",
"packageUrl": "",
"devMode": "DEVMODE_BOOL",
"components": [
{
"id": "Bar chart",
"name": "Bar chart",
"description": "My first Community Visualization",
"iconUrl": "https://storage.googleapis.com/community-visualizations-codelabs/table/table_icon.png",
"resource": {
"js": "YOUR_GCS_BUCKET/index.js",
"config": "YOUR_GCS_BUCKET/index.json",
"css": "YOUR_GCS_BUCKET/index.css"
}
}
]
}
11. Implantar a visualização
Em src/index.js, mude a constante LOCAL para "false". A visualização no navegador vai parar de funcionar. A linha de código alterada está em negrito. Essa booleana configura se o código deve usar um arquivo de dados "local" ou os dados recebidos do Data Studio.
src/index.js (abridged)
const d3 = require('d3');
const dscc = require('@google/dscc');
const local = require('./localMessage.js');
// change this to 'true' for local development
// change this to 'false' before deployment
export const LOCAL = false;
const drawViz = (message) => {...}
Em seguida, no terminal, execute:
npm run build:dev
npm run push:dev
O comando build:dev agrupa suas dependências do JavaScript em uma saída não minimizada e substitui os valores no manifesto para desativar o armazenamento em cache e apontar para o bucket "dev" que você configurou anteriormente.
O comando push:dev faz upload dos recursos de visualização para o bucket "dev" que você configurou na etapa 1 e imprime o local do bucket no console.
Atualize o relatório do Data Studio. Um gráfico de barras vai aparecer. Tente mudar as opções de dados e estilo no painel de propriedades. Mudar os dados vai mudar as barras. No entanto, o seletor de estilo de cor da barra ainda não vai funcionar.
12. Usar as seleções de cores do Editor de relatórios no gráfico de barras
Para editar o código localmente, primeiro atualize a variável const LOCAL em src/index.js para true. Em seguida, adicione uma nova função chamada styleVal() e atualize o código em drawViz(). Seu src/index.js vai ficar assim:
src/index.js
const d3 = require('d3');
const dscc = require('@google/dscc');
const local = require('./localMessage.js');
// change this to 'true' for local development
// change this to 'false' before deploying
export const LOCAL = false;
// parse the style value
const styleVal = (message, styleId) => {
if (typeof message.style[styleId].defaultValue === "object") {
return message.style[styleId].value.color !== undefined
? message.style[styleId].value.color
: message.style[styleId].defaultValue.color;
}
return message.style[styleId].value !== undefined
? message.style[styleId].value
: message.style[styleId].defaultValue;
};
const drawViz = message => {
const margin = { left: 20, right: 20, top: 20, bottom: 20 };
const height = dscc.getHeight() - 10;
const width = dscc.getWidth();
const chartHeight = height - margin.top - margin.bottom;
const chartWidth = width - margin.left - margin.right;
// remove existing svg
d3.select("body")
.selectAll("svg")
.remove();
// make a canvas
const svg = d3
.select("body")
.append("svg")
.attr("width", width)
.attr("height", height);
// make an svg for the bar chart
const chartSvg = svg
.append("svg")
.attr("x", margin.left)
.attr("y", margin.top)
.attr("width", chartWidth)
.attr("height", chartHeight);
// xScale to distribute bars
const xScale = d3
.scaleBand()
.domain(message.tables.DEFAULT.map(d => d.dimension[0]))
.range([0, chartWidth])
.paddingInner(0.3);
// yScale to size bars
const yScale = d3
.scaleLinear()
.domain([0, d3.max(message.tables.DEFAULT.map(d => d.metric[0]))])
.range([0, chartHeight]);
// get the user-selected bar color
let barColor = styleVal(message, "barColor");
// add bars
const bars = chartSvg
.append("g")
.attr("class", "bars")
.selectAll("rect.bars")
.data(message.tables.DEFAULT)
.enter()
.append("rect")
.attr("x", d => xScale(d.dimension[0]))
.attr("y", d => chartHeight - yScale(d.metric[0]))
.attr("width", xScale.bandwidth())
.attr("height", d => yScale(d.metric[0]))
.attr("fill", barColor);
// add text
const text = svg
.append("g")
.selectAll("text")
.data(message.tables.DEFAULT)
.enter()
.append("text")
.attr(
"x",
d => xScale(d.dimension[0]) + xScale.bandwidth() / 2 + margin.left
)
.attr("y", height - margin.bottom / 4)
.attr("text-anchor", "middle")
.attr("fill", barColor)
.text(d => d.dimension[0]);
};
// renders locally
if (LOCAL) {
drawViz(local.message);
} else {
dscc.subscribeToData(drawViz, {transform: dscc.objectTransform});
}
Salve src/index.js e volte para a sessão do navegador local. Veja o app sendo executado localmente e, em seguida, mude a constante LOCAL para false.
Faça upload dos arquivos atualizados para o Google Cloud Storage executando:
npm run build:dev
npm run push:dev
Atualize o relatório do Data Studio. Agora você pode mudar a cor das barras.
13. Implantações de produção
Implantações de produção
Quando estiver satisfeito com a visualização, verifique se a constante LOCAL em src/index.js é "false" e execute.
npm run build:prod
npm run push:prod
Isso vai implantar seus arquivos no local do bucket do GCS "prod". Além disso, o armazenamento em cache será ativado, e o JavaScript agrupado será minimizado adequadamente.
Assim como antes, o local da implantação será impresso no console. Use esse "manifest path" para carregar sua visualização "prod" em um relatório do Data Studio.
Parabéns! Você acabou de criar sua primeira visualização da comunidade com a ferramenta dscc-gen.
14. Próximas etapas
Ampliar sua visualização
- Adicionar interações à visualização
- Saiba mais sobre os elementos de estilo disponíveis e adicione mais estilo à sua visualização.
Faça mais com as visualizações da comunidade
- Revise as referências da biblioteca auxiliar dscc, do manifesto e do arquivo de configuração.
- Envie sua visualização para a galeria de visualizações da comunidade.
- Crie um conector da comunidade para o Data Studio.
Outros recursos
Confira abaixo diversos 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 | ||
Notícias e atualizações | Inscreva-se no Data Studio > Configurações do usuário | |
Fazer perguntas | Stack Overflow [google-data-studio]Fórum de desenvolvedores do Data Studio | |
Vídeos | Em breve! | |
Exemplos |