开始使用社区可视化

步骤:

  • 编写可视化文件 (JavaScript)
  • 编写可视化配置文件 (JSON)
  • 将文件上传到 Cloud Storage (GCS)
  • 用 Apps 脚本创建和部署清单以获取部署 ID
  • 使用部署 ID 在数据洞察中创建报告,加载可视化文件
  • 在报告画布上绘制可视化图表

基本信息和示例文件

已知问题

  • 在修改模式下,您无法直接从报告画布中选择可视化组件。 您需要选中拖动组件才能让可视化组件显示在屏幕中间。
  • GCS 有点不太可靠。如有其他问题,请参阅下面的“错误/问题排查”部分。

标记 (PROD)

如果您位于 ga-lego 组中,则在生产环境中应默认启用该功能。

示例文件

以下文件与本文档剩余部分的说明中的示例相对应:

编写可视化文件

MessageEvent 发布到窗口。该事件包含所有样式和配置数据。然后,您可以随意执行任何操作...

(function() {

  /**
   * There is a race condition in prod that prevents this event listener
   * from being registered before the MessageEvent is dispatched.
   * Workaround: Add your viz to the Data Studio report as normal. Then
   * force a MessageEvent dispatch by making a change to the viz
   * (E.g. resize the viz component, add/change a dimension/metric).
   **/
  window.addEventListener("message", handleMessage);

  function handleMessage(event) {
    console.log('Hello Viz World!')

    console.log('Take a look at the event object:');
    console.log(event);

    console.log('Data to render:');
    console.log(event.data.dataRows);

    console.log('Selected Dims/Mets:');
    console.log(event.data.concepts);

    console.log('Style config:');
    console.log(event.data.style);

    console.log('D3 is also available!');
    console.log(d3);
  }

  document.body.innerHTML = "I can manipulate the DOM!";

  window.parent.postMessage({
      deploymentId: 'YOUR_APPS_SCRIPT_DEPLOYMENT_ID',
      type: 'vizReady'
  }, '*');

})();

示例:公开可视化文件 viz.js

编写可视化配置文件

这将对维度/指标、行和样式施加限制。样式元素按顺序呈现。支持以下元素:

  • 字体颜色
  • 字号
  • 字体系列
  • 复选框
{
  "propertyConfig": {
    "data": {
      "maxDimensions": 2,
      "minDimensions": 2,
      "minMetrics": 1,
      "maxMetrics": 2,
      "maxRows": 500
    },
    "style": [{
      "name": "general",
      "heading": "General",
      "elements": [{
        "name": "useSingleColor",
        "label": "Single Color",
        "type": "CHECKBOX"
      }, {
        "name": "reverseColor",
        "label": "Show reverse color",
        "defaultValue": "false",
        "type": "CHECKBOX"
      }, {
        "name": "showText",
        "label": "Show Text",
        "defaultValue": "true",
        "type": "CHECKBOX"
      }, {
        "name": "fontSize",
        "label": "Font size",
        "defaultValue": "10",
        "type": "FONT_SIZE"
      }, {
        "name": "fontColor",
        "label": "Font color",
        "defaultValue": "#fff",
        "type": "FONT_COLOR"
      }, {
        "name": "font",
        "label": "Font family",
        "defaultValue": "auto",
        "type": "FONT_FAMILY"
      }]
    }]
  }
}

示例:公开可视化配置文件 viz.json

为可视化文件命名

  • 可视化文件名可以是任何以 .js 结尾的文件名。
  • 可视化配置文件名必须与可视化文件名一样,但以 .json 结尾。
  • 例如,myVizFileName.jsmyVizFileName.json

将文件上传到 Google Cloud Storage (GCS)

您可以使用任何 Cloud 项目进行存储。但为简单起见,您可以使用在创建新的 Apps 脚本项目时自动配置的 Cloud 项目。这样一来,您的 Apps 脚本清单和部署 ID 就会与您在 GCS 中的可视化文件相关联了。

  • 转到 Apps 脚本
  • 点击左上角的 + 新建脚本
  • 为您的项目命名
  • 在菜单中,点击资源->云端平台项目…
  • 点击指向关联 Cloud 项目的链接。这时系统会将您转到 Cloud Platform 控制台。
  • 在 Cloud Platform 控制台的左侧导航菜单中,选择存储
  • 创建存储分区
    • 存储分区类型:最佳选择是“区域”(美国西部、东部或中部)类型。就此使用情形而言,免费方案已绰绰有余。
    • 您稍后会在 Apps 脚本清单中用到此存储分区名称。
    • 如果您没有存储分区或无法创建存储分区,可以尝试使用此项目
  • 将您的可视化 JS 文件和可视化配置 JSON 文件上传到存储分区。
  • 将这些文件标记为“公开”

示例:自动配置的 Cloud 项目

编写 Apps 脚本清单并进行部署

清单描述了您的可视化文件,并对其进行打包,以用于数据洞察中。它会提供有关可视化的详细信息,包括可视化文件的存储位置。

  • 在 Apps 脚本项目中,点击菜单中的查看->显示清单文件。 您应该会看到一个新增的 appsscript.json 文件。
  • 编写清单。在下面的示例中,替换 YOUR_GCS_BUCKET_NAME 和 YOUR_VIZ_FILENAME。您无需列出 JSON 文件。
  • 保存清单文件。
  • 在菜单中,点击发布->从清单部署…
  • 从“部署”窗口点击获取 ID
  • 复制部署 ID
{
  "dataStudioVisualization": {
    "name": "Viz",
    "logoUrl": "http://www.google.com",
    "company": "Google",
    "supportUrl": "https://datastudio.google.com",
    "description": "Visualization example!",
    "visualizations": [{
      "name": "treemap",
      "description": "Viz",
      "resource": {
        "js": "YOUR_GCS_BUCKET_NAME/YOUR_VIZ_FILENAME.js",
        "config": "YOUR_GCS_BUCKET_NAME/YOUR_VIZ_CONFIG_FILENAME.json"
      }
    }]
  }
}

示例:Apps 脚本清单文件

测试可视化

  • 转到数据洞察、创建报告、添加数据。
  • 您应该会在工具栏中看到第三方可视化按钮。点击该按钮以使用部署 ID 加载可视化组件
    • 社区可视化加载按钮
  • 绘制可视化图表
  • 检查控制台,看看是否有错误、日志等。

示例:包含可视化数据的数据洞察报告

更改您的可视化(工作流程)

  • 完成上述步骤并且在您的报告中纳入可视化组件后,接下来的流程应该是
    • 在本地更新代码并保存
    • 使用 gsutil 上传或使用 GCS 浏览器手动上传。
    • 进入数据洞察,刷新包含可视化组件的报告。
  • 您应该不需要进行部署或返回到 Apps 脚本。
  • 您还可以使用不同的部署 ID 在一个报告中加载多个可视化组件。

错误/问题排查

  • 检查将 GCS 中的文件设为公开能否解决问题。如果您使用 gsutil 将文件复制到存储分区,则可能需要再次将这些文件设为公开。
  • 检查您是否已对数据洞察数据源页面中的 GCS 连接器进行身份验证。
  • 如果您遇到随机错误,不妨刷新一下试试,GCS 有时会出现问题。

    ...基本上,如果出现问题,请检查 GCS。

共享报告

  • 确保您的 Apps 脚本项目共享设置已设为“知道链接的人可以查看”。
  • 确保 GCS 文件已标记为“公开”。