Introdução
A API Linking oferece uma interface confiável para configurar e encaminhar usuários diretamente a um relatório do Looker Studio por um URL. Quando os usuários seguem um URL da API Linking, têm uma experiência simplificada para visualizar e interagir rapidamente com os próprios dados.
Neste documento, descrevemos o formato necessário dos URLs da API Linking e os parâmetros disponíveis.
Caso de uso e benefícios
A API Linking pode ser usada para fornecer relatórios pré-configurados para os clientes visualizarem e interagirem com os dados deles. Os principais benefícios da API Linking são:
- Uma experiência de criação de relatórios com um clique para seus clientes.
- A configuração dos dados é fornecida no URL para que os usuários não precisem configurar o relatório de dados.
- Os usuários podem salvar o relatório com um único clique e acessar novamente a qualquer momento.
- Criar relatórios em grande escala. A API Linking reduz o tempo necessário para fazer cópias ou criar novos relatórios.
- Possibilitar integrações de produtos. A interface estável permite que você integre o Looker Studio a um fluxo de trabalho do produto.
Como funciona
Confira a seguir como desenvolvedores e usuários interagem com a API Linking.
Vincular o fluxo de trabalho do desenvolvedor de API
O desenvolvedor prepara os modelos de relatórios, as fontes de dados e formata um URL da API Linking. O fluxo de trabalho típico para desenvolvedores é o seguinte:
- Decida se você quer usar um relatório em branco, o modelo de relatório padrão fornecido pelo Looker Studio ou criar um relatório do Looker Studio que vai servir como um modelo. Isso inclui a configuração das fontes de dados de modelo.
- Formate um URL da API Linking para seu caso de uso específico. Se aplicável, especifique o modelo de relatório e outros parâmetros, incluindo o nome do relatório, o nome da fonte de dados e as configurações dela.
- Use o URL da API Linking para direcionar os usuários ao relatório.
Experiência do usuário da API Linking
O usuário segue um URL da API Linking, que, se configurado corretamente pelo desenvolvedor, direciona para um relatório do Looker Studio que permite visualizar e interagir com os dados a que têm acesso. Uma experiência do usuário típica pode ser a seguinte:
- Em um navegador, o usuário visita um serviço integrado à API Linking.
- Uma call-to-action convida o usuário a clicar em um link para acessar os dados no Looker Studio.
- O usuário acessa o link e é direcionado a um relatório do Looker Studio. O relatório é carregado, e o usuário pode visualizar e interagir com os dados.
- O usuário clica em "Editar e compartilhar". O relatório é salvo na conta do Looker Studio dele.
- Agora o usuário tem acesso e controle total sobre a própria cópia do relatório. Ele pode ver, editar e compartilhar a qualquer momento.
Requisitos
Para garantir que o URL da API Linking funcione conforme o esperado, faça o seguinte:
- Um relatório para servir como modelo. Se não for fornecido, um relatório em branco ou um relatório padrão oferecido pelo Looker Studio poderá ser usado.
- Os usuários de um URL da API Linking precisam ter, no mínimo, acesso de leitura ao relatório do modelo. Dependendo do tipo de fontes de dados usadas no relatório e da configuração fornecida pela API Linking, os usuários também podem precisar de acesso para ver as fontes. Consulte os detalhes em Permissões de modelo.
- O tipo de conector de cada fonte de dados precisa oferecer suporte à configuração usando a API Linking. Consulte a Referência de conectores para ver uma lista de conectores compatíveis.
- Os usuários do URL da API Linking precisam ter acesso aos dados configurados nesse URL. Se o usuário não tiver acesso aos dados, todos os componentes dependentes do relatório mostrarão um erro.
Parâmetros de URL
O URL da API Linking precisa ter o seguinte formato:
https://lookerstudio.google.com/reporting/create?parameters
O URL deve ser usado no contexto de um navegador da Web, normalmente quando um usuário clica em um link ou é redirecionado ao URL. Ele também pode ser usado para Incorporar um relatório.
URL de exemplo
Confira a seguir um exemplo de URL da API Linking. O nome do relatório é definido, e uma única fonte de dados do BigQuery é configurada:
https://lookerstudio.google.com/reporting/create?
c.reportId=12345
&r.reportName=MyNewReport
&ds.ds0.connector=bigQuery
&ds.ds0.datasourceName=MyNewDataSource
&ds.ds0.projectId=project-1234
&ds.ds0.type=TABLE
&ds.ds0.datasetId=456
&ds.ds0.tableId=789
Alguns parâmetros de URL são obrigatórios, outros são opcionais. Confira a seguir uma lista de parâmetros usados para definir um URL da API Linking:
Parâmetros de controle
Os parâmetros de controle determinam o estado do relatório quando visualizado pelo URL da API Linking.
Nome do parâmetro | Descrição |
---|---|
Opcional. O ID do modelo do relatório. O Looker Studio vai abrir e configurar o relatório especificado. Saiba como encontrar o ID em ID do relatório. Se não for especificado, será usado um relatório em branco ou um modelo de relatório padrão. Consulte Usar um relatório em branco ou padrão para mais detalhes. | |
Opcional. O ID da página inicial a ser carregada no relatório. Se não for especificado, o padrão será a primeira página do relatório. | |
Opcional. O modo de relatório inicial. Uma destas:
view ou
edit . Se não for especificado, o padrão será view .
|
|
Opcional. Visibilidade da caixa de diálogo de informações/depuração. Defina como
true para mostrar o botão da caixa de diálogo. Se não for especificado, o padrão será false . Consulte
Como solucionar problemas de configuração para saber mais.
|
Exemplo
https://lookerstudio.google.com/reporting/create?
c.reportId=12345
&c.pageId=g7u8s9
&c.mode=edit
&r.reportName=MyNewReport
&ds.ds0.datasourceName=MyNewDataSource
&ds.ds0.connector=bigQuery
&ds.ds0.projectId=project-1234
&ds.ds0.type=TABLE
&ds.ds0.datasetId=456
&ds.ds0.tableId=789
Parâmetros do relatório
Os parâmetros substituem as propriedades do relatório.
Nome do parâmetro | Descrição |
---|---|
Opcional. Define o nome do relatório. Se não for especificado, o padrão será o nome do modelo de relatório. | |
Opcional. Define os IDs de métricas do Google Analytics para medir o uso do relatório. Use uma vírgula para separar vários códigos. Se |
|
Opcional. Defina como Se |
Exemplo
https://lookerstudio.google.com/reporting/create?
c.reportId=12345
&r.reportName=MyNewReport
&r.measurementId=G-XXXXXXXXXX
&ds.ds0.datasourceName=MyNewDataSource
&ds.ds0.connector=bigQuery
&ds.ds0.projectId=project-1234
&ds.ds0.type=TABLE
&ds.ds0.datasetId=456
&ds.ds0.tableId=789
Parâmetros da fonte de dados
Com os parâmetros da fonte de dados, você pode definir uma configuração de fonte de dados e os dados que serão acessados pelas fontes no modelo de relatório.
Um alias
é usado para fazer referência a uma fonte de dados em um relatório existente. Isso permite a compatibilidade com versões anteriores se uma fonte de dados for adicionada/removida do relatório de modelo.
Para saber detalhes sobre como encontrar um alias
de uma fonte de dados, consulte Alias de fonte de dados.
Parâmetros da fonte de dados
Os parâmetros a seguir são comuns em todos os tipos de conector:
Nome | Descrição |
---|---|
Opcional. Define o nome da fonte de dados. Se |
|
Opcional. Defina como Se |
|
Opcional.
O tipo de conector da fonte de dados. Para mais informações sobre os tipos de conectores compatíveis, consulte a Referência de conectores. Se definidos, todos os parâmetros de conector necessários para o tipo de conector vão precisar ser especificados no URL da API Linking, e a configuração da fonte de dados do modelo será totalmente substituída. Se não for especificado, zero ou mais parâmetros de conector para o tipo de conector poderão ser especificados no URL da API Linking. A configuração da fonte de dados do modelo será usada para especificar quaisquer parâmetros não fornecidos no URL da API Linking. Para mais detalhes sobre como identificar o tipo de conector da fonte de dados do modelo, consulte Tipo de conector. Para saber mais sobre como o parâmetro |
|
Opcional.
Defina como Defina como Se não forem especificados, os padrões variam de acordo com o tipo de conector. Consulte a referência do conector para ver os padrões específicos do conector, caso queira substituir o comportamento padrão. Considerações ao usar
refreshFields :
|
|
Obrigatório. A configuração da fonte de dados para o tipo de conector. Para mais detalhes sobre como identificar o conector usado para criar uma fonte de dados, consulte Tipo de conector. Para detalhes sobre os parâmetros da fonte de dados disponíveis para cada tipo de conector, consulte a Referência do conector. |
Substituição x atualização: configurações da fonte de dados
Ao definir parâmetros de fonte de dados, a presença ou omissão do parâmetro
ds.connector
no URL da API Linking indica a
intenção de substituir ou atualizar a configuração da fonte de dados do modelo,
respectivamente.
A tabela a seguir detalha como o parâmetro ds.connector
afeta se uma
configuração de fonte de dados de modelo é substituída completamente ou usada para atualizar
parâmetros não especificados:
O ds.connector está definido? |
Configuração e comportamento esperados | Uso típico |
---|---|---|
Sim |
Substituir. A configuração da fonte de dados do modelo é totalmente substituída usando os parâmetros de fonte de dados especificados no URL da API Linking. É preciso especificar todos os parâmetros necessários para o tipo de conector. Consulte Parâmetros obrigatórios quando ds.connector for definido.
|
|
Não | Atualizar. A configuração da fonte de dados do modelo será usada para especificar quaisquer parâmetros não fornecidos no URL da API Linking. Todos os parâmetros de conector do tipo de conector são opcionais, a menos que indicado de outra forma.
Isso simplifica o URL da API Linking e geralmente é recomendado quando você conhece a configuração da fonte de dados do modelo e quer substituir apenas um subconjunto de parâmetros. |
|
Parâmetros obrigatórios quando ds.connector
estiver definido
Se um parâmetro ds.connector
da fonte de dados for especificado, todos os parâmetros do conector designados como obrigatórios precisarão ser especificados para ela. Se o parâmetro ds.connector
da fonte de dados não for especificado, todos os parâmetros do conector, mesmo aqueles designados como obrigatórios, poderão ser tratados como opcionais, a menos que indicado de outra forma.
Exemplos
Configura um relatório com uma única fonte de dados do BigQuery (ds0
) e substitui completamente a configuração da fonte:
https://lookerstudio.google.com/reporting/create?
c.reportId=12345
&r.reportName=MyNewReport
&ds.ds0.datasourceName=MyNewDataSource
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=bigquery-public-data
&ds.ds0.datasetId=samples
&ds.ds0.tableId=shakespeare
O alias da fonte de dados pode ser omitido quando o relatório tem uma única fonte. O URL acima pode ser simplificado para o seguinte:
https://lookerstudio.google.com/reporting/create?
c.reportId=12345
&r.reportName=MyNewReport
&ds.datasourceName=MyNewDataSource
&ds.connector=bigQuery
&ds.type=TABLE
&ds.projectId=bigquery-public-data
&ds.datasetId=samples
&ds.tableId=shakespeare
Configura um relatório com uma única fonte de dados do BigQuery (ds0
) e atualiza somente o ID do projeto de faturamento da fonte de dados:
https://lookerstudio.google.com/reporting/create?
c.reportId=12345
&r.reportName=MyNewReport
&ds.ds0.billingProjectId=my-billing-project
Configura um relatório com duas fontes de dados, uma do BigQuery (ds0
) e uma do Google Analytics (ds1
). A configuração da fonte de dados do BigQuery é totalmente substituída, enquanto a configuração do Google Analytics atualiza um único parâmetro e depende da fonte de dados do modelo ds1
para todos os parâmetros do conector não especificados:
https://lookerstudio.google.com/reporting/create?
c.reportId=7890
&r.reportName=MyNewReportWithMultipleDataSources
&ds.ds0.datasourceName=MyNewDataSource
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=bigquery-public-data
&ds.ds0.datasetId=samples
&ds.ds0.tableId=shakespeare
&ds.ds1.viewId=92320289
Criar x adicionar
Às vezes, pode ser útil ter a mesma fonte de dados em vários relatórios. Assim, as atualizações na fonte afetam todos os relatórios juntos. Ao criar um relatório com a API Linking, é possível adicionar novamente uma fonte de dados do relatório do modelo, garantindo que todas as condições a seguir sejam atendidas:
- A fonte de dados é reutilizável. Consulte Fontes de dados incorporadas e reutilizáveis
- O URL não faz referência à fonte de dados pelo alias
- O URL não usa um alias curinga. Consulte Caractere curinga do alias da fonte de dados.
Quando uma nova fonte é criada com a API Linking, ela usa as credenciais do usuário que clicou no URL. Isso significa que o usuário precisa ter acesso aos dados subjacentes. Caso contrário, a conexão não funcionará. Ao adicionar novamente a fonte de dados ao novo relatório, você pode preservar as credenciais dela para que os usuários continuem acessando dados nos novos relatórios.
Caractere curinga do alias da fonte de dados
Para aplicar um parâmetro da API Linking a várias fontes de dados, é possível usar o alias curinga ds.*
no lugar do alias da fonte de dados.
Isso pode ser útil para remover parâmetros repetitivos do URL. Por exemplo, se você tiver um modelo com três fontes de dados do BigQuery anexadas e quiser substituir projectId
e datasetId
em cada uma, mas preservar o tableId
, poderá gravá-lo assim:
https://lookerstudio.google.com/reporting/create?
c.reportId=7890
&ds.ds1.projectId=client-project
&ds.ds1.datasetId=client-dataset
&ds.ds2.projectId=client-project
&ds.ds2.datasetId=client-dataset
&ds.ds3.projectId=client-project
&ds.ds3.datasetId=client-dataset
Com o caractere curinga ds.*
, também é possível usar este URL equivalente:
https://lookerstudio.google.com/reporting/create?
c.reportId=7890
&ds.*.projectId=client-project
&ds.*.datasetId=client-dataset
Os parâmetros fornecidos à API Linking que não usam o caractere curinga ds.*
têm
prioridade sobre aqueles que são. No exemplo acima, é possível adicionar um alias de fonte de dados específico para substituir o valor do caractere curinga.
https://lookerstudio.google.com/reporting/create?
c.reportId=7890
&ds.*.projectId=client-project
&ds.*.datasetId=client-dataset
&ds.ds1.datasetId=client-dataset
De modo mais geral, a ordem de precedência do parâmetro é a seguinte:
- Um parâmetro fornecido com um alias específico (
ds.ds1.datasetId
) - Um parâmetro fornecido com o caractere curinga (
ds.*.datasetId
) - Um valor derivado da fonte de dados do modelo, se o ds.connector não for fornecido (consulte Substituir x atualizar)
- O valor padrão do parâmetro, se for opcional.
Referência de conectores
A API Linking oferece suporte aos conectores e configurações a seguir. Para cada conector, é fornecida uma lista de parâmetros da fonte de dados disponíveis.
BigQuery
O conector do BigQuery aceita dois tipos de consulta: uma TABLE
, em que você fornece o ID da tabela a ser consultada, e uma CUSTOM_QUERY
, em que uma instrução SQL é fornecida para consultar uma tabela.
Consultas TABLE
Os parâmetros a seguir são aplicáveis quando type
está definido como TABLE
e você fornece o ID da tabela a ser consultada.
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como bigQuery para o conector do BigQuery.Se definido, substitui a fonte de dados pela configuração do BigQuery fornecida. Consulte Substituir x atualizar. |
|
Obrigatório** O tipo de consulta. Defina como
TABLE . |
|
Obrigatório** O ID do projeto da tabela a ser consultada. | |
Obrigatório** O ID do conjunto de dados da tabela a ser consultada. | |
Obrigatório** O ID da tabela a ser
consultada. Tabelas fragmentadas de data: O sufixo * (caractere curinga) ou YYYYMMDD é aceito
na consulta de tabelas fragmentadas por data.Se uma tabela for identificada como Google Analytics, Firebase Analytics ou Firebase Crashlytics, um modelo de campos padrão será selecionado, a menos que seja especificado. Consulte os parâmetros relacionados à tabela do modelo de campos. |
|
Opcional. O ID do projeto a ser usado para faturamento. Se não for definido,
projectId vai ser usado. |
|
Opcional. Defina como true se a tabela estiver particionada e você quiser usar a coluna de particionamento como uma dimensão de período. Isso se aplica apenas ao particionamento baseado em tempo (por exemplo, usando uma coluna de particionamento baseado em tempo ou a pseudocoluna _PARTITIONTIME ) e não funciona para tabelas particionadas por intervalo de números inteiros. Se não for especificado, o padrão será false . Para saber mais, consulte
Introdução às tabelas particionadas. |
|
Opcional. Quando não especificado, o padrão é true . Consulte refreshFields para mais detalhes. |
Modelo de campos para o Google Analytics, o Firebase Analytics e o Crashlytics
Para tabelas identificadas como do Google Analytics, Firebase Analytics ou Firebase Crashlytics, outros parâmetros estão disponíveis para definir o modelo de campos. Se não for especificado, um modelo padrão será selecionado.
Nome | Descrição |
---|---|
Opcional. O modelo de campos do Google Analytics a ser usado. Aplicável apenas quando uma exportação do BigQuery para a tabela do Google Analytics está sendo consultada. Uma destas: ALL , SESSION , HITS . Para tabelas do Google Analytics, o padrão será ALL se não for especificado. |
|
Opcional. O modelo de campos do Firebase Analytics a ser usado. Aplicável apenas quando uma tabela do BigQuery Export para o Firebase Analytics está sendo consultada.
Só pode ser definido como EVENTS . Para tabelas do Firebase Analytics, o padrão será EVENTS se não for especificado. |
|
O modelo de campos do Firebase Crashlytics a ser usado. Só pode ser definido como
DEFAULT . Aplicável apenas quando uma tabela do BigQuery Export para o Firebase Crashlytics está sendo consultada. Para tabelas do Firebase Crashlytics, o padrão será DEFAULT se não for especificado. |
Consultas PERSONALIZADAS
Os parâmetros a seguir são aplicáveis quando type
está definido como CUSTOM_QUERY
e
você fornece uma instrução SQL para consultar uma tabela.
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como bigQuery para o conector do BigQuery.Se definido, substitui a fonte de dados pela configuração do BigQuery fornecida. Consulte Substituir x atualizar. |
|
Obrigatório** O tipo de consulta. Defina como
CUSTOM_QUERY . |
|
Obrigatório** A consulta SQL a ser executada. | |
Opcional. O ID do projeto a ser usado para faturamento. Se não for definido,
projectId vai ser usado. Se projectId não estiver definido, o projeto da tabela consultada será usado. |
|
Opcional. Uma lista delimitada por vírgulas de strings de padrão e de substituição para aplicar à consulta SQL. A substituição de strings só será aplicada se houver uma
correspondência de padrão. Use uma vírgula para separar os pares de padrão e de string
de substituição. Por exemplo, |
|
Opcional. Quando não especificado, o padrão é true . Consulte refreshFields para mais detalhes. |
Exemplos
Uma configuração de tipo TABLE
em que a consulta é definida com um ID de tabela:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=bigquery-public-data
&ds.ds0.datasetId=samples
&ds.ds0.tableId=shakespeare
&ds.ds0.billingProjectId=myProject
Uma configuração do tipo TABLE
para consultar uma tabela fragmentada por data usando o sufixo de caractere curinga:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=price-data
&ds.ds0.datasetId=samples
&ds.ds0.tableId=stock_*
Uma configuração de tipo TABLE
para consultar uma tabela fragmentada por data usando o sufixo YYYYMMDD
:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=price-data
&ds.ds0.datasetId=samples
&ds.ds0.tableId=stock_YYYYMMDD
Uma configuração do tipo TABLE
para consultar uma tabela do BigQuery Export para o Google Analytics usando o modelo de campos SESSION
:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=my-gabq-project
&ds.ds0.datasetId=1234567
&ds.ds0.tableId=ga_sessions_YYYYMMDD
&ds.ds0.gaTemplateLevel=SESSION
Uma configuração do tipo TABLE
para consultar uma tabela particionada por tempo de ingestão e usar a coluna de particionamento como uma dimensão de período:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.connector=bigQuery
&ds.ds0.type=TABLE
&ds.ds0.projectId=acme-co-logs
&ds.ds0.datasetId=logs
&ds.ds0.tableId=logs_table
&ds.ds0.isPartitioned=true
Uma configuração de tipo CUSTOM_QUERY
em que a consulta é definida com uma instrução SQL:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.connector=bigQuery
&ds.ds0.type=CUSTOM_QUERY
&ds.ds0.projectId=bigquery-public-data
&ds.ds0.sql=SELECT%20word%2C%20word_count%20FROM%20%60bigquery-public-data.samples.shakespeare%60
&ds.ds0.billingProjectId=myProject
Uma configuração de tipo CUSTOM_QUERY
em que apenas a instrução SQL é atualizada e
a fonte de dados do modelo é usada no restante da configuração:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.sql=SELECT%20corpus%20FROM%20%60bigquery-public-data.samples.shakespeare%60
Uma configuração de tipo CUSTOM_QUERY
em que a instrução SQL da fonte de dados do modelo é atualizada usando sqlReplace
:
https://lookerstudio.google.com/reporting/create?
c.reportId=123abc
&ds.ds0.sqlReplace=bigquery-public-data,new-project,samples,new-dataset
# The following shows a template query before and after sqlReplace is applied.
#
# Template data source custom query:
# SELECT word, word_count FROM big-query-public-data.samples.shakespeare
# INNER JOIN
# SELECT word, word_count FROM big-query-public-data.samples.raleigh
#
# New data source custom query with sqlReplace applied:
# SELECT word, word_count FROM new-project.new-dataset.shakespeare
# INNER JOIN
# SELECT word, word_count FROM new-project.new-dataset.raleigh
Cloud Spanner
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como cloudSpanner para o conector do Cloud Spanner.Se definido, substitui a fonte de dados pela configuração do Cloud Spanner fornecida. Consulte Substituir x atualizar. |
|
Obrigatório** O ID do projeto. | |
Obrigatório** O ID da instância. | |
Obrigatório** O ID do banco de dados. | |
Obrigatório** A consulta SQL a ser executada. | |
Opcional. Quando não especificado, o padrão é true .
Consulte refreshFields para ver detalhes. |
Exemplo
Uma configuração do Cloud Spanner com uma instrução SQL:
https://lookerstudio.google.com/reporting/create?
c.reportId=456def
&ds.ds1.connector=cloudSpanner
&ds.ds1.projectId=myProject
&ds.ds1.instanceId=production
&ds.ds1.datasetId=transactions
&ds.ds1.sql=SELECT%20accountId%2C%20date%2C%20revenue%20FROM%20sales%3B
Conectores da comunidade
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como community para um conector da comunidade.Se definido, substitui a fonte de dados pela configuração do conector da comunidade fornecida. Consulte Substituir x atualizar. |
|
Obrigatório** O conector da comunidade connectorId (também conhecido como deploymentId ).
| |
Opcional. Outros parâmetros específicos do conector, conforme definido pela configuração do conector da comunidade. | |
Opcional. Quando não especificado, o padrão é true . Consulte refreshFields para mais detalhes. |
Exemplo
Conecte-se a um conector da comunidade com os parâmetros de configuração state
e city
:
https://lookerstudio.google.com/reporting/create?
c.reportId=161718pqr
&ds.ds5.connector=community
&ds.ds5.connectorId=AqwqXxQshl94nJa0E0-1MsZXQL0DfCsJIMWk7dnx
&ds.ds5.state=CA
&ds.ds5.city=Sacramento
Google Analytics
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como googleAnalytics para o conector do Google Analytics.Se definido, substitui a fonte de dados pela configuração do Google Analytics fornecida. Consulte Substituir x atualizar. |
|
Obrigatório** O ID da conta. | |
Obrigatório** O ID da propriedade. | |
O ID da vista. Obrigatório** para propriedades do Universal Analytics. Não defina para propriedades do Google Analytics 4. |
|
Opcional. Quando não especificado, o padrão é false . Consulte refreshFields para mais detalhes. |
Exemplos
Uma configuração do Google Analytics para uma propriedade do Universal Analytics:
https://lookerstudio.google.com/reporting/create?
c.reportId=789ghi
&ds.ds2.connector=googleAnalytics
&ds.ds2.accountId=54516992
&ds.ds2.propertyId=UA-54516992-1
&ds.ds2.viewId=92320289
Uma configuração do Google Analytics para uma propriedade do Google Analytics 4:
https://lookerstudio.google.com/reporting/create?
c.reportId=789ghi
&ds.ds2.connector=googleAnalytics
&ds.ds2.accountId=54516992
&ds.ds2.propertyId=213025502
Google Cloud Storage
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como googleCloudStorage
Conector do Google
Cloud Storage.Se definido, substitui a fonte de dados pela configuração fornecida do Google Cloud Storage. Consulte Substituir x atualizar. |
|
Obrigatório** O tipo de caminho. Use FILE para selecionar um único arquivo ou FOLDER para selecionar todos os arquivos do caminho especificado. |
|
Obrigatório** O caminho do arquivo (por exemplo, MyBucket/MyData/MyFile.csv) se pathType for FILE ou o caminho da pasta (por exemplo, *MyBucket/MyData) se pathType for FOLDER . |
|
Opcional. Quando não especificado, o padrão é true .
Consulte refreshFields para ver detalhes. |
Exemplo
Uma configuração do Google Cloud Storage para um único arquivo:
https://lookerstudio.google.com/reporting/create?
c.reportId=231908kpf
&ds.ds50.connector=googleCloudStorage
&ds.ds50.pathType=FILE
&ds.ds50.path=MyBucket%2FMyData%2FMyFile.csv
Uma configuração do Google Cloud Storage para todos os arquivos no caminho:
https://lookerstudio.google.com/reporting/create?
c.reportId=231908kpf
&ds.ds50.connector=googleCloudStorage
&ds.ds50.pathType=FOLDER
&ds.ds50.path=MyBucket%2FMyData
Planilhas Google
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como googleSheets para o conector das Planilhas Google.Se definido, substitui a fonte de dados pela configuração do Planilhas Google fornecida. Consulte Substituir x atualizar. |
|
Obrigatório** O ID da planilha. | |
Obrigatório** O ID da planilha. | |
Opcional. Defina como true para usar a primeira linha como cabeçalho.
Quando não especificado, o padrão é true . Os cabeçalhos das colunas precisam ser
exclusivos. Colunas sem cabeçalho não são adicionadas à fonte de dados.
|
|
Opcional. Defina como true para incluir células ocultas.
Quando não especificado, o padrão é true . |
|
Opcional. Defina como true para incluir células filtradas.
Quando não especificado, o padrão é true . |
|
Opcional. Intervalo, por exemplo: A1:B52. | |
Opcional. Quando não especificado, o padrão é true . Consulte refreshFields para mais detalhes. |
Exemplos
Uma configuração do Planilhas Google:
https://lookerstudio.google.com/reporting/create?
c.reportId=101112jkl
&ds.ds3.connector=googleSheets
&ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
&ds.ds3.worksheetId=903806437
Uma configuração do Planilhas Google com a primeira linha usada como cabeçalho e células ocultas e filtradas incluídas:
https://lookerstudio.google.com/reporting/create?
c.reportId=101112jkl
&ds.ds3.connector=googleSheets
&ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
&ds.ds3.worksheetId=903806437
&ds.ds3.hasHeader=true
&ds.ds3.includeHiddenCells=true
&ds.ds3.includeFilteredCells=true
Uma configuração do Planilhas Google com um intervalo (A1:D20):
https://lookerstudio.google.com/reporting/create?
c.reportId=101112jkl
&ds.ds3.connector=googleSheets
&ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
&ds.ds3.worksheetId=903806437
&ds.ds3.range=A1%3AD20
Looker
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como looker para o
conector do Looker.Se definido, substitui a fonte de dados pela configuração fornecida do Looker. Consulte Substituir x atualizar. |
|
Obrigatório** O URL da instância do Looker. | |
Obrigatório** O modelo do Looker. | |
Obrigatório** A Análise do Looker. | |
Opcional. Quando não especificado, o padrão é false . Consulte refreshFields para mais detalhes. |
Exemplo
Conecte-se a uma Análise do Looker:
https://lookerstudio.google.com/reporting/create?
c.reportId=161718pqr
&ds.ds5.connector=looker
&ds.ds5.instanceUrl=my.looker.com
&ds.ds5.model=thelook
&ds.ds5.explore=orders
Search Console
Nome do parâmetro | Descrição |
---|---|
Opcional. Defina como searchConsole para o conector do Search Console.Se definido, substitui a fonte de dados pela configuração fornecida do Search Console. Consulte Substituir x atualizar. |
|
Obrigatório** O URL do site. Para uma
propriedade do
domínio, use o prefixo sc-domain\: . |
|
Obrigatório** Define o tipo de tabela. Pode ser SITE_IMPRESSION ou URL_IMPRESSION . |
|
Obrigatório** Define o tipo de pesquisa. Pode ser WEB , IMAGE , VIDEO ou NEWS . |
|
Opcional. Quando não especificado, o padrão é false . Consulte refreshFields para mais detalhes. |
Exemplo
Uma configuração do Search Console para uma propriedade de prefixo de URL:
https://lookerstudio.google.com/reporting/create?
c.reportId=161718pqr
&ds.ds5.connector=searchConsole
&ds.ds5.siteUrl=https%3A%2F%2Fwww.example.com%2Fwelcome
&ds.ds5.tableType=SITE_IMPRESSION
&ds.ds5.searchType=WEB
Uma configuração do Search Console para uma propriedade do domínio:
https://lookerstudio.google.com/reporting/create?
c.reportId=161718pqr
ds.ds5.connector=searchConsole
&ds.ds5.siteUrl=sc-domain%3Aexample.com
&ds.ds5.tableType=SITE_IMPRESSION
&ds.ds5.searchType=WEB
Permissões de modelo
Para garantir a melhor experiência, é importante definir corretamente as permissões de acesso ao relatório do modelo e às fontes de dados associadas. As permissões necessárias dependem do modelo de relatório usar fontes de dados incorporadas e reutilizáveis e se a configuração da API Linking está definida para substituir ou atualizar uma configuração de fonte de dados.
A tabela a seguir fornece o acesso recomendado à fonte de dados para ter a melhor experiência do usuário com base nos modelos de fontes e na configuração da API Linking:
Tipo de origem de dados | Configuração da API Linking para a fonte de dados | Recomendação para permissões da fonte de dados | Observações |
---|---|---|---|
Incorporado | Substitua | N/A: o acesso de visualização será herdado do relatório. | Se o usuário tiver acesso de leitura ao relatório do modelo, ele automaticamente terá acesso de visualização a qualquer fonte de dados incorporada. |
Incorporado | Atualizar | N/A: o acesso de visualização será herdado do relatório. | Se o usuário tiver acesso de leitura ao relatório do modelo, ele automaticamente terá acesso de visualização a qualquer fonte de dados incorporada. |
Reutilizável | Substitua | Os usuários não precisam de acesso para visualizar. | Como a configuração da fonte de dados está sendo completamente substituída pela API Linking, o acesso de visualização não é necessário. |
Reutilizável | Atualizar | O usuário precisa de acesso para ver. | O acesso de leitura à fonte de dados é necessário para que a API Linking possa ler e usar a configuração da fonte de dados do modelo. Se os usuários não tiverem acesso para leitura, vão receber uma mensagem de erro ao carregar o relatório. |
Usar um relatório padrão ou em branco
Para usar um relatório em branco ou o relatório padrão, configure a API Linking da seguinte maneira:
Tipo de relatório | Defina o parâmetro de controle reportId . |
Defina os parâmetros da fonte de dados ( ). |
Observações |
---|---|---|---|
Relatório em branco | Não | Não | |
Relatório padrão | Não | Sim | O relatório padrão é fornecido pelo Looker Studio. Não é necessário usar um alias de fonte de dados ao especificar parâmetros de fonte de dados para o relatório padrão, já que ele tem uma única fonte incorporada. |
Os exemplos a seguir mostram vários URLs da API Linking que usam um relatório em branco ou padrão.
Inicie o fluxo de trabalho de criação de relatórios com um relatório em branco:
https://lookerstudio.google.com/reporting/create
Inicie o fluxo de trabalho de criação de relatórios com um relatório em branco e defina o nome dele:
https://lookerstudio.google.com/reporting/create?r.reportName=MyNewReport
Use o modelo de relatório padrão com uma configuração de conector do app Planilhas Google:
https://lookerstudio.google.com/reporting/create?
ds.connector=googleSheets
&ds.spreadsheetId=1Q-w7KeeJj1jk3wFcFm4NsPlppNscs0CtHf_EP9fsYOo
&ds.worksheetId=0
Incorporar um relatório
Para incorporar um relatório criado com a API Linking, defina os parâmetros de URL e inclua o caminho /embed/
. Um URL de incorporação da API Linking precisa ter o seguinte formato:
https://lookerstudio.google.com/embed/reporting/create?parameters
Encontrar IDs e aliases
ID do relatório
Para encontrar o ID do relatório:
- Abra o relatório que você quer usar como modelo. Confira o URL do relatório. A parte entre
reporting/
e/page
é o ID do relatório. Por exemplo, no URL a seguir,0B_U5RNpwhcE6SF85TENURnc4UjA
é o ID do relatório:
https://lookerstudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M
![Barra de endereço do navegador mostrando o URL de um relatório do Looker Studio.
O ID do relatório está destacado.](https://developers.google.cn/static/looker-studio/integrate/images/reportId-parameter.png?authuser=5&hl=pt)
Alias da fonte de dados
Um relatório pode ter várias fontes de dados, que precisam ser referenciadas pelo alias.
Para encontrar um alias de fonte de dados, faça o seguinte:
- Edite o relatório.
- Na barra de ferramentas, selecione Recurso > Gerenciar fontes de dados adicionadas.
- Confira a coluna Alias para encontrar informações de alias sobre cada fonte de dados.
É possível editar os nomes dos aliases para garantir a compatibilidade com versões anteriores quando uma fonte de dados for adicionada ou removida.
![Uma lista de fontes de dados na página de gerenciamento de recursos.
A coluna "Alias" está destacada.](https://developers.google.cn/static/looker-studio/integrate/images/data-source-alias.png?authuser=5&hl=pt)
Tipo de conector
Um relatório pode ter várias fontes de dados, cada uma criada com a configuração de um conector. Para encontrar o tipo de conector usado para criar uma fonte de dados, faça o seguinte:
- Edite o relatório.
- Na barra de ferramentas, selecione Recurso > Gerenciar fontes de dados adicionadas.
- Confira a coluna Tipo de conector para identificar o conector usado na criação de uma fonte de dados.
![Uma lista de fontes de dados na página de gerenciamento de recursos.
A coluna "Tipo de conector" está destacada.](https://developers.google.cn/static/looker-studio/integrate/images/data-source-connector.png?authuser=5&hl=pt)
Dicas e solução de problemas
Se você tiver dificuldades, confira os detalhes abaixo para identificar possíveis problemas e configurações incorretas comuns.
Caixa de diálogo de depuração
Use a caixa de diálogo de depuração para analisar a configuração da API Linking, conforme interpretada pelo Looker Studio. Ela pode ajudar a depurar problemas com a API.
- Quando um erro é encontrado durante a análise do URL da API Linking, uma caixa de diálogo é mostrada automaticamente com detalhes sobre o erro.
- Quando ocorre um erro e nenhuma caixa de diálogo é mostrada automaticamente, procure o botão de informações no canto superior direito do relatório. Clique para ver mais informações de depuração.
- Se nenhum botão de informações estiver disponível, ative o botão anexando o parâmetro
&c.explain=true
ao final de qualquer URL da API Linking.
Permissões
Verifique se você tem as permissões de modelo corretas definidas para os tipos de fonte de dados e a configuração da API Linking. Consulte os detalhes em Permissões de modelo.
Atualizar x substituir
Se você estiver atualizando uma configuração de fonte de dados com base em um modelo de fonte de dados, revise essas configurações e a da API Linking para garantir que elas sejam compatíveis. Confirme se os campos gerados com a nova configuração são compatíveis com os componentes e a configuração do relatório.
Ao realizar uma atualização ou substituição, é possível definir uma configuração inválida com comportamento indefinido. Consulte Substituir x atualizar para ver mais detalhes.
Atualizar campos
Se você configurou nomes de campos, tipos ou agregações para uma fonte de dados de modelo, essas alterações só serão transferidas para uma fonte configurada da API Linking se o parâmetro ds.refreshFields
estiver definido como false
.
Revise o parâmetro da fonte de dados ds.refreshFields
do URL da API Linking. Se omitido, confirme se o valor padrão do parâmetro para cada tipo de conector está correto para seu caso de uso.
Geralmente, se você configurou campos na fonte de dados de modelo e tem certeza de que as novas configurações da fonte de dados usando a API Linking sempre produzirão os mesmos campos, defina refreshFields
como false
.
Por exemplo, se durante a criação de um modelo de relatório, o Looker Studio identifica um campo de fonte de dados específico como o tipo Número e você o altera para o tipo Ano, essa mudança na configuração do campo passa a fazer parte da fonte de dados do modelo. Qualquer gráfico no modelo de relatório que usar o campo corrigido vai esperar um Ano. Se o gráfico for baseado em tempo, talvez ele não seja renderizado de outra forma. Se
a API Linking for usada para fornecer uma nova configuração de fonte de dados que gere
exatamente os mesmos campos, haverá dois resultados com base no valor do parâmetro
refreshFields
:
Se definido como
true
, a configuração de campo da fonte de dados do modelo não será transferida, e os gráficos talvez não sejam carregados se dependerem da mesma configuração de campo (ou seja, é esperado um campo do tipo Year).Se definida como
false
, a configuração de campo da fonte de dados do modelo será transferida para a nova fonte de dados, e os gráficos de relatórios receberão os mesmos campos com a mesma configuração e serão carregados com êxito.
Feedback e suporte
Use o Issue Tracker para informar problemas na API Linking ou enviar feedback. Consulte Suporte para ver recursos gerais sobre como receber ajuda e fazer perguntas.
Registro de alterações
2023-06-06
- Adicionamos os parâmetros de relatório
r.measurementId
er.keepMeasurementId
para definir a configuração do relatório de IDs de métricas do Google Analytics. ds.keepDatasourceName
foi adicionado para controlar a reutilização do nome da fonte de dados do modelo.- Adicionamos uma seção Incorporar relatório.
- Conector do BigQuery
sqlReplace
foi adicionado. Permite que você especifique strings de padrão e substituição para atualizar a consulta SQL da fonte de dados do modelo.
2023-05-22
- Adição de compatibilidade com o conector do Looker.
- Agora é possível usar conectores da comunidade.
2022-11-21
- Foi adicionado o recurso de usar um relatório em branco. Consulte Usar um relatório em branco ou padrão.
- Adicionamos uma seção
refreshFields
a Dicas e solução de problemas.
2022-11-14
- A referência do conector do Google Surveys foi removida devido à desativação do Google Surveys.
2022-06-15
- Fora da versão Beta
- A API Integration foi renomeada como API Linking.
- A API Linking não está mais na versão Beta.
- Adicionamos o parâmetro de controle
pageId
para permitir a vinculação a uma página específica do relatório. - Adicionamos o parâmetro de controle
mode
para definir o estado do relatório no modo Ver ou Editar no carregamento. - As configurações das fontes de dados agora podem ser totalmente ou parcialmente
atualizadas. Esse comportamento é determinado pela definição do parâmetro
ds.connector
. Consulte Substituir x atualizar para ver mais detalhes. - Um modelo padrão será usado se um modelo de relatório não for fornecido usando o parâmetro
c.reportId
. - Adicionamos o parâmetro de fonte de dados
ds.refreshFields
. Assim, você controla se os campos da fonte de dados são atualizados ao carregar uma configuração dela. - Conector do BigQuery
projectId
não é obrigatório quandotype
é definido comoCUSTOM_QUERY
.- Quando
billingProjectId
não estiver definido, o projeto de faturamento substituirá paraprojectId
ou o projeto da tabela consultada. - Inclusão de compatibilidade com tabelas particionadas por data. Defina o parâmetro
isPartitioned
comotrue
para usar o campo de partição como uma dimensão de período. - Inclusão de suporte para consultar tabelas particionadas por data usando o caractere curinga ou o sufixo de tabela
YYYYMMDD
. - Adicionado suporte à consulta de tabelas do Google Analytics, Firebase Analytics ou Crashlytics e à seleção de um modelo de campos.
- Planilhas Google
- O padrão de
hasHeader
étrue
, consistente com o padrão da IU da Web. includeHiddenAndFilteredCell
dividido emincludeHiddenCells
eincludeFilteredCells
. Agora, ambos usamtrue
como padrão, de acordo com o padrão da IU da Web.
- O padrão de
- Conector do Search Console
- O parâmetro
propertyType
foi renomeado comosearchType
.
- O parâmetro
- Conector do Surveys
surveyId
agora aceita um único ID de pesquisa ou uma lista separada por vírgulas de IDs de pesquisa.
16/12/2021
- Versão inicial da API Integration.
- É compatível com a vinculação a um relatório atual e a definição do nome do relatório.
- É possível configurar várias fontes de dados e definir o nome de cada uma.
- Suporte para os seguintes tipos de conector: BigQuery, Cloud Spanner, Google Analytics, Google Cloud Storage, Planilhas Google, Google Surveys e Search Console.