简介
Linking API 提供了一个可靠的接口，可以通过网址配置 Looker Studio 报告并将用户直接引导至此类报告。当用户访问 Linking API 网址时，将会获得流畅的体验，可以快速查看他们的数据并与之互动。
本文档介绍了关联 API 网址所需的格式及可用参数。
使用情形和优势
Linking API 可用于提供预配置的报告，以便您的客户查看他们的数据并与之互动。Linking API 的主要优势如下：
- 为您的客户提供一键式报告创建体验。
- 数据配置在网址中提供，因此用户无需配置数据报告。
- 用户只需点击一下即可保存报告，然后就能随时重新访问相应报告。
- 大规模创建报告。Linking API 可缩短复制或创建新报告所需的时间。
- 实现产品集成。借助稳定的接口，您可以将 Looker Studio 集成到产品工作流程中。
运作方式
下面介绍了开发者和用户如何与 Linking API 互动。
Linking API 开发者工作流程
开发者准备模板报告、数据源，并设置关联 API 网址的格式。开发者的典型工作流程如下：
- 决定是使用空白报告、Looker Studio 提供的默认报告模板，还是创建将用作模板的 Looker Studio 报告。这包括配置模板数据源。
- 根据您的具体使用情形设置关联 API 网址的格式。如果适用，请指定报告模板和其他参数，包括报告名称、数据源名称和数据源配置。
- 使用 Linking API 网址将用户引导至报告。
Linking API 用户体验
用户访问 Linking API 网址后，如果开发者已正确配置该网址，系统会将用户引导至 Looker Studio 报告，以便用户查看和互动他们有权访问的数据。典型的用户体验可能如下：
- 在浏览器中，用户访问集成了关联 API 的服务。
- 号召性用语吸引用户点击链接，以在 Looker Studio 中查看他们的数据。
- 用户点击该链接后转到 Looker Studio 报告。报告加载完毕，用户可以查看数据并与之互动。
- 用户点击“修改并分享”。报告随即保存到用户的 Looker Studio 账号中。
- 用户现在对自己的报告副本拥有完全的访问和控制权限。他们可以随时查看、修改和分享该副本。
要求
为确保关联 API 网址按预期工作，需要满足以下条件：
- 用作模板的报告。如果未提供，则可以使用 Looker Studio 提供的空白报告或默认报告。
- 链接 API 网址的用户必须至少拥有对模板报告的查看权限。根据报告中使用的数据源类型以及通过 Linking API 提供的配置，用户可能还需要对数据源拥有查看权限。如需了解详情，请参阅模板权限。
- 每个数据源的连接器类型都必须支持通过 Linking API 进行配置。如需查看支持的连接器列表，请参阅连接器参考信息。
- 使用关联 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 网址查看报告时的报告状态。
| 参数名称 | 说明 |
|---|---|
| 可选。模板报告 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，请参阅数据源别名。
数据源参数
以下参数是所有连接器类型通用的：
| 名称 | 说明 |
|---|---|
|
可选。设置数据源的名称。 如果未指定 |
|
|
可选。设置为 如果未指定 |
|
|
可选。
数据源的连接器类型。如需详细了解支持的连接器类型，请参阅连接器参考信息。 如果设置了此参数，则必须在 Linking API 网址中指定连接器类型的所有必需 连接器参数，并且模板数据源配置将被完全替换。 如果未指定，则可以在关联 API 网址中为连接器类型指定零个或多个 连接器参数。模板数据源配置将用于指定 Linking API 网址中未提供的任何参数。如需详细了解如何确定模板数据源的连接器类型，请参阅连接器类型。 如需详细了解 |
|
|
可选。
设置为 设置为 如果未指定，则默认值因连接器类型而异。如果您想替换默认行为，请查看连接器参考信息，了解连接器特定的默认值。 使用
refreshFields 时的注意事项： |
|
| 必需。连接器类型的数据源配置。如需详细了解如何确定用于创建数据源的连接器，请参阅连接器类型。如需详细了解每种连接器类型可用的数据源参数，请参阅连接器参考信息。 |
替换与更新 - 数据源配置
设置数据源参数时，关联 API 网址中是否存在 ds.connector 参数表示相应意图是替换还是更新模板数据源配置。
下表详细说明了 ds.connector 参数如何影响模板数据源配置是完全替换还是用于更新未指定的参数：
是否已设置 ds.connector？ |
预期配置和行为 | 典型用途 |
|---|---|---|
| 是 |
替换。系统会使用关联 API 网址中指定的数据源参数完全替换模板数据源配置。您必须为连接器类型指定所有必需的参数。请参阅设置 ds.connector 时的必需参数。
|
|
| 否 | 更新。模板数据源配置将用于指定 Linking API 网址中未提供的任何参数。除非另有说明，否则连接器类型的所有连接器参数都是可选的。
这样可以简化关联 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 创建新数据源时，该数据源会使用点击相应网址的用户的凭据。这意味着用户必须有权访问底层数据，否则连接将无法正常运行。 通过将数据源重新添加到新生成的报告中，您可以保留其凭据，以便用户可以继续访问新报告中的数据。
数据源别名通配符
如需将关联 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
提供给 Linking 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，请参阅替换与更新）
- 参数的默认值（如果参数是可选的）。
连接器参考信息
Linking API 支持以下连接器和配置。对于每种连接器，我们都提供了可用的数据源参数列表。
BigQuery
BigQuery 连接器支持两种类型的查询：TABLE 查询（您可以在其中提供要查询的表的表 ID）和 CUSTOM_QUERY 查询（您可以在其中提供 SQL 语句来查询表）。
TABLE 查询
当 type 设置为 TABLE 且您提供要查询的表的 ID 时，以下参数适用。
| 参数名称 | 说明 |
|---|---|
可选。对于 BigQuery 连接器，应设置为 bigQuery。如果设置，则使用提供的 BigQuery 配置替换数据源。请参阅替换与更新。 |
|
必需** 查询的类型。设置为 TABLE。 |
|
| 必需** 要查询的表的项目 ID。 | |
| 必需** 要查询的表的 Dataset 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 导出表时适用。ALL、SESSION、HITS 中的一个。对于 Google Analytics 表，如果未指定，则默认为 ALL。 |
|
可选。要使用的 Firebase Analytics 字段模板。仅在查询 Firebase Analytics 表的 BigQuery 导出数据时适用。
只能设置为 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
| 参数名称 | 说明 |
|---|---|
可选。对于 Google Cloud Storage 连接器，应设置为 googleCloudStorage。如果设置，则使用提供的 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
模板权限
为确保用户享有最佳体验，请务必为模板报告和关联的数据源正确设置报告访问权限。所需的权限取决于报告模板是使用嵌入式数据源还是可重用数据源，以及关联 API 配置是设置为替换还是更新数据源配置。
下表根据模板数据源和 Linking API 配置，提供了建议的数据源访问权限，以实现最佳用户体验：
| 数据源类型 | 关联数据源的 API 配置 | 数据源权限建议 | 备注 |
|---|---|---|---|
| 嵌入式 | 替换 | 不适用 - 查看权限将从报告继承。 | 如果用户对模板报告拥有查看权限，则会自动对任何嵌入式数据源拥有查看权限。 |
| 嵌入式 | 更新 | 不适用 - 查看权限将从报告继承。 | 如果用户对模板报告拥有查看权限，则会自动对任何嵌入式数据源拥有查看权限。 |
| 可重复使用 | 替换 | 用户无需查看权限。 | 由于数据源配置将通过 Linking API 完全替换，因此不需要查看权限。 |
| 可重复使用 | 更新 | 用户需要查看权限。 | 必须拥有数据源的查看权限，Linking API 才能读取和使用模板数据源中的配置。如果用户没有查看权限，则在加载报告时会收到错误消息。 |
使用空白报告或默认报告
如需使用空白报告或默认报告，请按如下方式配置 Linking API：
| 报告类型 | 设置 reportId 控制参数 |
设置数据源 ( |
备注 |
|---|---|---|---|
| 空白报告 | 否 | 否 | |
| 默认报告 | 否 | 是 | 默认报告由 Looker Studio 提供。 为默认报告指定数据源参数时，无需使用数据源别名，因为默认报告只有一个嵌入式数据源。 |
以下示例展示了使用空白报告或默认报告的各种 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
嵌入报告
如需嵌入使用 Linking API 创建的报告，请设置 网址 参数并添加 /embed/ 路径。Linking 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 问题。
- 如果在解析关联 API 网址时遇到错误，系统会自动显示一个对话框，其中包含有关该错误的详细信息。
- 如果发生错误，但系统未自动显示对话框，请在报告的右上角附近寻找信息按钮。点击可查看更多调试信息。
- 如果没有信息按钮，您可以通过将
&c.explain=true参数附加到任何关联 API 网址的末尾来启用该按钮。
权限
确保您已为数据源类型和 Linking API 配置设置正确的模板权限。如需了解详情，请参阅模板权限。
更新与替换
如果要从数据源模板更新数据源配置，请检查模板数据源配置和 Linking API 配置，确保它们兼容。确认新配置生成的字段与报告组件和配置兼容。
在执行更新而非替换时，可能会设置具有未定义行为的无效配置。如需了解详情，请参阅替换与更新。
刷新字段
如果您为模板数据源配置了字段名称、类型或汇总，则只有当 ds.refreshFields 参数设置为 false 时，这些更改才会转移到通过 Linking API 配置的数据源。
检查您的关联 API 网址的 ds.refreshFields 数据源参数。如果省略，请确认每个连接器类型的参数默认值是否适合您的使用情形。
一般来说，如果您已在模板数据源中配置字段，并且确定通过 Linking API 进行的新数据源配置始终会生成完全相同的字段，建议将 refreshFields 设置为 false。
例如，如果在创建报告模板期间，Looker Studio 将某个数据源字段识别为“数字”类型，而您将其更改为“年份”类型，则此字段配置更改现在会成为模板数据源的一部分。报告模板中任何使用更正后字段的图表都将需要年份，如果图表是基于时间的，则可能无法呈现。如果使用 Linking API 提供可生成完全相同字段的新数据源配置，则会根据 refreshFields 参数的值出现两种结果：
如果设置为
true，则模板数据源中的字段配置将不会沿用，并且如果图表依赖于相同的字段配置（即需要 Year 类型的字段），则可能会无法加载。如果设置为
false，模板数据源中的字段配置将沿用到新数据源，报告图表将接收具有相同配置的相同字段并成功加载。
反馈和支持
请使用问题跟踪器报告 Linking API 问题或提供反馈。如需获取有关如何寻求帮助和提问的一般资源，请参阅支持。
更新日志
2023-06-06
- 添加了
r.measurementId和r.keepMeasurementId报告参数，用于配置 Google Analytics 衡量 ID 报告设置。 - 添加了
ds.keepDatasourceName以控制模板数据源名称的重用。 - 添加了嵌入报告部分。
- BigQuery 连接器
- 添加了
sqlReplace。用于指定模式和替换字符串，以更新模板数据源的 SQL 查询。
- 添加了
2023-05-22
2022-11-21
- 添加了使用空白报告的功能。请参阅使用空白报告或默认报告
- 在提示和问题排查中添加了
refreshFields部分。
2022-11-14
- 由于 Google 问卷调查停用，问卷调查连接器参考已被移除。
2022-06-15
- 结束 Beta 版测试
- 集成 API 已重命名为关联 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，与 Web 界面的默认设置保持一致。
- Search Console 连接器
- 将
propertyType参数重命名为searchType。
- 将
- Google 问卷连接器
surveyId现在接受单个调查 ID 或以英文逗号分隔的调查 ID 列表。
2021 年 12 月 16 日
- Integration API 的初始版本。
- 支持链接到现有报告和设置报告名称。
- 可以配置多个数据源，并且可以为每个数据源设置名称。
- 支持以下连接器类型：BigQuery、Cloud Spanner、Google Analytics、Google Cloud Storage、Google 表格、Google 问卷调查、Search Console。