简介
Links API 提供了一个可靠的界面，可用于配置通过网址将用户直接转到 Looker Studio 报告。当用户访问 Links API 网址时，可以获享流畅的体验，从而快速查看自己的数据并与之互动。
本文档介绍了 Linking API 网址的必需格式和可用参数。
使用情形和优势
Links API 可用于提供预配置的报告，供客户查看和与其数据互动。Links API 的主要优势如下：
- 为您的客户提供一键式报告创建体验。
- 数据配置在网址中提供，因此用户无需为其数据配置报告。
- 用户只需点击一下即可保存报告，并且可以随时重新访问报告。
- 大规模创建报告。Links API 可减少复制报告或创建新报告所需的时间。
- 实现产品集成。通过稳定的界面，您可以将 Looker Studio 集成到产品工作流中。
运作方式
下文介绍了开发者和用户如何与 Links API 互动。
关联 API 开发者工作流程
开发者准备模板报告、数据源，并设置 Links API 网址的格式。开发者的典型工作流程如下：
- 决定是使用空白报告（Looker Studio 提供的默认报告模板），还是创建将用作模板的 Looker Studio 报告。其中包括配置模板数据源。
- 根据您的具体使用情形设置 Linking API 网址的格式。如果适用，请指定报告模板和其他参数，包括报告名称、数据源名称和数据源配置。
- 使用 Linking API 网址将用户引导至该报告。
关联 API 用户体验
用户需要访问 Links API 网址，如果开发者正确配置该网址，用户就可以访问 Looker 数据洞察报告，查看自己有权访问的数据并与之互动。典型的用户体验如下：
- 在浏览器中，用户访问集成了 Linking API 的服务。
- 号召性用语邀请用户点击链接，以在 Looker 数据洞察中查看他们的数据。
- 用户点击该链接并转到 Looker 数据洞察报告。系统会加载该报告，并且用户可以查看数据并与之互动。
- 用户点击“修改和分享”。报告会保存到其 Looker Studio 帐号中。
- 用户现在对自己的报告副本拥有完全的访问和控制权限。他们可以随时查看、修改和分享该副本。
要求
若要确保 Links API 网址按预期运行，必须满足以下条件：
- 一个报告，可作为模板。如果未提供，则可以使用空白报告或 Looker Studio 提供的默认报告。
- Links API 网址的用户必须至少拥有模板报告查看权限。根据报告中使用的数据源类型以及通过 Linking API 提供的配置，用户还可能需要获得对数据源的查看权限。如需了解详情，请参阅模板权限。
- 每个数据源的连接器类型都必须支持通过 Linking API 进行配置。如需查看受支持的连接器列表，请参阅连接器参考。
- Links API 网址的用户必须有权访问 Linking API 网址中配置的数据。如果用户无权访问基础数据，则所有相关的报告组件都会显示错误。
网址参数
Links 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
有些网址参数为必填，有些则是可选的。下面列出了用于定义 Links API 网址的参数：
控制参数
控制参数决定了通过 Linking API 网址查看报告时的状态。
| 参数名称 | 说明 |
|---|---|
| 可选。模板报告 ID。Looker Studio 将打开并配置指定的报告。如需详细了解如何查找此 ID，请参阅举报 ID。如果未指定，则使用空白报告或默认报告模板；如需了解详情，请参阅使用空白或默认报告。 | |
| 可选。要在报告中加载的初始网页的 ID。如果未指定，则默认为报告的第一页。 | |
可选。初始报告模式。
view 或
edit 中的一个。如果未指定，则默认为 view。
|
|
可选。信息/调试对话框的可见性。设置为 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
报告参数
报告参数会替换报告属性。
| 参数名称 | 说明 |
|---|---|
| 可选。设置报告名称。如果未指定，则默认为模板报告名称。 | |
|
可选。将 Google Analytics（分析）衡量 ID 设置为衡量报告使用情况。使用英文逗号分隔多个 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，请参阅数据源别名。
数据源参数
以下参数在所有连接器类型中通用：
| 名称 | 说明 |
|---|---|
|
可选。设置数据源的名称。 如果未指定 |
|
|
可选。设置为 如果未指定 |
|
|
可选。
数据源的连接器类型。如需详细了解支持的连接器类型，请参阅连接器参考。 如果设置了此参数，则必须在“关联 API 网址”中指定相应连接器类型的所有必需的 连接器参数，并完全替换模板数据源配置。 如果未指定连接器类型，则可以在链接 API 网址中指定零个或多个连接器类型的 连接器参数。模板数据源配置将用于指定未在 Links API 网址中提供的任何参数。如需详细了解如何识别模板数据源的连接器类型，请参阅连接器类型。 如需详细了解 |
|
|
可选。
设置为 设置为 如果未指定，默认值因连接器类型而异。如果您想要替换默认行为，请查看连接器参考信息，了解连接器特有的默认值。 使用
refreshFields 时的注意事项： |
|
| 强制要求。连接器类型的数据源配置。如需详细了解如何识别用于创建数据源的连接器，请参阅连接器类型。如需详细了解适用于各种连接器类型的数据源参数，请参阅连接器参考。 |
替换与更新 - 数据源配置
设置数据源参数时，如果关联 API 网址中存在或省略 ds.connector 参数，则表示的意图是分别替换或更新模板数据源配置。
下表详细说明了 ds.connector 参数如何影响是完全替换模板数据源配置，还是用于更新未指定的参数：
是否已设置 ds.connector？ |
预期的配置和行为 | 典型用途 |
|---|---|---|
| 是 |
替换。系统将使用 Linking API 网址中指定的数据源参数来完全替换模板数据源配置。您必须为连接器类型指定所有必需的参数。请参阅设置 ds.connector 时的必需参数。
|
|
| 否 | 更新。模板数据源配置将用于指定未在 Links API 网址中提供的任何参数。除非另有说明，否则连接器类型的所有连接器参数都是可选的。 这样可以简化 Linking API 网址。如果您熟悉模板数据源配置，并且只想替换一部分参数，我们通常建议您这样做。 |
|
已设置 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
创建与添加
有时，在多个报告中使用同一个数据源会很有用，因为对数据源的更新会同时影响所有报告。使用 Linking API 创建报告时，您可以从模板报告重新添加数据源，方法是确保满足以下所有条件：
- 数据源可重复使用（请参阅嵌入式数据源和可重复使用的数据源）
- 网址未按别名引用数据源
- 网址未使用通配符别名（请参阅数据源别名通配符）
当使用 Linking API 创建新的数据源时，该数据源会使用点击该网址的用户的凭据。这意味着用户必须有权访问底层数据，否则连接将无法正常运行。 通过将数据源重新添加到新生成的报告中，您可以保留其凭据，以便用户继续访问新报告中的数据。
数据源别名通配符
如需将一个 Links API 参数应用于多个数据源，可以使用通配符别名 ds.* 来代替数据源别名。
这对于移除网址中的重复参数非常有用。例如，如果您有一个附加了三个 BigQuery 数据源的模板，并且想要替换每个数据源中的 projectId 和 datasetId，但保留 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
更笼统地说，参数的优先级顺序如下：
- 具有特定别名 (
ds.ds1.datasetId) 的参数 - 使用通配符提供的参数 (
ds.*.datasetId) - 从模板数据源派生的值（如果未提供 ds.connector，请参阅替换与更新）
- 参数的默认值（可选）。
连接器参考文档
Links API 支持以下连接器和配置。对于每个连接器，我们都提供了可用的数据源参数列表。
BigQuery
BigQuery 连接器支持两种类型的查询：一种是 TABLE 查询，用于提供要查询的表的表 ID；使用 CUSTOM_QUERY 来提供用于查询表的 SQL 语句。
表查询
当 type 设置为 TABLE 并且您提供了要查询的表的 ID 时，以下参数适用。
| 参数名称 | 说明 |
|---|---|
可选。对于 BigQuery 连接器，应设置为 bigQuery。如果设置了此参数，会将数据源替换为提供的 BigQuery 配置。请参阅替换与更新。 |
|
必需** 查询的类型。设置为 TABLE。 |
|
| 必需** 要查询的表的项目 ID。 | |
| 必需** 要查询的表的数据集 ID。 | |
| 必需** 要查询的表的表 ID。 日期分片表： 查询日期分片表时支持 *（通配符）或 YYYYMMDD 后缀。如果某个表被标识为 Google Analytics（分析）、Firebase Analytics 或 Firebase Crashlytics，系统将选择默认字段模板（除非已指定）。请参阅字段模板表相关参数。 |
|
可选。用于结算的项目的 ID。如果未设置，系统将使用 projectId。 |
|
可选。如果表已分区，并且您希望将分区列用作日期范围维度，请将此参数设置为 true。这仅适用于基于时间的分区（例如，使用基于时间的分区列或 _PARTITIONTIME 伪列），而不适用于整数范围分区表。如果未指定，则默认为 false。如需了解详情，请参阅
分区表简介。 |
|
可选。如果未指定，则默认为 true。如需了解详情，请参阅 refreshFields。 |
适用于 Google Analytics（分析）、Firebase Analytics 和 Crashlytics 的字段模板
对于标识为 Google Analytics（分析）、Firebase Analytics 或 Firebase Crashlytics 的表，您还可以使用其他参数设置字段模板。如果未指定，系统将选择默认模板。
| 名称 | 说明 |
|---|---|
可选。要使用的 Google Analytics（分析）字段模板。仅在查询 Google Analytics（分析）表的 BigQuery Export 情况时才适用。ALL、SESSION 和 HITS 中的一个。对于 Google Analytics（分析）表，如果未指定，则默认为 ALL。 |
|
可选。要使用的 Firebase Analytics 字段模板。仅在查询 Firebase Analytics 表的 BigQuery Export 时才适用。只能设置为 EVENTS。对于 Firebase Analytics 表，如果未指定，则默认为 EVENTS。 |
|
要使用的 Firebase Crashlytics 字段模板。只能设置为 DEFAULT。仅在查询 Firebase Crashlytics 表的 BigQuery 导出作业时才适用。对于 Firebase Crashlytics 表，如果未指定，则默认为 DEFAULT。 |
自定义查询
如果将 type 设置为 CUSTOM_QUERY 并且您提供了 SQL 语句来查询表，则以下参数适用。
| 参数名称 | 说明 |
|---|---|
可选。对于 BigQuery 连接器，应设置为 bigQuery。如果设置了此参数，会将数据源替换为提供的 BigQuery 配置。请参阅替换与更新。 |
|
必需** 查询的类型。设置为 CUSTOM_QUERY。 |
|
| 必需** 要运行的 SQL 查询。 | |
可选。用于结算的项目的 ID。如果未设置，系统将使用 projectId。如果未设置 projectId，则将使用查询的表的项目。 |
|
|
可选。要应用于 SQL 查询的模式和替换字符串的逗号分隔列表。仅当存在模式匹配时，才会应用字符串替换。使用英文逗号分隔模式和替换字符串对。例如 |
|
可选。如果未指定，则默认为 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
使用 SESSION 字段模板查询适用于 Google Analytics（分析）的 BigQuery Export 表格的 TABLE 类型配置：
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 类型配置，其中使用 sqlReplace 更新模板数据源的 SQL 语句：
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
| 参数名称 | 说明 |
|---|---|
可选。对于 Cloud Spanner 连接器，应设置为 cloudSpanner。如果设置，则使用提供的 Cloud Spanner 配置替换数据源。请参阅替换与更新。 |
|
| 必填** 项目 ID。 | |
| 必填** 实例 ID。 | |
| 必填** 数据库 ID。 | |
| 必需** 要运行的 SQL 查询。 | |
可选。如果未指定，则默认为 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
社区连接器
| 参数名称 | 说明 |
|---|---|
可选。将社区连接器设置为 community。如果已设置，则会将数据源替换为提供的社区连接器配置。请参阅替换与更新。 |
|
必需** 社区连接器 connectorId（也称为 deploymentId）。
| |
| 可选。特定于连接器的其他参数，由社区连接器的 连接器配置定义。 | |
可选。如果未指定，则默认为 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（分析）
| 参数名称 | 说明 |
|---|---|
可选。对于 Google Analytics（分析）连接器，应设置为 googleAnalytics。如果设置此参数，会将数据源替换为提供的 Google Analytics（分析）配置。请参阅替换与更新。 |
|
| 必填** 帐号 ID。 | |
| 必填** 媒体资源 ID。 | |
| 数据视图 ID。 对于 Universal Analytics 媒体资源，此属性为必需属性**。 请勿为 Google Analytics（分析）4 媒体资源设置此参数。 |
|
可选。如果未指定，则默认为 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
| 参数名称 | 说明 |
|---|---|
可选。设置为 googleCloudStorage
Google Cloud Storage 连接器。如果设置，则会将数据源替换为提供的 Google Cloud Storage 配置。请参阅替换与更新。 |
|
必需** 路径类型。使用 FILE 选择单个文件，或使用 FOLDER 选择给定路径下的所有文件。 |
|
必需** 如果 pathType 为 FILE，则要求文件路径（例如 MyBucket/MyData/MyFile.csv）；如果 pathType 为 FOLDER，则为文件夹路径（例如，*MyBucket/MyData）。 |
|
可选。如果未指定，则默认为 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 表格
| 参数名称 | 说明 |
|---|---|
可选。对于 Google 表格连接器，应设置为 googleSheets。如果设置此参数，会将数据源替换为提供的 Google 表格配置。请参阅替换与更新。 |
|
| 必填** 电子表格 ID。 | |
| 必填** 工作表 ID。 | |
可选。设置为 true 可将第一行用作标题。如果未指定，则默认为 true。列标题必须是唯一的。标题为空的列将不会添加到数据源中。
|
|
可选。设置为 true 可包含隐藏的单元格。
如果未指定，则默认为 true。 |
|
可选。设置为 true 可包含已过滤的单元格。
如果未指定，则默认为 true。 |
|
| 可选。范围，例如 A1:B52。 | |
可选。如果未指定，则默认为 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
| 参数名称 | 说明 |
|---|---|
可选。对于
Looker 连接器，应设置为 looker。如果设置，则会将数据源替换为提供的 Looker 配置。请参阅替换与更新。 |
|
| 必需** Looker 实例网址。 | |
| 必需** Looker 模型。 | |
| 必需属性** Looker 探索。 | |
可选。如果未指定，则默认为 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
| 参数名称 | 说明 |
|---|---|
可选。对于 Search Console 连接器，应设置为 searchConsole。如果设置此参数，则会将数据源替换为提供的 Search Console 配置。请参阅替换与更新。 |
|
必填** 网站网址。对于网域资源，请使用 sc-domain\: 前缀。 |
|
必需** 设置表类型。可以是 SITE_IMPRESSION 或 URL_IMPRESSION 中的一个。 |
|
必需** 设置搜索类型。可以是 WEB、IMAGE、VIDEO 或 NEWS 之一。 |
|
可选。如果未指定，则默认为 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
模板权限
为确保用户获得最佳用户体验，请务必为模板报告和关联数据源正确设置报告访问权限。所需权限取决于报告模板使用的是嵌入式数据源还是可重复使用的数据源，以及 Links API 配置是否设置为替换或更新数据源配置。
下表根据模板数据源和 Linking API 配置，提供了为实现最佳用户体验而推荐的数据源访问权限：
| 数据源类型 | 关联数据源的 API 配置 | 数据源权限建议 | 备注 |
|---|---|---|---|
| 嵌入式 | 替换 | 不适用 - 数据视图访问权限将沿用自报告。 | 如果用户对模板报告拥有查看权限，则会自动获得对任何嵌入式数据源的查看权限。 |
| 嵌入式 | 更新 | 不适用 - 数据视图访问权限将沿用自报告。 | 如果用户对模板报告拥有查看权限，则会自动获得对任何嵌入式数据源的查看权限。 |
| 可重复使用 | 替换 | 用户无需查看权限。 | 由于系统将通过 Links API 完全替换数据源配置，因此无需查看权限。 |
| 可重复使用 | 更新 | 用户需要查看权限。 | 您需要拥有数据源的“查看”访问权限，关联 API 才能读取和使用模板数据源中的配置。如果用户没有查看权限，则会在加载报告时收到错误消息。 |
使用空白报告或默认报告
如需使用空白报告或默认报告，请按以下方式配置 Linking API：
| 报告类型 | 设置 reportId 控制参数 |
设置数据源 ( |
备注 |
|---|---|---|---|
| 空白报告 | 否 | 否 | |
| 默认报告 | 否 | 是 | 默认报告由 Looker 数据洞察提供。 在为默认报告指定数据源参数时，无需使用数据源别名，因为默认报告只有一个嵌入式数据源。 |
以下示例显示了使用空白报告或默认报告的各种 Linking 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/ 路径。Links API 嵌入网址必须采用以下格式：
https://lookerstudio.google.com/embed/reporting/create?parameters
查找 ID 和别名
报告 ID
要查找报告 ID，请执行以下操作：
- 打开要用作模板的报告。检查该报告的网址。
reporting/和/page之间的部分就是报告 ID。例如，在以下网址中，0B_U5RNpwhcE6SF85TENURnc4UjA就是报告 ID：
https://lookerstudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M
数据源别名
一个报告可以有多个数据源。数据源应通过别名进行引用。
要查找数据源别名，请执行以下操作：
- 修改报告。
- 在工具栏中，依次选择资源 > 管理添加的数据源。
- 查看别名列，找到每个数据源的别名信息。
您可以修改别名，以确保添加或移除数据源时的向后兼容性。
连接器类型
一个报告可以有多个数据源，每个数据源都是通过配置连接器创建的。要查找用于创建数据源的连接器类型，请执行以下操作：
- 修改报告。
- 在工具栏中，依次选择资源 > 管理添加的数据源。
- 查看连接器类型列，确定用于创建数据源的连接器。
提示和问题排查
如果您遇到问题，请查看以下详细信息，以确定潜在问题和常见的错误配置。
调试对话框
使用调试对话框查看 Looker Studio 解读的 Linking API 配置。它有助于调试 API 问题。
- 在解析 Links API 网址期间遇到错误时，系统会自动显示一个对话框，其中包含错误的详细信息。
- 如果发生错误且未自动显示对话框，请查找报告右上角的信息按钮。点击可获取其他调试信息。
- 如果没有显示信息按钮，您可以在任何 Linking API 网址末尾附加
&c.explain=true参数来启用该按钮。
权限
确保您为数据源类型和关联 API 配置设置了正确的模板权限。如需了解详情，请参阅模板权限。
更新与替换
如果要通过数据源模板更新数据源配置，请检查模板数据源配置和 Linking API 配置，确保它们兼容。确认新配置生成的字段与报告组件和配置兼容。
在执行更新与替换时，可能会设置具有未定义行为的无效配置。如需了解详情，请参阅替换与更新。
刷新字段
如果您为模板数据源配置了字段名称、类型或汇总，那么仅当 ds.refreshFields 参数设置为 false 时，这些更改才会延续到关联 API 配置的数据源。
查看 Linking API 网址的 ds.refreshFields 数据源参数。如果省略此参数，请确认每种连接器类型的参数默认值适合您的用例。
通常，如果您已在模板数据源中配置了字段，并且确定通过 Linking API 进行的新数据源配置始终会生成完全相同的字段，则建议将 refreshFields 设置为 false。
例如，如果在创建报告模板期间，Looker 数据洞察将特定数据源字段标识为 Number 类型，然后您将其更改为 Year 类型，那么此字段配置更改现在是模板数据源的一部分。报告模板中使用更正后的字段都将显示 Year；如果基于时间的图表是基于时间的，则可能不会呈现。如果使用 Linking API 提供产生完全相同字段的新数据源配置，那么根据 refreshFields 参数的值将会出现两种结果：
如果设置为
true，则模板数据源中的字段配置不会沿用，并且如果图表依赖于相同的字段配置（即，应为 Year 类型的字段），则图表可能无法加载。如果设置为
false，则模板数据源中的字段配置将沿用到新的数据源，报告图表将接收具有相同配置并成功加载的相同字段。
反馈和支持
请使用问题跟踪器报告关联 API 方面的问题或提供反馈。请参阅支持，获取有关获取帮助和提问的常规资源。
更新日志
2023-06-06
- 添加了
r.measurementId和r.keepMeasurementId报告参数，用于配置 Google Analytics（分析）衡量 ID 报告设置。 - 添加了
ds.keepDatasourceName，以控制模板数据源名称的重复使用。 - 新增了嵌入报告部分。
- BigQuery 连接器
- 添加了
sqlReplace。允许您指定格式和替换字符串，以更新模板数据源的 SQL 查询。
- 添加了
2023-05-22
2022-11-21
2022-11-14
- 由于 Google 问卷调查即将停用，问卷调查连接器引用已被移除。
2022-06-15
- 已完成 Beta 版测试
- Integration API 已重命名为 Linking API。
- 关联 API 已完成 Beta 版测试。
- 添加了
pageId控制参数，允许链接到特定报告页面。 - 添加了
mode控件参数，用于在加载时将报告状态设置为“查看”或“修改”模式。 - 数据源配置现在可以完全或部分替换。此行为取决于是否设置了
ds.connector参数。如需了解详情，请参阅替换与更新。 - 现在，如果未通过
c.reportId参数提供报告模板，则使用默认模板。 - 添加了
ds.refreshFields数据源参数。这样，您就可以控制在加载数据源配置时是否刷新数据源字段。 - BigQuery 连接器
- 如果将
type设置为CUSTOM_QUERY，则无需提供projectId。 - 如果未设置
billingProjectId，结算项目将回退到projectId或所查询表的项目。 - 新增了对日期分区表的支持。将
isPartitioned参数设置为true即可将分区字段用作日期范围维度。 - 新增了对使用通配符或
YYYYMMDD表后缀查询日期分区表的支持。 - 新增了查询 Google Analytics（分析）、Firebase Analytics 或 Crashlytics 表以及选择字段模板的支持。
- 如果将
- Google 表格
hasHeader默认为true，与网页界面默认值一致。includeHiddenAndFilteredCell分为includeHiddenCells和includeFilteredCells。现在两者均默认为true，与网页界面默认设置一致。
- Search Console 连接器
- 已将
propertyType参数重命名为searchType。
- 已将
- 问卷调查连接器
surveyId现在接受单个调查问卷 ID 或以英文逗号分隔的调查问卷 ID 列表。
2021 年 12 月 16 日
- Integration API 的初始版本。
- 支持链接到现有报告和设置报告名称。
- 可以配置多个数据源，并且可以为每个数据源设置名称。
- 支持以下连接器类型：BigQuery、Cloud Spanner、Google Analytics（分析）、Google Cloud Storage、Google 表格、Google 问卷调查、Search Console。