操作

用量

。
层次结构
view
字段类型
action
可能的字段类型
维度，衡量

默认值
无

接受
各种参数

特殊规则
  • form_url 的网址必须可供 Looker 服务器访问，并使用具有有效证书的 HTTPS
  • icon_url的网址必须可供用户的浏览器访问

定义

action 参数会创建一项数据操作，让用户可以直接从 Looker 在其他工具中执行字段级任务。例如，此操作可以导致发送电子邮件、在其他应用程序中设置值，或执行任何其他可供接收服务器配置的操作。接收服务器必须能够接受 JSON POST。

您可以为维度或衡量定义 action。然后，在“探索”页面、“样式”面板或信息中心，点击相应字段即可执行以下操作：

定义 action 时，您可以使用以下参数指定所需的行为：

参数 说明
label 一个字符串，用于指定在“操作”菜单中向用户显示的操作名称。
url 用于指定处理操作的网址的字符串。如果指定了 [数据操作的网址许可名单](/admin-options/settings/general#url_allowlist_for_data_actions)，您必须将此 url 值添加到许可名单。对于任何数据操作，只允许使用符合许可名单格式的网址。如果没有现有条目，则允许所有网址执行数据操作。
icon_url 一个字符串，用于指定包含图片文件的网址，以便用户可以一目了然地了解此链接会将他们定向到何处。icon_url 值必须可供用户的浏览器访问。
form_url 一个字符串，用于指定会返回表单给用户展示的网址；表单必须以 JSON 格式呈现，如本页中的使用 form_url 或 form_param 指定表单行为部分所述。form_url 必须可供 Looker 服务器访问，并使用具有有效证书的 HTTPS。
param 将值传递给接收服务器。
form_param 添加将针对此操作显示的表单输入。
user_attribute_param 将用户属性传递给接收服务器。如果您要对数据操作使用 user_attribute_param，必须将数据操作的 url 值添加到数据操作网址许可名单。

与数据操作类似，您还可以使用 Looker 操作中心提供的字段级操作来从特定单元格发送数据。请参阅本页中的考虑使用 Looker 操作中心部分，详细了解此选项。

使用 user_attribute_param 将用户属性传递给接收服务器

您可以使用 user_attribute_param 参数将用户属性发送到接收服务器。在每个 user_attribute_param 中，您需要指定以下子参数：

参数 类型 说明
user_attribute Looker ID Looker 中用户属性的名称
name 字符串 您希望 JSON 载荷中显示的属性名称

使用 param 将值传递到接收服务器

您可以使用 param 参数在 JSON 载荷中发送任意数据。在每个 param 中，您需要指定以下子参数：

参数 类型 说明
name 字符串 要传递给接收服务器的参数的名称
value 字符串 要传递给接收服务器的参数值

请勿在 param 参数中传递敏感数据或私密信息（例如用户凭据）。而应在“管理”设置中将用户凭据配置为用户属性，并在 user_attribute_param 参数中传递这些信息。

使用 form_url 或 form_param 指定表单行为

您可以创建一个表单，供 Looker 用户互动，然后在 JSON 载荷中提交他们的表单输入。如果您显示表单，表单将以叠加层的形式显示在触发了相应操作的页面（探索、样式、信息中心或旧版信息中心）上。您可以使用 form_url 或 form_param 参数来实现此目的。

如果您希望操作中心服务器定义表单布局，请使用 form_url 参数。form_url 应包含一个网址，该网址会返回表单的 JSON 表示形式，如本页后面部分所述。

如果您想直接在 LookML 中定义表单布局，请使用 form_param 参数。

表单选项

在这两种情况下，您都可用于定义表单：

选项 类型 说明
name 字符串 将在 JSON 载荷中显示的值的名称
type 输入类型 将向用户显示的表单字段类型：
select - 显示下拉列表
string - 显示单行输入字段
textarea - 显示多行文本输入框
label 字符串 将向用户显示的输入标签
description 字符串 根据需要向用户显示的字段的说明
required 布尔值 指定是否在用户提交表单前提供表单选项
default 字符串 表单字段的起始值（如果有）
option 字符串 如果您选择的 type 为 select，请在此处定义选择选项

如果您将 type 设置为 select，则可以使用 option 在下拉列表中指定项。每个 option 都包含以下详细信息：

选项 类型 说明
name 字符串 将出现在 JSON 载荷中的表单值名称
label 字符串 将向用户显示的选项的标签（可选）

使用不含表单的数据操作

如果您未在 action 定义中添加 form_url 或 form_param 参数，则数据操作将不包含表单。在这种情况下，当用户点击操作菜单中的操作时，操作就会发送请求。

点击没有表单的操作后，Actions 菜单会在操作左侧显示图标以指示其状态：

  • 系统会显示一个加载图标，表明该操作正在执行。
  • 系统会显示一个对勾标记，说明该操作已执行。
  • 系统会显示一个圆形 i，表示操作失败。

如果操作左侧未显示任何图标，则表示操作未触发。

服务器响应

成功的 HTTP 响应将被视为成功的操作。

服务器还可以将几个操作传回给 Looker。如果 webhook 请求使用 JSON 响应，Looker 会在响应中查找特殊的 looker 键。其他所有操作均会被忽略。例如，在：

{
  "my_apps_business_logic": "something",
  "looker": {
    "success": true,
    "refresh_query": true
  }
}

此处的 success 默认为 true，如果将 success 设置为 false，则会在 Looker 中指明请求失败。此外，refresh_query 默认为 false，将其设置为 true 将跳过缓存，重新运行当前的 Looker 查询。

对于随同传递的任何表单参数，您还可以使用验证错误进行响应：

{
  "looker": {
    "success": false,
    "validation_errors": {
      "body": "Body must be more than 10 characters long."
    }
  }
}

此处的 validation_errors 默认为 {}。它应该是一个 JSON 对象，其中键是表单参数的名称，而值是一个字符串，表示该参数的错误消息。

示例

如果您使用 form_url 参数（在此示例中为 Liquid 语法），则所有选项都必须以 JSON 对象形式返回。例如：

dimension: foo {
  action: {
    label: "Send a Thing"
    url: "https://example.com/ping/\{{ value \}}"
    form_url: "https://example.com/ping/\{{ value \}}/form.json"
  }
}

服务器应返回与 LookML 匹配的表单的 JSON 表示法：

[
  {
    "name": "title",
    "type": "select",
    "label": "desired label name",
    "description": "description text",
    "required": true,
    "default": "value string",
    "options": [
      {
        "name": "name string"
        "label": "desired label name"
      },
      {
        "name": "name string"
        "label": "desired label name"
      }
    ]
  },
  {
    "name": "title",
    "type": "textarea",
    "label": "desired label name",
    "description": "description text",
    "required": true,
    "default": "value string",
  }
]

如果您使用 form_param 参数，这些选项会用作 LookML 参数。例如：

form_param: {
  name: "title"
  type: select
  label: "desired label name"
  option: {
    name: "name string"
    label: "desired label name"
  }
  required: yes
  description: "description text"
  default: "value string"
}

考虑使用 Looker 操作中心

如果您尚未将服务器设置为接收操作请求，或者想要实现可重用性有限的用例，那么 action 参数是一个不错的选择。不过，建议您考虑改用 Looker 操作中心提供的字段级操作。（请确保您的实例符合相应要求。）

除了现有的 Looker Action Hub 集成之外，您还可以按照操作中心文档页面上的说明创建自己的自定义操作。