通过 Action Hub 分享数据

除了向 Looker 的内置目标位置分发内容之外,您还可以使用操作(也称为集成)将内容传送到通过操作中心服务器与 Looker 集成的第三方服务。

本页将向您介绍构建自定义操作的选项,您可以请求添加到 Looker Action Hub 添加到您自己的 Private Action Hub 服务器。本页面还介绍了如何启动本地 Action hub 服务器以测试自定义操作或运行私人 Action Hub 服务器。

若要开始使用操作,您可以执行以下任一操作:

将操作添加到操作中心后,Looker 管理员可以enable该操作,以用于向这些服务提供 Looker 内容

如果您想通过 Looker Action Hub 使用 Looker 的集成,还可以设置多个操作中心,同时托管您自己的私有操作或自定义操作。每个操作中心的操作都会显示在管理面板的操作页面上。

Looker 操作中心

Looker 托管并提供 Looker Action Hub,这是一种无状态服务器,可实现 Looker 的 Action API 并提供常用操作。您的用户使用操作发送的任何数据都将在 Looker Action Hub 服务器上临时处理,而不是在您的 Looker 实例中处理。

Looker 已与多项服务集成。请参阅管理员设置 - 操作文档页面,了解如何启用这些现有服务。

Looker Action Hub 要求

Looker Action Hub 必须能够通过以下方式发送和接收 API 请求:

如果您的 Looker 部署无法满足这些请求,或者您的 Looker 实例启用了 IP 许可名单功能,请考虑设置本地操作中心服务器,以便提供专用 Looker 集成自定义操作。客户托管的实例的管理员还可以专门为 OAuth 和流式操作部署本地操作服务器

从 Looker 实例发送到 Looker Action Hub 网络的请求

actions.looker.com 的请求会解析为动态 IP 地址。来自 Looker 实例的传出请求必须能够访问以下端点:

actions.looker.com/
actions.looker.com/actions/<name>/execute
actions.looker.com/actions/<name>/form

其中 name 是操作的程序化名称

从 Looker 用户浏览器发送到 Looker Action Hub 网络的请求

Looker 用户的浏览器必须能够向以下 Looker Action Hub 端点(适用于 OAuth)发出请求:

actions.looker.com/actions/<name>/oauth

其中 name 是操作的程序化名称

从 Looker Action Hub 网络发送到 Looker 实例的请求

对于支持流式结果或使用 OAuth 的操作,Looker 操作中心必须向 Looker 实例发出请求。

流式操作使该操作能够使用提供所有结果的查询。启用 OAuth 的操作通过 OAuth 2.0 流程使用每位用户的身份验证。OAuth 操作必须将用户凭据存储在其来源 Looker 实例中,因为 Looker Action Hub 是无状态的多租户形式,不会存储任何类型的用户专用凭据。

从 Looker Action Hub 发送到 Looker 实例的请求会采用以下形式:

GET <host_looker_url>/downloads/<random_40_char_token>
POST <host_looker_url>/action_hub_state/<random_40_char_token>

这些网址是在 Looker 实例中生成的位置,然后才会发送到 Looker Action Hub。因此,Looker Action Hub 需要能够将 <host_looker_url> 解析为 IP 地址,并能够向 Looker 实例所在的网络发出请求。

Looker Action Hub 具有静态出站 IP 地址,请求始终来自这些地址:35.153.89.114104.196.138.16335.169.42.87。已启用 IP 许可名单的 Looker 托管实例的管理员必须添加这些 IP 地址,才能执行任何支持流式结果或使用 OAuth 的操作。

客户托管的实例的注意事项

如需使用 Looker 集成,Looker Action Hub 必须能够与 Looker 实例通信并满足这些要求。由于各种原因,客户托管的 Looker 实例有时无法做到这一点。如果 Looker Action Hub 与 Looker 实例之间无法进行双向通信,则 Looker Action Hub 可能会出现意外或不良行为,例如查询挂起或无法执行操作。

为了解决 Looker Action Hub 无法与 Looker 实例通信的潜在问题,Looker 管理员可以实施本页下文所示的解决方案之一。合适的解决方案或解决方案组合将取决于 Looker 实例的架构:

  • 如果客户托管的实例无法通过 Looker Action Hub 进行解析,也就是说,Looker 操作中心无法接收来自 Looker 实例的请求,那么 Looker 管理员可以与 Google Cloud 销售专家联系,以启用 public_host_url 许可功能。该许可功能显示了 --public-host-url 启动选项,管理员可使用该选项指定不同于实例 <host_looker_url> 的可解析 <public_host_url> 主机名。public_host_url 会替换某些特定 Looker Action Hub 回调网址的主机名,并通过将 public_host_url 作为可公开解析名称的反向代理来路由这些回调网址。此反向代理仅接受来自 Looker Action Hub 的静态出站流量 IP 地址的请求;使用此方法的 Looker 管理员必须将 Looker Action Hub 从中向 Looker 实例发出请求的出站流量 IP 地址添加到许可名单:35.153.89.114104.196.138.16335.169.42.87

  • 如果客户托管的实例网址可以由 Looker 实例解析,但 Looker Action Hub 无法向 Looker 实例发送请求,则用户可能无法配置或使用支持流式结果或使用 OAuth 的操作。为解决此问题,Looker 管理员必须将下列出站流量 IP 地址(35.153.89.114104.196.138.16335.169.42.87)添加到 Looker Action Hub 的许可名单中。

  • 如果上述解决方案都不适合 Looker 实例架构,Looker 管理员可以为所有操作或仅针对支持流式结果或使用 OAuth 的操作部署客户托管的操作中心

  • 如需部署客户托管的 Action Hub,您必须确保 JAR 文件托管在公共服务器上,以便 Looker Action Hub 能够与其通信。但我们不推荐此解决方案。

此外,如果客户托管的 Looker 实例使用的 SSL 证书由证书授权机构 (CA) 颁发,而该证书授权机构不在此根证书列表中,则 OAuth 和流式操作可能无法在该实例上使用。

构建自定义操作

本部分介绍了使用 Looker Action Hub 源代码编写和测试自定义操作时要遵循的步骤。如需查看功能代码示例,请查看 GitHub 中 looker-open-source/actions 代码库中的现有操作。

您可以通过以下方式创建自定义操作:

  1. 设置开发代码库
  2. 编写操作
  3. 测试您的 Action
  4. 在 Looker Action Hub 中或您自己的私有 Action Hub 服务器上发布和启用您的 Action

与任何操作一样,您可能需要先使用特定参数配置 LookML 模型,然后才能使用相应操作传送数据。

设置开发代码库

Looker Action Hub 是一个使用 TypeScript 编写的 Node.js 服务器,它是现代 JavaScript 之上的一个小层,可添加类型信息以帮助发现编程错误。如果您熟悉 JavaScript,应该熟悉大部分 TypeScript 语言。

运行 Looker Action Hub 需要以下软件:

  • Node.js
  • Node Version Manager (NVM - 用于选择正确的 Node.js 版本)
  • Yarn(管理依赖项)

安装所需的软件后,您就可以设置开发环境了。我们的以下示例使用 Git。

  1. 在本地克隆 looker-open-source/actions 代码库:

    git clone git@github.com:looker-open-source/actions.git
    
  2. actions/src/actions 目录中创建一个使用您的操作名称的目录。例如:

    mkdir actions/src/actions/my_action
    
  3. 开始使用执行操作所需的文件填充目录。如需查看示例文件结构,请参阅操作 GitHub 代码库

Looker 建议您同时添加以下内容:

  • 一份 README 文件,用于说明您的 Action 的身份验证目的和方式
  • PNG 图标,会显示在 Looker Action Hub(或 Looker 实例上的私有操作中心)和 Looker 数据传送窗口中
  • 您想在操作代码上运行的测试的任何文件 - 这与测试您的操作不同

编写操作

Looker Action Hub 服务器的设计要求是它完全无状态,因此不允许在 Action 应用或服务中存储任何信息。执行操作文件的请求调用中必须提供执行操作所需的全部信息。

操作文件的确切内容将根据服务、操作操作的类型或级别,以及需要指定的数据或可视化格式而有所不同。您也可以为 OAuth 2.0 授权流程配置此操作。

操作文件基于 /execute API 方法。每当用户在 Looker 中执行操作时,系统都会向 Looker API 请求传递 DataActionRequestDataActionRequest 包含执行操作所需的所有数据和元数据。您也可以使用 /form 方法,该方法用于在用户执行操作之前收集更多信息。当用户选择将相应操作作为数据传输的目标位置时,您在 /form 中指定的字段会显示在发送安排弹出式窗口中。

编写 Action 文件时,请在操作定义中至少添加以下标记为必需的参数:

参数 需要 说明 数据类型
name 操作的唯一名称。此名称在 Looker Action Hub 中的所有操作中应该是唯一的。 字符串
url 此操作的 /execute 端点的绝对网址。 字符串
label 直观易懂的操作标签。 字符串
supportedActionTypes 操作支持的操作类型的列表。有效值为 "cell""query""dashboard" 字符串
formURL 此操作的 /form 端点的绝对网址。 字符串
description 操作的说明。 字符串
params 操作的 parameters 数组。以字符串格式为每个参数添加名称、标签和说明。这些字段显示在管理面板中操作的启用页面上。如需管理用户向操作目的地传送数据的方式,您可以指定一个用户属性,用户必须针对该属性定义值。 parameters
supportedFormats 操作支持的数据格式列表。有效值为 "txt""csv""inline_json""json""json_detail", "json_detail_lite_stream", "xlsx", "html", "wysiwyg_pdf", "assembled_pdf", and "wysiwyg_png". 字符串
supportedFormattings 操作支持的格式选项列表。有效值为 "formatted""unformatted" 字符串
supportedVisualizationFormattings 操作支持的可视化格式设置选项列表。有效值为 "apply""noapply" 字符串
iconName 表示操作的图标图片的数据 URI。 字符串
requiredFields 与此操作兼容的必填字段的说明列表。如果此列表中有多个条目,则操作需要多个字段。 RequiredField
supportedDownloadSettings 一个布尔值,用于确定是否向操作发送一次性下载网址以便于无限量流式传输数据。该参数由 usesStreaming 参数设置,该参数是一个 true/false 布尔值。如果此字段的值为 usesStreaming = true,则设为 supportedDownloadSettings = url。如果此字段的值为 usesStreaming = false,则设为 supportedDownloadSettings = push 布尔值
usesOAuth 一个布尔值,用于确定操作是否为 OAuth 操作。这将决定该操作是否会发送一次性链接,以便能够为特定用户为此操作设置 state 布尔值
usesStreaming 布尔值,用于确定操作是否支持流式查询结果。查看集成服务列表中的使用数据流(是/否)列。流式传输结果的操作可能需要配置本地操作中心服务器。如需了解详情,请参阅为使用 OAuth 或流式传输的操作设置本地操作中心页面,了解相关详情。 布尔值
minimumSupportedVersion 操作将显示在管理面板 Action Hub 列表中的最低 Looker 版本。 字符串

GitHub 上提供了 Looker Action Hub 操作示例以供参考。

支持的操作类型

Looker 支持三种类型的操作,具体在操作的 supportedActionTypes 参数中指定:查询、单元格和信息中心。

  • 查询级操作:该操作会发送整个查询。例如,细分操作就是查询级操作。
  • 单元格级操作:单元格级操作会发送数据表中一个特定单元格的值。此操作类型与数据操作不同,后者可以使用 action 参数为维度或测量定义。 如需从表格中的特定单元格发送信息,Looker 会使用标记将操作映射到相应的单元格。操作需要在 requiredFields 中指定支持的代码。如需映射操作和字段,LookML 中的字段需要使用 LookML tags 参数指定映射到哪些标记。例如,Twilio 消息操作使用 phone 标记,以便 LookML 开发者可以控制 Twilio 操作将会显示哪些手机号码字段。
  • 信息中心级操作:信息中心级操作支持发送信息中心的图片。例如,SendGrid 操作会通过电子邮件发送信息中心图片。

向自定义操作添加用户属性

对于自定义操作,您可以在操作文件的 params 参数中添加用户属性。如果该参数为必需参数,则除了 send_to_integration 权限之外,每位用户还必须在其用户帐号或自己所属的用户群组中为此属性定义一个值,才能在发送或安排内容时将操作显示为目标位置选项。

如需为操作添加用户属性,请执行以下操作:

  1. Looker 管理员可能需要创建与 user_attribute_param 对应的用户属性(如果相应用户属性尚不存在)。
  2. 为需要将内容传送到操作目标的用户或用户群组定义有效的用户属性值。(这些用户还必须具有 send_to_integration 权限。)
  3. params 参数表示 Looker 管理员必须在管理面板的操作列表中操作的启用页面上配置的表单字段。在操作文件的 params 参数中,添加以下代码:
  params = [{
    description: "A description of the param.",
    label: "A label for the param.",
    name: "action_param_name",
    user_attribute_name: "user_attribute_name",
    required: true,
    sensitive: true,
  }]

其中 user_attribute_name 是在管理面板用户部分的用户属性页面上的名称字段中定义的用户属性,required: true 表示用户必须为该用户属性定义非 null 的有效值,才能在提供数据时看到操作;sensitive: true 表示用户属性在输入后已加密,且永远不会显示在 Looker 界面中。您可以指定多个用户属性子参数。

  1. 将更新部署到操作中心服务器。
    • 如果您要添加新操作,则 Looker 管理员需要通过在管理面板中的操作页面上点击相应操作旁边的启用按钮来启用该操作。
    • 如果您要更新现有操作,请点击 Refresh 按钮以刷新操作列表。接下来,点击设置按钮。
  2. 在操作设置/启用页面上,Looker 管理员必须将操作的表单字段配置为从用户属性中提取信息,方法是点击相应字段右侧的用户属性图标 ,然后选择所需的用户属性。

单元格级操作中的 requiredField 个参数

对于单元格级别的操作,您可以配置模型的 LookML 字段以将数据传送到该操作目的地,只需在操作文件的 requiredFields 参数中指定您的操作支持的标记即可。

参数 需要 说明 数据类型
tag 如果存在,则与具有此标记的字段匹配。 字符串
any_tag 如果存在,会取代 tag 并匹配具有任何给定标记的字段。 字符串
all_tags 如果存在,会取代 tag 并匹配包含所有提供的标记的字段。 字符串

支持的数据格式

DataActionRequest 类定义了操作支持的数据传输格式。对于查询级别的操作,请求将包含可以采用多种格式的附件。该操作可以指定一个或多个 supportedFormats,也可以通过指定所有可能的格式让用户选择格式。对于单元格级操作,单元格的值将显示在 DataActionRequest 中。

为 OAuth 配置操作

您可以配置操作,以便用户使用 OAuth 进行身份验证以处理该操作。即使 Looker Action Hub 必须保持无状态,您也可以通过 Looker Action API 中的表单请求强制执行状态。

Looker 操作 OAuth 流程

对于 Looker Action Hub 中的操作,您可以扩展 OAuthAction(而非 Hub.Action)以设置一个布尔值,以指示需要哪些 OAuth 方法才能对用户进行身份验证。对于每个已启用 OAuth 或已启用状态的操作,Looker 会针对每个用户和每个操作存储一个状态,以确保每项操作和用户组合都具有独立的 OAuth 事件。

创建操作的流程通常涉及一个 /form 请求,后跟一个 /execute 请求。对于 OAuth,/form 请求应包含一个用于确定用户是否在目标服务中通过身份验证的方法。如果用户已经过身份验证,则操作应根据 /execute 请求的任何要求返回常规 /form。如果用户未经过身份验证,则操作会返回一个用于初始化 OAuth 流程的链接。

使用 OAuth 网址保存状态

Looker 会将正文为空的 HTTP POST 请求发送到 ActionList 端点。如果操作在其定义中返回 uses_oauth: true,则系统会在来自 Looker 的每个 /form 请求中向该操作发送一个一次性 state_urlstate_url 是一个特殊的一次性网址,用于设置用户对于指定操作的状态。

如果用户未通过端点身份验证,返回的 /form 应包含类型为 oauth_linkform_field,该 form_field 会转到操作的 /oauth 端点。应将 state_url 加密,并将其保存为 state 参数,并将其保存在返回的 oauth_url 中。例如:

{
        "name": "login",
        "type": "oauth_link",
        "label": "Log in",
        "description": "OAuth Link",
        "oauth_url": "ACTIONHUB_URL/actions/my_action/oauth?state=encrypted_state_url"
}

在此示例中,/oauth 端点会将用户重定向到身份验证服务器。/oauth 端点会在 oauthUrl(...) 方法中针对 OAuth 操作构造重定向,如 Dropbox OauthUrl 中所示。

包含该加密 state_urlstate 参数应传递到 Looker Action Hub。

使用 Action Hub 重定向 URI 保存状态

/oauth 端点中,系统还会为操作中心创建 redirect_uri,并将其传递给操作的 oauthUrl(...) 方法。此 redirect_uri 采用 /actions/src/actions/my_maction/oauth_redirect 格式,是身份验证返回结果时使用的端点。

此端点将调用 oauthFetchInfo(...) 方法,该方法应由 OauthAction 方法实现,以提取必要的信息,并尝试接收或保存从身份验证服务器收到的任何状态或 auth

state 会解密加密的 state_url,并使用它来将 state POST 回 Looker。当用户下次向相应操作发出请求时,系统会将新保存的状态发送到 Looker Action Hub。

将您的操作文件添加到 Looker Action Hub 代码库

写入操作文件后,请在 Looker Action Hub 代码库中执行以下操作:

  1. 将操作文件(例如 my_action.ts)添加到 actions/src/actions/index.ts

    import "./my_action/my_action.ts"
    
  2. 添加您在编写 Action 时使用的 Node.js 软件包要求。例如:

    yarn add aws-sdk
    yarn add express
    
  3. 安装 Looker Action Hub 服务器的 Node.js 依赖项。

    yarn install
    
  4. 运行您编写的所有测试。

yarn test

测试操作

如需进行完整测试,您可以托管一个私有操作中心服务器,针对 Looker 实例尝试执行您的操作。此服务器需要位于公共互联网中,并具有有效的 SSL 证书,并且必须能够发起和接收与 Looker 之间的连接或 HTTPS 请求。为此,您可以使用基于云的平台,如 Heroku,如以下示例所示。或者,您也可以使用满足上述要求的任何平台。

设置本地 Action Hub 服务器

在此示例中,我们将执行在 looker-open-source/actions/src/actions GitHub 代码库中开发的操作,并将代码提交到新的 Git 分支。我们建议您使用分支来处理功能,以便轻松跟踪代码,并根据需要通过 Looker 轻松创建 PR。

  1. 首先,请创建分支,然后暂存并提交您的工作。例如:

    git checkout -b my-branch-name
    git add file-names
    git commit -m commit-message
    
  2. 在此示例中,如需将分支推送到 Heroku,请在命令行中将 Heroku 作为远程选项来配置 Git 代码库:

    heroku login
    heroku create
    git push heroku
    
  3. Heroku 会返回公开网址,现在托管操作中心供您使用。请访问该网址或运行 heroku logs,以确认 Action Hub 正在运行。如果您忘记了公开网址,可以在命令行中运行以下命令:

    heroku info -s | grep web_url
    

    Heroku 会返回您的公开网址。例如:https://my-heroku-action-server-1234.herokuapp.com

  4. 在命令行中,设置您的 Action Hub 基准网址:

    heroku config:set ACTION_HUB_BASE_URL="https://my-heroku-action-server-1234.herokuapp.com"
    
  5. 设置 Action Hub 标签:

    heroku config:set ACTION_HUB_LABEL="Your Action Hub"
    
  6. Looker 使用授权令牌连接到 Action Hub。在命令行中生成令牌:

    heroku run yarn generate-api-key
    

    如果您未使用 Heroku(如此示例所示),请改用:

    yarn generate-api-key
    

    Heroku 会返回您的授权令牌。例如:Authorization: Token token="abcdefg123456789"

  7. 使用以下密钥设置 Action Hub 密钥:

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"
    

    客户托管的部署可能需要配置此处未记录的其他环境变量。

  8. 依次点击管理 > 操作,在本地 Looker 实例上添加您的操作。

    • 在操作列表底部,点击 Add Action Hub
    • 输入 Action Hub 网址密钥(可选)。
    • 在 Looker 管理菜单中的操作列表中找到您的操作。
    • 点击启用

如果您的操作需要从 Looker 传递特定类型的数据,请务必配置任何模型以包含适当的 tags 参数。

现在,您可以测试自己的 Action 了!

测试信息中心级和查询级操作

如有必要,在 Looker 实例中,使用标记配置 LookML 模型。创建并保存 Look。在已保存的 Look 中,点击右上角的菜单,然后选择发送,并以您的操作为目标位置。如果您有要提交的表单,Looker 会在 Sent(已发送)窗口中呈现该表单。

点击发送测试以传送数据。操作的状态将显示在管理面板的调度器历史记录中。如果您的操作遇到错误,错误会显示在管理面板中,Looker 会向发送相应操作的用户发送一封电子邮件,其中包含错误消息。

测试单元格级操作

为您的操作设置带有正确标记的 LookML 字段。在您的 Looker 实例中,运行包含该字段的查询。在数据表格中找到相应字段。点击单元格中的 ,然后从下拉菜单中选择。如果您收到错误,则需要在解决这些错误后彻底刷新数据表。

发布和启用自定义操作

自定义操作有两种发布选项:

发布操作后,您可以通过管理面板的操作页面启用该操作

发布到 Looker Action Hub

这种方法是最简单的,适用于您希望让所有 Looker 用户执行的任何操作。

在您的操作经过测试后,您可以向 GitHub 中的 looker-open-source/actions 代码库提交 PR。

  1. 输入以下命令:

    git push <your fork> <your development branch>
    
  2. 使用 looker-open-source/actions 代码库作为目标创建拉取请求。

  3. 填写 Looker Marketplace 和 Action Hub 提交表单。如需详细了解表单要求,请参阅向 Looker Marketplace 提交内容

    Looker 将审核您的操作代码。我们保留拒绝 PR 的权利,但可以帮助您解决出现的任何问题并提供改进建议。然后,我们将代码合并到 looker-open-source/actions 代码库中,并将其部署到 actions.looker.com。代码部署后,即可供所有 Looker 客户使用。

  4. 在 Looker 实例中启用操作,这样操作便会作为数据传输选项显示。

发布到 Private Action Hub 服务器

如果您有公司或用例专用的自定义操作,则应将操作添加到 looker-open-source/actions 代码库中。相反,请使用您用于测试 Action 的同一 Node.js 框架来创建私有操作中心。

您可以在自己的基础架构上设置内部操作中心服务器,也可以使用云端应用平台(我们以 Heroku 为例)。别忘了在部署前将 Looker Action Hub 分支到您的私有 Action Hub 服务器。

配置 LookML 模型以用于某个操作

对于自定义操作和可从 Looker Action Hub 获得的操作,您必须在 LookML 模型中使用 tags 参数来标识相关的数据字段。管理面板中的操作页面会提供服务所需代码(如果有)的相关信息。

例如,Twilio Send Message 集成会向一系列手机号码发送消息。在管理面板的操作页面上,集成会显示辅助文本“操作可用于具有标记为 phone 的字段的查询”。

这意味着 Twilio Send Message 服务要求一个包含手机号码字段的查询,并使用 tags 参数来标识查询中的哪个字段包含手机号码。您可以通过为手机号码字段指定 tags: ["phone"] 来标识 LookML 中的该字段。手机号码字段的 LookML 可能如下所示:

dimension: phone {
  tags: ["phone"]
  type: string
  sql: ${TABLE}.phone ;;
}

不需要代码的集成会在管理面板的操作页面上显示辅助文本“可以将操作用于任何查询”。

请务必使用 tags 参数标识 LookML 模型中的所有必填字段,以便用户使用该服务发送数据。

后续步骤

了解如何向集成服务提供 Look、探索信息中心的内容。