在 Looker Studio 中关联并直观呈现您的所有数据

1. 简介

借助 Looker Studio，您可以免费构建具有精美数据可视化图表的实时交互式信息中心。在 Looker Studio 中从各种来源提取数据，并创建无限数量的报告，同时还可使用完整的编辑和共享功能。以下屏幕截图展示了 Looker Studio 信息中心示例：

（点击此处可在 Looker Studio 中查看此示例报告）

社区连接器是 Looker Studio 的一项功能，可让您使用 Apps 脚本来构建与任何可通过互联网访问的数据源的连接器。社区连接器由 Looker Studio 社区构建。也就是说，任何人都可以构建社区连接器。您还可以与他人共享社区连接器，以便他们可以在 Looker Studio 中访问自己的数据。

您可以在不同的使用情形下使用社区连接器：

您正在可视化来自商业平台（例如社交媒体、营销、分析等）的数据
您正在直观呈现本地企业数据（例如本地 MySQL 数据库中的销售数据）
您正在为客户提供一种直观呈现其来自您服务的数据的方式
您正在创建一键式举报平台
您正在直观呈现来自网络来源的自有数据（例如，创建 Google 健身信息中心）

学习内容

Looker Studio 社区连接器的工作原理
如何使用 Google Apps 脚本构建社区连接器
如何在 Looker Studio 中使用社区连接器

所需条件

能够访问互联网和网络浏览器
Google 账号
熟悉基本的 JavaScript 和 Web API

2. 简短调查问卷

您为何选择此 Codelab？

我对数据可视化很感兴趣。

我想详细了解 Looker Studio

我想构建自己的社区连接器。

我正在尝试将 Looker Studio 与其他平台集成。

我对 Google Cloud 解决方案感兴趣。

您打算如何使用本 Codelab/教程？

仅浏览

阅读并完成练习

您对 Looker Studio 的熟悉程度如何？

从未听说过

我知道这是什么，但我不用它。

我经常使用它。

我是专家级用户。

哪项描述最符合您的背景？

开发者

业务 / 财务 / 数据分析师

数据科学家 / 数据工程师

营销 / 社交媒体 / 数字分析专家

设计师

其他

您可以前往下一页提交调查问卷信息。

3. 社区连接器概览

借助 Looker Studio 中的社区连接器，可以从 Looker Studio 直接连接到任何可通过互联网访问的数据源。您可以连接到商业平台、公开数据集或您自己的本地私有数据。社区连接器可以通过 Web API、JDBC API、扁平文件（CSV、JSON、XML）和 Apps 脚本服务提取数据。

假设您已在 npm 上发布了一个软件包，并且想要按天跟踪该软件包在一段时间内的下载次数。在本 Codelab 中，您将构建一个使用 npm 软件包下载次数 API 提取数据的社区连接器。然后，您可以在 Looker Studio 中使用该社区连接器构建信息中心，以直观呈现下载次数。

4. 社区连接器工作流程

在基本社区连接器中，您需要定义四个函数：

getAuthType()
getConfig()
getSchema()
getData()

Looker Studio 会根据工作流的当前步骤执行这些连接器函数，并在后续步骤中使用响应。以下视频概述了：

社区连接器的工作原理
工作流程中的不同步骤
调用不同函数时
Looker Studio 显示不同的界面时
不同步骤中的预期用户操作

观看完视频后，您可以继续完成 Codelab。

您无需记住此工作流，只需查看一下，了解连接器中会发生什么情况即可。您可以随时返回此图表。

在下一步中，您将开始在 Google Apps 脚本中创建连接器。您需要在 Apps 脚本界面和本 Codelab 之间来回切换。

5. 设置 Apps 脚本项目

第 1 步：访问 Google Apps 脚本。

第 2 步：点击左上角的“+ 新项目”，创建一个新的 Apps 脚本项目。

您将看到一个 shell 项目，其中 Code.gs 文件中包含一个空白的 myFunction 函数。

第 3 步：删除 myFunction 函数。

第 4 步：为项目命名：

点击页面左上角的 Untitled project
输入项目名称。

在 Code.gs 文件中开始编写连接器代码。

6. 定义 getAuthType()

当 Looker Studio 需要了解连接器使用的身份验证方法时，会调用 getAuthType() 函数。此函数应返回连接器授权第三方服务所需的身份验证方法。

对于您要构建的 npm 下载连接器，您无需向任何第三方服务进行身份验证，因为您使用的 API 不需要任何身份验证。复制以下代码并将其添加到 Code.gs 文件中：

Code.gs

var cc = DataStudioApp.createCommunityConnector();

function getAuthType() {
  var AuthTypes = cc.AuthType;
  return cc
    .newAuthTypeResponse()
    .setAuthType(AuthTypes.NONE)
    .build();
}

在此处，您表示连接器不需要任何第三方身份验证 (AuthTypes.NONE)。如需查看所有支持的身份验证方法，请参阅 AuthType() 参考。

7. 定义 getConfig()

连接器的用户需要先配置连接器，然后才能开始使用。getConfig() 函数响应定义了用户将看到的配置选项。Looker Studio 会调用 getConfig() 函数来获取连接器的配置详细信息。Looker Studio 会根据 getConfig() 提供的响应来呈现连接器配置屏幕并更改某些连接器行为。

在配置界面中，您可以使用以下表单元素提供信息或获取用户输入：

`TEXTINPUT`	输入元素	单行文本框。
`TEXTAREA`	输入元素	多行文本区域框。
`SELECT_SINGLE`	输入元素	一个包含多个选项的下拉列表，只能从中选择一个选项。
`SELECT_MULTIPLE`	输入元素	一个包含多个选项的下拉列表，可以从中选择多个选项。
`CHECKBOX`	输入元素	单个复选框，可用于捕获布尔值。
`INFO`	显示元素	一个静态的纯文本框，可用于向用户提供说明或信息。

使用 INFO 元素提供用户说明，并使用 TEXTINPUT 元素从用户处获取输入软件包名称。在 getConfig() 响应中，您将这些表单元素归入 configParams 键下。

由于您连接到的 API 需要将日期作为参数，因此请在 getConfig() 响应中将 dateRangeRequired 设置为 true。这会告知 Looker Studio 在所有数据请求中提供日期范围。如果您的数据源不需要将日期作为参数，则您可忽略此项。

将以下 getConfig() 代码添加到 Code.gs 文件中，放在 getAuthType() 的现有代码下方：

Code.gs

function getConfig(request) {
  var config = cc.getConfig();
  
  config.newInfo()
    .setId('instructions')
    .setText('Enter npm package names to fetch their download count.');
  
  config.newTextInput()
    .setId('package')
    .setName('Enter a single package name')
    .setHelpText('e.g. googleapis or lighthouse')
    .setPlaceholder('googleapis');
  
  config.setDateRangeRequired(true);
  
  return config.build();
}

根据这些 configParams，当您在 Looker Studio 中使用连接器时，您会看到如下所示的配置界面。不过，我们稍后会详细介绍这一点。

接下来，我们来看下一个函数 - getSchema()。

8. 定义 getSchema()

Looker Studio 会调用 getSchema() 函数，以获取与用户为连接器选择的配置相关联的架构。Looker Studio 会根据 getSchema() 提供的响应向用户显示字段界面，其中列出了连接器中的所有字段。

对于连接器的任何特定配置，架构都是连接器可以提供数据的所有字段的列表。连接器可能会根据不同的配置返回具有不同字段的不同架构。该架构可以包含从 API 源中提取的字段、在 Apps 脚本中计算的字段，以及在 Looker Studio 中使用计算字段公式计算的字段。连接器会提供架构中每个字段的元数据，包括：

字段的名称
字段的数据类型
语义信息

如需了解详情，请稍后查看 getSchema() 和 Field 参考。

架构可能是固定的，也可能在调用 getSchema() 时动态计算，具体取决于连接器的提取方式。用户在 getConfig() 中定义的配置参数将通过 () 函数的 request 实参提供。

在本 Codelab 中，您无需访问 request 实参。在下一部分中，您将为 getData() 函数编写代码，届时会详细了解 request 实参。

对于您的连接器，架构是固定的，包含以下 3 个字段：

`packageName`	用户提供的 npm 包的名称
`downloads`	npm 软件包的下载次数
`day`	下载次数的统计日期

以下是连接器的 getSchema() 代码。getFields() 辅助函数可抽象出字段的创建过程，因为 getSchema() 和 getData() 都需要此功能。将以下代码添加到您的 Code.gs 文件中：

Code.gs

function getFields(request) {
  var cc = DataStudioApp.createCommunityConnector();
  var fields = cc.getFields();
  var types = cc.FieldType;
  var aggregations = cc.AggregationType;
  
  fields.newDimension()
    .setId('packageName')
    .setType(types.TEXT);
  
  fields.newMetric()
    .setId('downloads')
    .setType(types.NUMBER)
    .setAggregation(aggregations.SUM);
  
  fields.newDimension()
    .setId('day')
    .setType(types.YEAR_MONTH_DAY);
  
  return fields;
}

function getSchema(request) {
  var fields = getFields(request).build();
  return { schema: fields };
}

根据此架构，当您在 Looker Studio 中使用此连接器时，预计会在 Looker Studio 字段界面中看到以下字段。不过，稍后在测试连接器时，您会详细了解这一点。

接下来，我们来看看最后一个函数 getData()。

9. 定义 getData()：第 1 部分

Looker Studio 会在需要提取数据时调用 getData() 函数。Looker Studio 会根据 getData() 提供的响应来呈现和更新信息中心内的图表。在以下事件期间可能会调用 getData()：

用户将图表添加到信息中心
用户修改图表
用户查看信息中心
用户修改与数据源相关联的过滤条件或数据控件
Looker Studio 需要数据样本

您无需从此页面复制任何代码，因为您将复制已完成的

getData()

后续步骤中的代码。

了解 `request` 对象

Looker Studio 会在每次 getData() 调用时传递 request 对象。请查看下方的 request 对象结构。这将有助于您为 getData() 函数编写代码。

`request` 对象结构

{
  configParams: object,
  scriptParams: object,
  dateRange: {
    startDate: string,
    endDate: string
  },
  fields: [
    {
      name: Field.name
    }
  ]
}

configParams 对象将包含 getConfig() 中定义并由用户配置的参数的配置值。
scriptParams 对象将包含与连接器执行相关的信息。在本 Codelab 中，您无需使用此功能。
如果 getConfig() 响应中请求了日期范围，则 dateRange 将包含所请求的日期范围。
fields 将包含请求数据的字段名称列表。

对于您的连接器，getData() 函数中的 request 示例可能如下所示：

{
  configParams: {
    package: 'jquery'
  },
  dateRange: {
    startDate: '2017-07-16',
    endDate: '2017-07-18'
  },
  fields: [
    {
      name: 'day',
    },
    {
      name: 'downloads',
    }
  ]
}

对于上述 request 中的 getData() 调用，即使连接器架构具有其他字段，也仅请求了两个字段。下一页将包含此 getData() 调用的示例响应和常规 getData() 响应结构。

10. 定义 getData()：第 2 部分

在 getData() 响应中，您需要为所请求的字段提供架构和数据。您将把代码划分为三个部分：

为所请求的字段创建架构。
从 API 中提取并解析数据。
转换已解析的数据并过滤出所请求的字段。

您无需从此页面复制任何代码，因为您将复制已完成的

getData()

下一页中的代码。

这是连接器的 getData() 结构。

function getData(request) {

  // TODO: Create schema for requested fields.
  
  // TODO: Fetch and parse data from API.
  
  // TODO: Transform parsed data and filter for requested fields.

  return {
    schema: <filtered schema>,
    rows: <transformed and filtered data>
  };
}

为所请求的字段创建架构

// Create schema for requested fields
  var requestedFieldIds = request.fields.map(function(field) {
    return field.name;
  });
  var requestedFields = getFields().forIds(requestedFieldIds);

从 API 中提取和解析数据

npm API 网址将采用以下格式：

https://api.npmjs.org/downloads/point/{start_date}:{end_date}/{package}

使用 Looker Studio 提供的 request.dateRange.startDate、request.dateRange.endDate 和 request.configParams.package 为 API 创建网址。然后，使用 UrlFetchApp（Apps 脚本类：参考）从 API 中提取数据。然后解析提取的响应。

  // Fetch and parse data from API
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ];
  var response = UrlFetchApp.fetch(url.join(''));
  var parsedResponse = JSON.parse(response).downloads;

转换已解析的数据并过滤请求的字段

来自 npm API 的响应将采用以下格式：

{
  downloads: [
    {
    day: '2014-02-27',
    downloads: 1904088
    },
    ..
    {
    day: '2014-03-04',
    downloads: 7904294
    }
  ],
  start: '2014-02-25',
  end: '2014-03-04',
  package: 'somepackage'
}

转换来自 npm API 的响应，并以以下格式提供 getData() 响应。如果您不清楚此格式，请参阅下一段中的示例回答。

{
  schema: [
    {
      object(Field)
    }
  ],
  rows: [
    {
      values: [string]
    }
  ]
}

在响应中，使用 schema 属性仅返回所请求字段的架构。您将使用 rows 属性以行列表的形式返回数据。对于每一行，values 中的字段序列必须与 schema 中的字段序列一致。根据我们之前有关 request 的示例，getData() 的响应将如下所示：

{
  schema: requestedFields.build(),
  rows: [
    {
      values: [ 38949, '20170716']
    },
    {
      values: [ 165314, '20170717']
    },
    {
      values: [ 180124, '20170718']
    },
  ]
}

您已创建架构子集。使用以下函数转换解析后的数据，并针对所请求的字段进行过滤。

function responseToRows(requestedFields, response, packageName) {
  // Transform parsed data and filter for requested fields
  return response.map(function(dailyDownload) {
    var row = [];
    requestedFields.asArray().forEach(function (field) {
      switch (field.getId()) {
        case 'day':
          return row.push(dailyDownload.day.replace(/-/g, ''));
        case 'downloads':
          return row.push(dailyDownload.downloads);
        case 'packageName':
          return row.push(packageName);
        default:
          return row.push('');
      }
    });
    return { values: row };
  });
}

11. 定义 getData()：第 3 部分

合并后的 getData() 代码如下所示。将以下代码添加到您的 Code.gs 文件中：

Code.gs

function responseToRows(requestedFields, response, packageName) {
  // Transform parsed data and filter for requested fields
  return response.map(function(dailyDownload) {
    var row = [];
    requestedFields.asArray().forEach(function (field) {
      switch (field.getId()) {
        case 'day':
          return row.push(dailyDownload.day.replace(/-/g, ''));
        case 'downloads':
          return row.push(dailyDownload.downloads);
        case 'packageName':
          return row.push(packageName);
        default:
          return row.push('');
      }
    });
    return { values: row };
  });
}

function getData(request) {
  var requestedFieldIds = request.fields.map(function(field) {
    return field.name;
  });
  var requestedFields = getFields().forIds(requestedFieldIds);

  // Fetch and parse data from API
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ];
  var response = UrlFetchApp.fetch(url.join(''));
  var parsedResponse = JSON.parse(response).downloads;
  var rows = responseToRows(requestedFields, parsedResponse, request.configParams.package);

  return {
    schema: requestedFields.build(),
    rows: rows
  };
}

您已完成 Code.gs 文件的操作！接下来，更新清单。

12. 更新清单

在 Apps 脚本编辑器中，依次选择项目设置 > 在编辑器中显示“appsscript.json”清单文件。

这将创建一个新的 appsscript.json 清单文件。

将 appscript.json 文件替换为以下内容：

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",

  "dataStudio": {
    "name": "npm Downloads - From Codelab",
    "logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20logo/npm-logo-red.png",
    "company": "Codelab user",
    "companyUrl": "https://developers.google.com/looker-studio/",
    "addonUrl": "https://github.com/googledatastudio/example-connectors/tree/master/npm-downloads",
    "supportUrl": "https://github.com/googledatastudio/community-connectors/issues",
    "description": "Get npm package download counts.",
    "sources": ["npm"]
  }
}

保存 Apps 脚本项目。

恭喜！您已构建了首个社区连接器，可以进行试用！

13. 在 Looker Studio 中测试连接器

使用部署

第 1 步：在 Apps 脚本开发环境中，依次点击部署 > 测试部署，打开“测试部署”对话框。

系统会列出默认部署，即主部署。

第 2 步：点击复制以复制头部部署 ID。

第 3 步：如需在 Looker Studio 中加载连接器，请将以下链接中的 <HEAD_DEPLOYMENT_ID> 占位符替换为连接器的 Head 部署 ID，然后在浏览器中打开该链接：

https://lookerstudio.google.com/datasources/create?connectorId=<HEAD_DEPLOYMENT_ID>

授权连接器

首次使用 Looker Studio 的用户：如果您之前未使用过 Looker Studio，系统会要求您授权 Looker Studio 并同意相关条款及条件。完成授权流程。首次使用 Looker Studio 时，您可能还会看到一个用于更新营销偏好的对话框。如果您想通过电子邮件了解最新功能、更新和产品公告，请订阅产品公告。

加载完成后，您会看到授权连接器的提示。

点击“授权”，并向连接器提供所需的授权。

配置连接器

授权完成后，系统会显示配置界面。在文本输入区域中输入“lighthouse”，然后点击右上角的“连接”。

确认架构

您将看到“字段”界面。点击右上角的创建报告。

创建信息中心

您将进入 Looker Studio 信息中心环境。点击添加到报告。

在 Looker Studio 中，每当用户访问连接器并添加新配置时，系统都会在用户的 Looker Studio 账号中创建一个新的数据源。您可以将数据源视为基于特定配置的连接器实例化。数据源会根据连接器和用户选择的配置返回包含一组特定字段的数据表。用户可以根据同一连接器创建多个数据源。一个数据源可用于多个报告，而同一报告可使用多个数据源。

现在，添加一个时序图表！在菜单中，依次点击插入 > 时序图表。然后将时间序列放置在画布中。您应该会看到所选软件包的 npm 下载次数时序图表。添加日期过滤器控件，并查看信息中心，如下所示。

大功告成！您刚刚创建了第一个社区连接器！本 Codelab 至此结束。现在，让我们看看您可以采取哪些后续步骤。

14. 后续步骤

改进您构建的连接器

改进您刚刚构建的连接器：

在 Looker Studio 中，如果您未在连接器的配置界面中提供软件包名称，则在绘制时序图表时会看到一条出错提示。尝试向连接器配置添加输入验证或默认选项。
尝试在连接器配置中添加对同时查询多个软件包名称的支持。提示：npm 软件包下载次数 API 支持以英文逗号分隔的多个软件包名称作为输入。
您可以在我们的 npm 连接器代码中找到这两种问题的解决方案。

利用社区连接器执行更多操作

查看连接器 API 和清单的参考文档。
您可以浏览我们的开源代码库，了解连接器代码示例，从而掌握最佳实践。
完成 clasp Codelab，以便您可以在本地环境中开发社区连接器。
构建完整的社区连接器后，请考虑可用的发布选项。
为 Looker Studio 构建社区可视化图表。

其他资源

以下是您可以访问的各种资源，可帮助您更深入地了解本 Codelab 中涵盖的内容。

资源类型	用户功能	开发者功能
文档	帮助中心	开发者文档
新闻和最新动态	在 Looker Studio 中注册 > 用户设置	开发者邮寄名单
提问	用户论坛	Stack Overflow [looker-studio]
视频	DataVis DevTalk
示例	报告库连接器库	开源代码库

在 Looker Studio 中关联并直观呈现您的所有数据

1. 简介

学习内容

所需条件

2. 简短调查问卷

您为何选择此 Codelab？

您打算如何使用本 Codelab/教程？

您对 Looker Studio 的熟悉程度如何？

哪项描述最符合您的背景？

3. 社区连接器概览

4. 社区连接器工作流程

5. 设置 Apps 脚本项目

6. 定义 getAuthType()

Code.gs

7. 定义 getConfig()

Code.gs

8. 定义 getSchema()

Code.gs

9. 定义 getData()：第 1 部分

了解 request 对象

request 对象结构

10. 定义 getData()：第 2 部分

为所请求的字段创建架构

从 API 中提取和解析数据

转换已解析的数据并过滤请求的字段

11. 定义 getData()：第 3 部分

Code.gs

12. 更新清单

appsscript.json

13. 在 Looker Studio 中测试连接器

使用部署

授权连接器

配置连接器

确认架构

创建信息中心

14. 后续步骤

改进您构建的连接器

利用社区连接器执行更多操作

其他资源

了解 `request` 对象

`request` 对象结构