关联 API

简介

Links API 提供了一个可靠的接口,用于配置和转发用户 Looker Studio 报告。当用户使用关联 API 时 他们可以获得流畅的体验,以便快速查看和互动的网址 数据

本文档介绍了链接 API 网址的所需格式以及 可用的参数

使用情形和优势

Links API 可用于为客户提供预配置的报告 查看数据并与之互动链接 API 的主要优势包括 如下:

  • 为您的客户提供一键式报告创建体验
    • 数据配置在网址中提供,因此用户无需 为数据配置报告
    • 用户只需点击一下即可保存报告,然后即可通过以下网址再次访问此报告: 。
  • 大规模创建报告。Linking API 缩短了 您可以复制报表或创建新报表
  • 实现产品集成。借助稳定版接口,您可以 将 Looker Studio 集成到产品工作流程中。

工作原理

下文介绍了开发者和用户如何与关联 API 互动。

关联 API 开发者工作流程

开发者准备模板报告、数据源以及设置关联格式 API 网址。开发者的典型工作流程如下:

  1. 决定是否使用空白报告,即提供的默认报告模板 或创建 Looker Studio 报告, 模板。这包括配置模板数据源。
  2. 设置适用于您的具体用例的链接 API 网址的格式。如果适用,请指定 报告模板和其他参数,包括报告名称、数据 来源名称和数据源配置。
  3. 使用 Links API 网址将用户引导至报告。

关联 API 用户体验

用户会访问一个链接 API 网址,如果该网址由 将引导他们查看 Looker Studio 报告 以及与自己有权访问的数据互动一般的用户体验可能是 如下:

  1. 用户在浏览器中访问已与“关联”功能集成的服务 API。
  2. 号召性用语会邀请用户点击链接,以便在 Looker Studio。
  3. 用户点击该链接后,会被定向到 Looker Studio 报告。通过 报告加载后,用户就可以查看他们的数据并与之互动。
  4. 用户点击“修改并分享”。报告已保存到他们的 Looker Studio 。
  5. 用户现在对自己的报告副本拥有完全的访问和控制权限。他们可以随时查看、修改和分享该副本。

要求

为确保链接 API 网址按预期运行,必须具备以下条件:

  1. 报告,用作模板。如果未提供,则是空白报告; 可以使用 Looker Studio 提供的默认报告。
  2. 链接 API 网址的用户至少需要拥有 模板报告。取决于报告中所用数据源的类型 以及通过 Links API 提供的配置,用户可能还需要 对数据源的查看权限。请参阅模板权限: 。
  3. 每个数据源的连接器类型都必须支持通过 链接 API。如需查看受支持设备的列表,请参阅连接器参考信息 连接器。
  4. 链接 API 网址的用户必须有权访问在 链接 API 网址。如果用户无权访问底层数据 任何相关的报告组件都会显示错误。

网址参数

链接 API 网址必须采用以下格式:

https://lookerstudio.google.com/reporting/create?parameters

该网址预计将在网络浏览器环境中使用,通常由 用户点击链接或重定向到网址。它还可以用于 嵌入报告

示例网址

下面是一个链接 API 网址示例。系统会设置报告名称 BigQuery 数据源已配置:

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

有些网址参数是必需的,有些则是可选的。以下是 用于定义链接 API 网址的参数列表:

Control 参数

控制参数决定了通过“关联”查看报告时的状态 API 网址。

参数名称 说明
c.reportId
可选。模板报告 ID。Looker Studio 将打开并配置 。如需详细了解如何查找 ID,请参阅 举报 ID。如果未指定,则会显示空白报告或 使用的是默认报告模板,请参阅使用 空白报告或默认报告了解详情。
c.pageId
可选。要在报告中加载的初始页面的 ID。默认值为 报告的第一页(如果未指定)。
c.mode
可选。初始报告模式。以下之一: <ph type="x-smartling-placeholder"></ph> view edit。如果未指定,则默认为 view
c.explain
可选。信息/调试对话框的可见性。设置为 true,用于显示对话框按钮。默认值为 false(如果未指定)。请参阅 排查配置问题

示例

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

报告参数

报告参数会替换报告属性。

参数名称 说明
r.reportName
可选。设置报告名称。如果未指定,则默认为 模板报告名称。
r.measurementId

可选。将 Google Analytics 衡量 ID 设为 衡量 报告使用情况。使用英文逗号分隔多个 ID。

如果r.measurementIdr.keepMeasurementId 未指定时,Google Analytics 衡量 ID 报告 则默认为未设置如果 r.measurementId 且 已设置r.keepMeasurementIdr.keepMeasurementId 优先设置 ID。

r.keepMeasurementId

可选。设置为 true 可使用模板报告 Google Analytics 衡量 ID。默认值为 false

如果r.measurementIdr.keepMeasurementId 未指定时,Google Analytics 衡量 ID 报告 则默认为未设置如果 r.measurementId 且 已设置r.keepMeasurementIdr.keepMeasurementId 优先设置 ID。

示例

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

数据源参数

通过数据源参数,您可以定义数据源配置和 为模板报告中的数据源访问的数据。

alias 用于引用现有报告中的数据源。在模板报告中添加/移除数据源时,使用别名可实现向后兼容性。

如需详细了解如何查找数据源 alias,请参阅数据源别名

数据源参数

以下参数在所有连接器类型中都是通用的:

名称 说明
ds.alias.datasourceName

可选。设置数据源的名称。

如果 ds.datasourceName 且 未指定数据源名称 ds.keepDatasourceName 默认为命名惯例,其中包括连接器类型和 创建时间(例如 samples - 12/12/21, 10:53 PM)。如果 ds.datasourceNameds.keepDatasourceName 设置数据,ds.datasourceName 优先设置数据 来源名称。

ds.alias.keepDatasourceName

可选。设置为 true 可使用模板数据源 名称。如果未指定,则默认为 false

如果 ds.datasourceName 且 未指定数据源名称 ds.keepDatasourceName 默认为命名惯例,其中包括连接器类型和 创建时间(例如 samples - 12/12/21, 10:53 PM)。如果 ds.datasourceNameds.keepDatasourceName 设置数据,ds.datasourceName 优先设置数据 来源名称。

ds.alias.connector
可选。

数据源的连接器类型。如需详细了解 支持的连接器类型,请参阅连接器类型 参考

如果设置,则所有必需 必须在 关联 API 网址和模板数据源配置将 已被完全替换。

如果未指定,则零个或多个 可在以下位置指定连接器类型的连接器参数: 链接 API 网址。模板数据源配置将用于 指定链接 API 网址中未提供的所有参数。了解详情 有关如何识别模板数据源的连接器类型的信息,请参阅 连接器类型

详细了解 ds.connector 参数如何影响 是否完全替换模板数据源配置 或用于更新未指定的参数,请参阅 替换与更新

ds.alias.refreshFields
可选。

设置为 true 可使用数据源配置 (通过链接 API 指定的资源) 刷新 数据源字段,并使用新字段更新报告组成部分 选择。true通常为 在切换连接器类型时指定,或 适用于配置更改会产生不同字段的连接器类型 (例如,BigQuery 数据源的字段通常会随表的不同而变化 配置)。

设置为 false 以保留数据源字段 与模板报告相比没有任何变化。false通常为 当新数据配置生成完全相同的字段时指定 并且希望保留对 模板数据源。

如果未指定,默认值因连接器类型而异。查看 特定于连接器的连接器参考 默认值,如果您想要覆盖默认行为。

使用 refreshFields 时的注意事项:
  • 如果 refreshFields 设置为 false,并且 通过 Linking API 指定的数据源配置 与模板报告中使用的字段不同, 则受影响的组件可能会出现配置错误。
  • 对模板数据源中的字段(例如名称、类型、 汇总等数据)在以下情况下不会沿用到新数据源: refreshFields 设置为 true。设置 refreshFieldsfalse(用于维护字段) 配置数据来源。
  • <ph type="x-smartling-placeholder"></ph> 计算字段和 <ph type="x-smartling-placeholder"></ph> 模板数据源中定义的参数将始终复制 创建新的数据源,并且不受 refreshFields
ds.alias.connectorParameters
必需。此资源的数据源配置 连接器类型。如需详细了解如何识别 用于创建数据源的连接器,请参阅 连接器类型。如需详细了解 源参数的详情,请参阅 连接器参考

替换与更新 - 数据源配置

设置数据源参数时,是否存在 Links API 网址中的 ds.connector 参数表示 打算替换更新模板数据源配置, 。

下表详细说明了 ds.connector 参数如何影响 模板数据源配置被整体替换或用于更新 未指定参数:

是否已设置“ds.connector”? 预期的配置和行为 典型用途
替换。模板数据源配置会在 使用在“关联”部分中指定的数据源参数 API 网址。您必须为 连接器类型。请参阅 ds.connector 已设置
  • 更改数据源的连接器类型时。例如:如果您 在模板报告中配置了 BigQuery 数据源,但想要 通过关联 API 配置 Google 表格数据源。这将需要 新连接器配置进行完整定义。
  • 当您想要保证数据源的配置时。 替换配置可避免任何可能的未知值 来自模板数据源的数据
更新。模板数据源配置将用于 指定链接 API 网址中未提供的所有参数。所有连接器 除非另有说明,否则连接器类型的参数是可选的。

这简化了链接 API 网址,通常推荐在 熟悉模板数据源配置,只想 覆盖一部分参数。
  • 当您只想提供与 可以依赖于模板数据 来源。例如:仅更改 BigQuery 数据源配置的结算项目 ID,并使用 模板配置。

设置 ds.connector 时的必需参数

如果指定了数据源的 ds.connector 参数,则 必须为所有被指定为必需的连接器参数, 数据源。如果数据源的 ds.connector 参数为 所有连接器参数,即使是指定为必需参数, 均可视为可选项,除非另有说明。

示例

使用单个 BigQuery 数据源 (ds0) 配置报告,并替换 数据源配置:

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

如果报告只包含一个数据源,则可以省略数据源别名。上述网址可简化为以下内容:

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

配置具有单个 BigQuery 数据源 (ds0) 的报告,并且 更新对象的结算项目 ID 数据源:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.billingProjectId=my-billing-project

配置包含两个数据源的报告:一个 BigQuery 数据源 (ds0) 和一个 Google Analytics 数据源 (ds1)。BigQuery 数据源配置是 而 Google Analytics 配置会更新 单个参数,并依赖于 ds1 模板数据源来提供 未指定的连接器参数:

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

创建与添加

有时,在多个报告中使用相同的数据源会很有帮助, 对数据源进行的更新会同时影响所有报告 使用关联 API 创建报告时,您可以从下列位置重新添加数据源: 来生成模板报告:

  1. 数据源可重复使用(请参阅嵌入式数据源与可重复使用的数据源
  2. 该网址未按别名引用数据源
  3. 网址未使用通配符别名(请参阅数据源别名通配符

使用 Links API 创建新数据源时,它会使用相应凭据 用户点击了相应网址也就是说,用户必须有权访问 否则连接将不起作用。 通过将数据源重新添加到新生成的报告,您可以保留其 凭据,以便用户能够继续访问新报告中的数据。

数据源别名通配符

要将一个链接 API 参数应用到多个数据源,通配符别名 可以使用 ds.* 代替数据源别名。

这对于从网址中移除重复参数非常有用。对于 例如,假设您有一个附加了三个 BigQuery 数据源的模板,并且 您要替换 projectIddatasetId, 但保留 tableId,您可以将其编写为:

  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

或者,如果使用 ds.* 通配符,您可以使用下面的等效网址:

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset

向 Links API 提供的不使用 ds.* 通配符的参数为 优先级高于实际优先级在上面的示例中,您可以添加 特定数据源别名替换通配符中的值。

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset
  &ds.ds1.datasetId=client-dataset

更笼统地说,参数的优先顺序如下:

  1. 以特定别名 (ds.ds1.datasetId) 指定的参数
  2. 使用通配符 (ds.*.datasetId) 提供的参数
  3. 从模板数据源派生的值(如果未提供 ds.connector) (请参阅替换与更新
  4. 参数的默认值(如果可选)。

连接器参考信息

Links API 支持以下连接器和配置。对于每个 连接器,则会看到可用数据源参数的列表。

BigQuery

BigQuery 连接器支持两种类型的查询:TABLE 查询,其中 您需要提供要查询的表的表 ID 和 CUSTOM_QUERY,其中 您需要提供一条 SQL 语句来查询表。

TABLE 查询

type 设置为 TABLE 并且您 提供要查询的表的 ID。

参数名称 说明
ds.alias.connector
可选。设置为 bigQuery BigQuery 连接器

如果设置了此字段,则会将数据源替换为 提供的 BigQuery 配置请参阅 替换与更新
ds.alias.type
必填** 查询的类型。设置为 TABLE
ds.alias.projectId
必需** 表格的项目 ID 进行查询。
ds.alias.datasetId
必需**:要复制的表的数据集 ID 查询。
ds.alias.tableId
必需**:要复制的表格的表格 ID query.

日期分片表
支持 *(通配符)YYYYMMDD 后缀 。
如果某个表被标识为 Google 或 Firebase Crashlytics,默认字段 将默认选中该模板。请参阅 fields template 表相关参数。
ds.alias.billingProjectId
可选。用于结算的项目的 ID。如果未设置, 将使用 projectId
ds.alias.isPartitioned
可选。如果该表已进行分区,并且true 您希望将分区列用作日期范围维度。这是 仅适用于基于时间的分区(例如,使用 分区列或 _PARTITIONTIME 伪列)以及 不适用于整数范围分区表。默认值为 false(如果未指定)。如需了解详情,请参阅 <ph type="x-smartling-placeholder"></ph> 分区表简介
ds.alias.refreshFields
可选。如果未指定,则默认为 true。请参阅 refreshFields
Google Analytics、Firebase Analytics 和 Crashlytics 的字段模板

对于标识为 Google Analytics、Firebase Analytics 或 Firebase 的表 Crashlytics,则可以使用其他参数来设置字段模板。如果 未指定,则系统会选择默认模板。

名称 说明
ds.alias.gaTemplateLevel
可选。要使用的 Google Analytics 字段模板。仅适用于 当查询用于 Google Analytics 表的 BigQuery Export 时。一个 共 ALLSESSIONHITS。适用于 Google 分析表,如果未指定,则默认为 ALL
ds.alias.firebaseTemplateLevel
可选。要使用的 Firebase Analytics 字段模板。适用 仅在查询用于 Firebase Analytics 的 BigQuery Export 表时。 只能设置为 EVENTS。对于 Firebase Analytics 表 如果未指定,则默认为 EVENTS
ds.alias.crashlyticsTemplateLevel
要使用的 Firebase Crashlytics 字段模板。只能设置为 DEFAULT。仅适用于为 Firebase 导出 BigQuery 数据的情况 正在查询 Crashlytics 表。对于 Firebase Crashlytics 表: 如果未指定,则默认为 DEFAULT

CUSTOM 查询

type 设置为 CUSTOM_QUERY 且 您需要提供一条 SQL 语句来查询表。

参数名称 说明
ds.alias.connector
可选。设置为 bigQuery BigQuery 连接器

如果设置了此字段,则会将数据源替换为 提供的 BigQuery 配置请参阅 替换与更新
ds.alias.type
必填** 查询的类型。设置为 CUSTOM_QUERY
ds.alias.sql
必需**:要运行的 SQL 查询。
ds.alias.billingProjectId
可选。用于结算的项目的 ID。如果未设置, 将使用 projectId。如果未设置 projectId 则将使用所查询表的项目。
ds.alias.sqlReplace

可选。以英文逗号分隔的模式和替换字符串列表 适用于 SQL 查询。字符串替换仅在存在 模式匹配。使用英文逗号分隔模式和替换字符串 对。例如 stringPattern1,replacementString1, stringPattern2,replacementString2

ds.alias.refreshFields
可选。如果未指定,则默认为 true。请参阅 refreshFields

示例

用表 ID 定义查询的 TABLE 类型配置:

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

使用通配符查询日期分片表的 TABLE 类型配置 字符后缀:

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 查询日期分片表的 TABLE 类型配置 后缀:

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
  

用于查询适用于 Google Analytics 的 BigQuery Export 的 TABLE 类型配置 表,使用 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
  

用于查询提取时间分区表的 TABLE 类型配置 将分区列用作日期范围维度:

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

用 SQL 语句定义查询的 CUSTOM_QUERY 类型配置:

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

CUSTOM_QUERY 类型配置,其中仅更新 SQL 语句 模板数据源用于配置的其余部分:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sql=SELECT%20corpus%20FROM%20%60bigquery-public-data.samples.shakespeare%60

CUSTOM_QUERY 类型配置,其中模板数据的 SQL 语句 来源是使用 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

参数名称 说明
ds.alias.connector
可选。设置为cloudSpanner 云 Spanner 连接器

如果设置了此字段,则会将数据源替换为 提供的 Cloud Spanner 配置请参阅 替换与更新
ds.alias.projectId
必填**:项目 ID。
ds.alias.instanceId
必填** 实例 ID。
ds.alias.databaseId
必填** 数据库 ID。
ds.alias.sql
必需**:要运行的 SQL 查询。
ds.alias.refreshFields
可选。如果未指定,则默认为 true。 如需了解详情,请参阅 refreshFields

示例

使用 SQL 语句的 Cloud Spanner 配置:

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

社区连接器

参数名称 说明
ds.alias.connector
可选。设置为 community 社区连接器

如果设置,则会使用提供的社区连接器替换数据源 配置。请参阅 替换与更新
ds.alias.connectorId
必需** 社区连接器 connectorId(也称为 deploymentId)。
ds.alias.parameters
可选。其他特定于连接器的参数,由 社区连接器的 <ph type="x-smartling-placeholder"></ph> 连接器配置
ds.alias.refreshFields
可选。如果未指定,则默认为 true。请参阅 refreshFields

示例

通过“state”和“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

参数名称 说明
ds.alias.connector
可选。设置为 googleAnalytics Google Analytics 连接器

如果设置了此字段,则会将数据源替换为 所提供的 Google Analytics 配置。请参阅 替换与更新
ds.alias.accountId
必填** 账号 ID。
ds.alias.propertyId
必填** 媒体资源 ID。
ds.alias.viewId
数据视图 ID。
对于 Universal Analytics,则必需** Analytics 媒体资源。
请勿为 Google Analytics 4 媒体资源进行设置。
ds.alias.refreshFields
可选。如果未指定,则默认为 false。请参阅 refreshFields

示例

适用于 Universal Analytics 媒体资源的 Google 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

适用于 Google Analytics 4 媒体资源的 Google Analytics 配置:

https://lookerstudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=213025502

Google Cloud Storage

参数名称 说明
ds.alias.connector
可选。已设置为“googleCloudStorageGoogle Cloud Storage 连接器

如果设置此字段,则会替换数据源 与提供的 Google Cloud Storage 配置相关联。请参阅 替换与更新
ds.alias.pathType
必需**:路径类型。使用 按 FILE 键可选择单个文件,按 FOLDER 键可选择单个文件 指定路径的所有文件。
ds.alias.path
必需**:文件路径(例如 MyBucket/MyData/MyFile.csv)(如果 pathTypeFILE 或文件夹路径(例如 *MyBucket/MyDatapathTypeFOLDER
ds.alias.refreshFields
可选。如果未指定,则默认为 true。 如需了解详情,请参阅 refreshFields

示例

适用于单个文件的 Google Cloud Storage 配置:

https://lookerstudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FILE
  &ds.ds50.path=MyBucket%2FMyData%2FMyFile.csv

适用于路径中所有文件的 Google Cloud Storage 配置:

https://lookerstudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FOLDER
  &ds.ds50.path=MyBucket%2FMyData

Google 表格

参数名称 说明
ds.alias.connector
可选。设置为 googleSheets Google Google 表格连接器

如果设置了此字段,则会将数据源替换为 提供的 Google 表格配置。请参阅 替换与更新
ds.alias.spreadsheetId
必填** 电子表格 ID。
ds.alias.worksheetId
必需属性** 工作表 ID。
ds.alias.hasHeader
可选。设置为 true 可将第一行用作标题。 如果未指定,则默认为 true。列标题必须为 唯一。标题为空的列不会添加到数据源中。
ds.alias.includeHiddenCells
可选。设置为 true 可包含隐藏的单元格。 如果未指定,则默认为 true
ds.alias.includeFilteredCell
可选。设置为 true 可包含已过滤的单元格。 如果未指定,则默认为 true
ds.alias.range
可选。范围,例如 A1:B52。
ds.alias.refreshFields
可选。如果未指定,则默认为 true。请参阅 refreshFields

示例

Google 表格配置:

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437

将第一行用作标题且包含已隐藏和已过滤单元格的 Google 表格配置:

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

设置了范围 (A1:D20) 的 Google 表格配置:

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

参数名称 说明
ds.alias.connector
可选。设置为 looker <ph type="x-smartling-placeholder"></ph> Looker 连接器

如果设置了此字段,则会将数据源替换为 提供的 Looker 配置。请参阅 替换与更新
ds.alias.instanceUrl
必需** Looker 实例网址。
ds.alias.model
必需** Looker 模型。
ds.alias.explore
必需** Looker 探索。
ds.alias.refreshFields
可选。如果未指定,则默认为 false。请参阅 refreshFields

示例

关联到 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

参数名称 说明
ds.alias.connector
可选。设置为 searchConsole 搜索 控制台连接器

如果设置了此字段,则会将数据源替换为 提供的 Search Console 配置。请参阅 替换与更新
ds.alias.siteUrl
必需**:网站网址。对于 域 属性,前缀为 sc-domain\:
ds.alias.tableType
必需**:设置表类型。可以是 SITE_IMPRESSIONURL_IMPRESSION 之一。
ds.alias.searchType
必需**:设置搜索类型。可以是 WEBIMAGEVIDEONEWS
ds.alias.refreshFields
可选。如果未指定,则默认为 false。请参阅 refreshFields

示例

适用于网址前缀资源的 Search Console 配置:

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

适用于网域资源的 Search Console 配置:

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

模板权限

为确保为用户提供最佳用户体验,请务必正确设置 对模板报告和关联数据的报告访问权限 来源。所需权限取决于报表模板 使用嵌入式数据源与可重复使用的数据源,以及关联 API 是否 配置为替换或更新 数据源配置。

下表提供了建议的数据源访问权限,以实现最佳性能 基于模板数据源和关联 API 的用户体验 配置:

数据源类型 数据源的关联 API 配置 数据源权限建议 备注
嵌入式 替换 不适用 - 查看权限将从报告继承。 如果用户拥有对模板报告的查看权限,他们将会自动获得 对任何嵌入式数据源拥有查看权限。
嵌入式 更新 不适用 - 查看权限将从报告继承。 如果用户拥有对模板报告的查看权限,他们将会自动获得 对任何嵌入式数据源拥有查看权限。
可重复使用 替换 用户不需要查看权限。 由于数据源配置将被完全替换 则不需要查看权限。
可重复使用 更新 用户需要查看权限。 必须具备对数据源的查看权限,才能关联 API 能够读取和使用来自模板数据源的配置。如果 用户没有查看权限,如果他们没有查看权限, 。

使用空白报告或默认报告

要使用空白报告或默认报告,请将链接 API 配置为 如下:

报告类型 设置 reportId 控件参数 设置数据源 (ds) 参数。 备注
空白报告
默认报告

默认报告由 Looker Studio 提供。

指定 数据源参数,因为默认报告包含 单一嵌入式数据源。

以下示例显示了使用空白或默认值的各种链接 API 网址 报告。

使用空白报告启动报告创建工作流程:

https://lookerstudio.google.com/reporting/create

使用空白报告启动报告创建工作流程,并设置报告 名称:

https://lookerstudio.google.com/reporting/create?r.reportName=MyNewReport

使用默认报告模板和 Google 表格连接器配置:

https://lookerstudio.google.com/reporting/create?
  ds.connector=googleSheets
  &ds.spreadsheetId=1Q-w7KeeJj1jk3wFcFm4NsPlppNscs0CtHf_EP9fsYOo
  &ds.worksheetId=0

嵌入报告

要嵌入使用 links API 创建的报告,请将 网址参数并添加 /embed/ 路径。链接 API 嵌入网址必须采用以下格式:

https://lookerstudio.google.com/embed/reporting/create?parameters

查找 ID 和别名

报告 ID

要查找报告 ID,请执行以下操作:

  1. 打开要用作模板的报告。检查该报告的网址。reporting//page 之间的部分就是报告 ID。例如,在以下网址中,0B_U5RNpwhcE6SF85TENURnc4UjA 就是报告 ID:
https://lookerstudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M
显示 Looker Studio 报告网址的浏览器地址栏。
            报告 ID 处于突出显示状态。
在报告网址中查找报告 ID。

数据源别名

一个报告可以有多个数据源。数据源应通过别名进行引用。

要查找数据源别名,请执行以下操作:

  1. 修改报告。
  2. 在工具栏中,依次选择资源 > 管理添加的数据源
  3. 查看别名列,找到每个数据源的别名信息。

您可以修改别名,以确保添加或移除数据源时的向后兼容性。

数据源资源管理页面中的数据源列表。
            “别名”列处于突出显示状态。
在数据源管理页面中查找数据源别名。

连接器类型

一个报告可以有多个数据源,每个数据源都是通过配置连接器创建的。要查找用于创建数据源的连接器类型,请执行以下操作:

  1. 修改报告。
  2. 在工具栏中,依次选择资源 > 管理添加的数据源
  3. 查看连接器类型列,确定用于创建数据源的连接器。
数据源资源管理页面中的数据源列表。
            “连接器类型”列处于突出显示状态。
在数据源管理页面中查找数据源连接器类型。

提示和问题排查

如果您遇到问题,请查看以下详细信息以找出潜在问题 以及常见的错误配置

“Debug”对话框

使用调试对话框查看由 Looker Studio。它有助于调试 API 问题。

  • 在解析 Linking API 期间遇到错误时 网址,即会自动显示一个对话框,其中包含有关 错误。
  • 如果出现错误且没有自动显示对话框,请查看 找到报告右上角的信息按钮。点击 调试信息。
    用于了解报告创建方式的信息按钮。
  • 如果没有可用的信息按钮,您可以通过以下方式启用该按钮: 将 &c.explain=true 参数附加到 任何链接 API 网址。

权限

确保您已为数据源类型设置了正确的模板权限 以及关联 API 配置请参阅模板权限: 。

更新与替换

如果要通过数据源模板更新数据源配置,请查看 模板数据源配置和 Linking API 配置 它们是兼容的。确认新配置生成的字段 与报告组件和配置兼容。

在执行更新与替换时,可以设置一个无效的 具有未定义行为的配置。请参阅 如需了解详情,请参阅替换与更新

刷新字段

如果您为模板数据配置了字段名称、类型或汇总 来源,那么相应更改只会应用到已配置 Link API 中的数据 source(如果 ds.refreshFields 参数设置为) false

请查看您的 ds.refreshFields 数据源参数 链接 API 网址。如果省略,请确认 每种连接器类型都适合您的用例。

通常,如果您已在模板数据源中配置了字段,并且 确保通过 Links API 设置的新数据源配置始终是 会生成完全相同的字段,则将 refreshFields 设置为 false 即可 建议。

例如,如果在创建报告模板期间,Looker Studio 会 将特定数据源字段标识为 Number 类型,您将它更改为 类型 Year,此字段配置更改现已成为模板数据的一部分 来源。报告模板中使用更正后字段的所有图表都会 预计为 Year;如果图表是基于时间的,则可能不会显示。如果 链接 API 用于提供新的数据源配置, 完全相同的字段,则根据 refreshFields 参数:

  • 如果设置为 true,模板数据源中的字段配置将 不会沿用,并且如果图表无法沿用,可能会无法加载 相同的字段配置(即,应使用 Year 类型的字段)。

  • 如果设置为 false,则表示模板数据源中的字段配置 将转移到新的数据源,并且报告图表将收到 具有相同配置的相同字段,并成功加载。

反馈和支持

使用问题跟踪器报告 Link API 问题或提供反馈。请参阅 支持获取关于获取帮助和提问的一般资源。

更新日志

2023-06-06

  • 添加了 r.measurementId 和 要配置的 r.keepMeasurementId 报告参数 Google Analytics 衡量 ID 报告设置。
  • 添加了 ds.keepDatasourceName,以控制对 模板数据源名称。
  • 添加了嵌入报告部分。
  • BigQuery 连接器 <ph type="x-smartling-placeholder">
      </ph>
    • 添加了 sqlReplace。可让您指定 模式和替换字符串,用于更新模板的 SQL 查询 数据源。

2023-05-22

2022-11-21

2022-11-14

2022-06-15

  • 已结束 Beta 版测试 <ph type="x-smartling-placeholder">
      </ph>
    • Integration API 已重命名为 Linking API
    • Linking API 已结束 Beta 版测试。
  • 添加了 pageId 控制参数,以允许链接到特定报告 页面。
  • 添加了 mode 控件参数,以将报告状态设置为 View 或 加载时修改 Edit 模式。
  • 现在可以完全替换或部分替换数据源配置 已更新。此行为取决于 已设置 ds.connector 参数。请参阅替换与更新 了解详情。
  • 现在,如果未使用 c.reportId 参数。
  • 添加了 ds.refreshFields 数据源参数。这样,您就可以 控制在加载数据源时是否刷新数据源字段 配置。
  • BigQuery 连接器 <ph type="x-smartling-placeholder">
      </ph>
    • type 设置为 CUSTOM_QUERY 时,projectId 不是必需的。
    • 如果未设置 billingProjectId,则结算项目将 回退到 projectId 或所查询表的项目。
    • 添加了对日期分区表的支持。设置 isPartitioned true 的参数,以将分区字段用作日期范围 维度。
    • 新增了对使用通配符查询日期分区表的支持 字符或 YYYYMMDD 表后缀。
    • 现已支持查询 Google Analytics、Firebase Analytics 或 Crashlytics 表,并选择一个字段模板。
  • Google 表格 <ph type="x-smartling-placeholder">
      </ph>
    • hasHeader 默认为 true,与网页界面的默认设置一致。
    • includeHiddenAndFilteredCell 分为 includeHiddenCells
    • includeFilteredCells。现在两者都默认为 true,与 网页界面默认值。
  • Search Console 连接器 <ph type="x-smartling-placeholder">
      </ph>
    • propertyType 参数重命名为了 searchType
  • 问卷调查连接器 <ph type="x-smartling-placeholder">
      </ph>
    • surveyId 现在接受单个调查问卷 ID 或以英文逗号分隔的 问卷调查 ID。

2021 年 12 月 16 日

  • Integration API 的初始版本。
    • 支持链接到现有报告和设置报告名称。
    • 可以配置多个数据源,并且可以为每个数据源设置名称。
    • 支持以下连接器类型:BigQuery、Cloud Spanner、Google Analytics、Google Cloud Storage、Google 表格、Google 问卷调查、Search Console。