動作

用量

view: view_name {
  dimension: field_name {
    action:  {
      label: "Label to Appear in Action Menu"
      url: "https://example.com/posts"
      icon_url: "https://looker.com/favicon.ico"
      form_url: "https://example.com/ping/{{ value }}/form.json"
      param: {
        name: "name string"
        value: "value string"
      }
      form_param: {
        name:  "name string"
        type: textarea | string | select
        label:  "possibly-localized-string"
        option: {
          name:  "name string"
          label:  "possibly-localized-string"
        }
        required:  yes | no
        description:  "possibly-localized-string"
        default:  "string"
      }
      user_attribute_param: {
        user_attribute: user_attribute_name
        name: "name_for_json_payload"
      }
    }
  }
}
階層
view
欄位類型
action
可能的欄位類型
維度、評估指標

預設值
無

接受
各種參數

特別規則
  • Looker 伺服器必須能存取 form_url 的網址，且該網址必須使用 HTTPS 並具備有效憑證
  • 使用者瀏覽器必須能存取 icon_url 的網址

定義

action 參數會建立資料動作，讓使用者直接透過 Looker 跨工具執行欄位層級工作。舉例來說，可以觸發傳送電子郵件、在其他應用程式中設定值，或執行任何可設定接收伺服器處理的動作，前提是接收伺服器必須能夠接受 JSON POST。

您可以為維度或指標定義 action。在「探索」頁面、Look 或資訊主頁上，選取動作的欄位即可存取該動作。

定義 action 時，請使用下列參數指定所選行為：

參數 說明
label 指定動作名稱的字串，這個名稱會出現在使用者介面的動作選單中。
url 指定處理動作的網址字串。如果指定了「資料動作的網址許可清單」，就必須將這個 url 值加入許可清單。只有符合許可清單模式的網址，才能用於任何資料動作。如果沒有現有項目，則所有網址都可用於資料動作。
icon_url 這個字串會指定含有圖片檔案的網址，方便使用者一目瞭然這個連結會將他們導向何處。使用者瀏覽器必須能存取 icon_url 值。
form_url 這個字串會指定網址，該網址會傳回要向使用者顯示的表單；表單必須以 JSON 格式呈現，如本頁「使用 form_url 或 form_param 指定表單行為」一節所述。Looker 伺服器必須能存取 form_url，且 form_url 必須使用 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 參數，資料動作就不會包含表單。在這種情況下，當使用者從「動作」選單選取該動作時，動作會傳送要求。

選取不含表單的動作後，「動作」選單會在動作左側顯示圖示，指出動作狀態：

  • 畫面會顯示載入圖示，表示正在執行動作。

  • 畫面上會顯示勾號，表示動作已執行。

  • 畫面上會顯示帶圓圈的 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 Hub

如果您尚未設定伺服器來接收動作要求，或是想導入重複使用次數有限的用途，建議使用 action 參數。不過，您可以考慮改用 Looker Action Hub 提供的欄位層級動作。(請確認執行個體符合這些 Looker 動作中心規定)。

除了現有的 Looker 動作中心整合，您也可以按照動作中心說明文件頁面的指示，建立自己的自訂動作。