为 Looker Marketplace 开发自定义块

本页介绍了如何创建可添加到 Looker Marketplace 并供其他 Looker 用户访问的自定义块。

请注意，您必须是 Looker 合作伙伴网络的成员或 Looker 客户，才能向 Looker Marketplace 提交内容。

如需了解已构建且可供使用的 Looker 块，请参阅 Looker 块文档页面。如需了解如何自定义从 Marketplace 安装的块，请参阅 Customizing Looker Marketplace Blocks（自定义 Looker Marketplace 中的块）文档页面。

如需开发一个块并通过 Looker Marketplace 将其提供给所有 Looker 用户，请按照本页中所述的步骤操作：

  1. 设置数据源并将其连接到 Looker。
  2. 创建项目并添加所需文件。
  3. 让您的版块易于访问。
  4. 提交要接受 Looker 审核的屏蔽对象。

设置数据源并将其连接到 Looker

分块是数据模型，因此当它们针对特定且易于重复的数据集进行设计时，效果最佳。当用户的数据集与块中的架构、表和字段名称不匹配时，就会发生大多数块安装错误。

  • 如果您要为特定数据集（例如 Google Analytics [分析] 数据）构建数据块，请记下您对该数据集所做的任何设置或自定义操作。请尽可能减少此类自定义，以便为用户简化安装流程。在 README 文件中提供具体说明。
  • 如果您要为常规分析模式（例如同类群组留存率）构建块，请记下您希望用户的数据集包含哪些字段。用户使用的架构、表和字段名称很可能与数据集中的名称不同。请为表格和字段名称使用 LookML 常量，并在自述文件中告知用户需要更新哪些字段。

确定数据源后，请将数据源连接到 Looker，以便开始建模。如果您需要更改任何默认连接设置，请在 README 文件中记下相关说明。

创建项目并添加所需文件

创建一个项目来代表您的广告连播。考虑使用 block-<database_dialect>-<role> 等命名惯例（例如 block-redshift-admin）。

接下来，在项目中创建以下文件：

  • 用于定义项目名称、连接名称和任何其他常量的清单文件
  • 每个视图对应的视图文件
  • 每个探索对应的探索文件
  • 一个模型文件，其中包含项目中的所有视图文件、探索文件和 LookML 信息中心文件
  • 至少三个 LookML 信息中心文件
  • 一个 marketplace.json 文件，其中包含将在此版块的 Marketplace 商品详情中显示的信息
  • 包含 MIT 开源许可文本的 LICENSE 文件
  • 详细说明设置说明和选项的 README 文件

安装您的版块的用户可以在单独的 refinements.lkml 文件中优化基本探索、视图和信息中心。以下部分更详细地介绍了每种必需文件类型：

创建清单文件

为您的项目创建清单文件。清单文件应以项目名称开头，然后定义一些供用户更改的 LookML 常量。例如，您应使用 export: override_required 将 Looker 连接名称定义为常量，以便用户可以使用自己的连接名称替换它。

下面是一个清单文件示例：

project_name: "block-ga-360"

################# Constants ################

## Used in google_analytics_block.model connection param
constant: CONNECTION_NAME {
  value: "looker-private-demo"
  export: override_required
}

## Used in ga_sessions.view sql_table_name
constant: SCHEMA_NAME {
  value: "bigquery-public-data.google_analytics_sample"
  export: override_optional
}

constant: GA360_TABLE_NAME {
  value: "ga_sessions_*"
  export: override_optional
}

创建视图和探索文件

为每个视图创建一个 view.lkml 文件。如果用户的架构和表名称可能与您的架构和表名称不同，请务必在清单文件中将架构和表名称定义为常量，以便下载您屏蔽程序的用户可以更新自动生成的清单文件中的架构和表名称。然后，在视图的 sql_table_name 参数中引用这些常量。

以下是一个块 view.lkml 文件的示例：

view: user_facts {

  # SCHEMA_NAME and GA360_TABLE_NAME are constants
  sql_table_name: @{SCHEMA_NAME}.@{GA360_TABLE_NAME} ;;

  dimension: clientID {
    type: string
    sql: ${TABLE.clientId}
  }

}

接下来，创建一个或多个 explore.lkml 文件。确保每个探索文件都包含该探索所需的视图。精心设计您的探索，使其包含逻辑联接、数据分析和精选探索页面。其他用户从 Marketplace 安装该版块后，其企业用户应该可以轻松上手并开始分析数据。

您可以在我们的社区论坛和 Looker 最佳实践中找到有关建模最佳实践的一般列表，例如最佳实践：LookML 的注意事项和禁忌以及最佳实践：编写可持续、可维护的 LookML。

以下是 explore.lkml 文件的示例：

include: "/Google_Analytics/Sessions/*.view.lkml"

explore: future_input {
  view_label: "Audience Traits"
  label: "BigQuery ML Customer Likelihood to Purchase"
  description: "This explore allows you to slice and dice likeliness to purchase scores by different customer traits to see how they differ. The default range of data you are looking at is in the past 30 days"
  join: future_purchase_prediction {
    type: left_outer
    sql_on: ${future_purchase_prediction.clientId} = ${future_input.client_id} ;;
    relationship: one_to_one
  }
}

创建模型文件

创建一个模型文件，其中包含项目中的所有视图、探索和信息中心文件。确保在清单文件中将连接名称引用为 LookML 常量。

请定义至少一个 datagroup 以设置缓存政策。

以下是模型文件的示例：

connection: "@{CONNECTION_NAME}"

include: "/views/*.view.lkml"
include: "/explores/*.explore.lkml"
include: "/dashboards/*.dashboard.lookml"

datagroup: nightly {
  sql_trigger: SELECT TIMEZONE('US/Pacific',GETDATE())::DATE;;
}

创建 LookML 信息中心文件

若要添加到 Looker Marketplace 中，每个组成块都必须至少包含三个可提供有意义、有帮助的分析的 LookML 信息中心。信息中心应美观、实用且全面，且不得包含任何模糊不清的数据。

虽然 LookML 信息中心没有硬性设计要求，但 Looker 建议遵循以下一般设计最佳实践：

  • 整个信息中心内一致的调色板
  • 至少 7 个功能块
  • 至少包含三种不同的可视化图表类型（例如，单个值、条形图和折线图）

在为区块开发信息中心时，不支持自定义可视化图表。请改用 Looker 的原生可视化图表类型。

如需详细了解如何自定义 LookML 信息中心和 LookML 信息中心中的可视化图表，请分别参阅信息中心参数和信息中心元素参数文档页面。如需查看 LookML 信息中心文件示例，请参阅 Redshift 管理控制台中的 Redshift 管理 LookML 信息中心文件。

创建 marketplace.json 文件

创建 marketplace.json 文件，以提供有关商品详情应如何在 Marketplace 中显示的信息。Looker Marketplace 中的每个版块都必须提供这些额外信息，以帮助用户选择最符合其需求的版块。您的 marketplace.json 文件应包含：

  • 购物平台 label、category_label 和 branding 字段
  • 用户需要填写的 LookML 常量列表，以填充模型 LookML（例如连接名称）

下面是 Google BigQuery 性能块的 marketplace.json 文件示例：

{
  "label": "Google BigQuery Performance",
  "category_label": "Models",
  "branding": {
    "image_uri": "https://marketplace-api.looker.com/block-icons/google-cloud.png",
    "tagline": "This Block provides a comprehensive overview of all cost and performance data for one or multiple BigQuery projects, enabling users to effectively monitor BigQuery usage down to a per user level. It can be used to set up alerts to long running or high cost queries."
  },

  "constants": {
    "CONNECTION_NAME": {
      "label": "Connection Name",
      "value_constraint": "connection"
    },
    "SCHEMA_NAME": {
      "label": "Schema Name"
    },
    "AUDIT_LOG_EXPORT_TABLE_NAME": {
      "label": "Audit Log Export Table Name",
      "description": "The table name of your BigQuery Optimization data (typically cloudaudit_googleapis_com_data_access_*)."
    }
  },
  "models": [
    {
      "name": "block_bigquery_optimization_v2",
      "connection_constant": "CONNECTION_NAME"
    }
  ]
}

以下屏幕截图显示了此 marketplace.json 文件将生成的购物平台商品详情。

Marketplace 商品详情示例。

  • "label" 字段用于控制块的标题。在本示例中，此维度为 Google BigQuery 性能。
  • "tagline" 字段用于控制购物平台商品详情的第一个段落。
  • "image_uri" 字段用于控制购物平台商品详情左上角显示的图片。在此示例中，此图标为 Google Cloud 徽标。
  • "constants" 字段会提示用户在安装过程中在 Marketplace 界面中填充常量。在此示例中，marketplace.json 文件中列出了三个常量（CONNECTION_NAME、SCHEMA_NAME 和 AUDIT_LOG_EXPORT_TABLE_NAME），因此系统会提示用户在安装前为这三个字段指定值。

创建 LICENSE 文件

所有 Looker 块都必须采用 MIT 开源许可。将此许可中的文本添加到名为 LICENSE 的文件中。如需查看许可文件示例，请参阅 Redshift 管理员块许可文件。

创建 README 文件

README 文件应包含实现该块的所有说明，并应明确指出需要进行任何自定义的位置，例如自动生成的清单文件](#the_autogenerated_manifest_file) 或优化文件。如需查看 README 文件示例，请参阅 Redshift 管理员块 README 文件。

关于 README 文件，需要注意以下事项：

  • 用户需要哪些数据源？他们需要付费订阅吗？
  • 数据库用户应具有哪些权限？
  • 需要哪些 Looker 连接设置？
  • 这些块字段名称是否与用户数据集中的字段名称一致？如果没有，用户应该更改哪些设置？

自动生成的文件

当用户安装您的模块时，其 Looker 实例会创建一个新的 Looker 项目，并将您项目的文件作为只读文件。它还会为您的用户自动生成以下文件：

  • 包含购物平台商品详情信息的只读 marketplace_lock.lkml 文件
  • 引用 marketplace_lock.lkml 中的商品详情清单的清单文件
  • 一个 refinements.lkml 文件，其中包含您的版块中的所有视图和探索
  • 一个只读模型文件，其中包含块中的模型文件和 refinements.lkml 文件

从 Looker Marketplace 安装您的块的用户可以使用 refinements.lkml 文件来优化您的 LookML，甚至可以添加新的 LookML 文件。如需详细了解用户如何自定义您的版块，请参阅自定义 Looker Marketplace 版块文档页面。

自动生成的清单文件

借助自动生成的清单文件，安装您代码块的用户可以设置连接名称等变量。您可以在自动生成的清单文件中修改版块清单文件中定义的 LookML 常量，也可以让用户在版块下载界面中进行设置。

优化文件

借助自动生成的 refinements.lkml 文件，安装您版块的用户可以优化为您的版块定义的视图和探索。下载您的模块的用户会在此处进行大部分 LookML 自定义，以适应其使用情形。

以下是一个自动生成的 refinements.lkml 文件示例：

include: "//ga360-v2/**/*.view.lkml"
include: "//ga360-v2/**/*.explore.lkml"

\# Use LookML refinements to refine views and explores that are defined in the remote project.
\# Learn more at: https://docs.looker.com/data-modeling/learning-lookml/refinements
\#
\#
\# For example we could add a new dimension to a view:
\#     view: +flights {
\#       dimension: air_carrier {
\#         type: string
\#         sql: ${TABLE}.air_carrier ;;
\#       }
\#     }
\#
\# Or apply a label to an explore:
\#     explore: +aircraft {
\#       label: "Aircraft Simplified"
\#     }
\#

使屏幕截图项目可访问

将您的块 LookML 托管在公开访问的 GitHub 代码库中。

所有 Looker 块都必须采用 MIT 开源许可，并且许可文本必须包含在代码库的 LICENSE 文件中。

提交屏蔽内容以供审核

当您的块准备好提交后，请按照向 Looker Marketplace 提交内容中的说明为您的块创建证明文件，将您的块提交给 Looker 团队以供审核，然后将您的块发布到 Looker Marketplace。