透過行動中心分享資料

除了將內容傳送至 Looker 內建目的地,您也可以使用「動作」(也稱為「整合」),將內容傳送至透過動作中樞伺服器與 Looker 整合的第三方服務。

本頁面將逐步說明如何建構自訂動作,並要求將動作新增至 Looker 動作中心 新增至您自己的私人動作中心伺服器。本頁面也說明如何啟動本機動作中心伺服器,測試自訂動作或執行私人動作中心伺服器。

如要開始使用動作,可以採取下列任一做法:

將動作新增至動作中心後,Looker 管理員可以啟用動作,以便將 Looker 內容傳送至這些服務

如要透過 Looker Action Hub 使用 Looker 的整合功能,並代管自己的私人或自訂動作,也可以設定多個動作中心。每個動作中心的操作都會顯示在「管理」面板的「動作」頁面上。

Looker Action Hub

Looker 會代管並提供 Looker Action Hub,這是一個實作 Looker Action API 的無狀態伺服器,並公開熱門動作。使用者透過動作傳送的任何資料,都會在 Looker 動作中心伺服器上暫時處理,而不是在 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 Action Hub 必須向 Looker 執行個體提出要求。

串流動作可讓動作使用傳回「所有結果」的查詢。啟用 OAuth 的動作會透過 OAuth 2.0 流程,使用個別使用者的驗證。OAuth 動作必須將使用者憑證儲存在來源 Looker 執行個體中,因為 Looker 動作中心是無狀態的多租戶,不會儲存任何類型的使用者專屬憑證。

從 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 Action Hub 前,於 Looker 執行個體中即時產生。因此,Looker Action Hub 必須能夠將 <host_looker_url> 解析為 IP 位址,並向 Looker 執行個體所在的網路提出要求。

Looker Action Hub 具有靜態輸出 IP 位址,要求一律會來自這些位址:35.153.89.114104.196.138.16335.169.42.87。如果 Looker 代管例項的管理員已啟用 IP 許可清單,就必須新增這些 IP 位址,才能使用支援串流結果或使用 OAuth 的任何動作。

客戶代管執行個體的注意事項

如要使用 Looker 整合功能,Looker Action Hub 必須能與 Looker 執行個體通訊,並符合 Looker Action Hub 需求。基於各種原因,客戶代管的 Looker 執行個體不一定能做到這一點。如果 Looker Action Hub 和 Looker 執行個體無法雙向通訊,Looker Action Hub 可能會出現非預期或不良行為,例如查詢停止回應或無法使用動作。

為解決 Looker Action Hub 無法與 Looker 執行個體通訊的潛在問題,Looker 管理員可以實作本頁稍後顯示的其中一種解決方案。適用的解決方案或解決方案組合取決於 Looker 執行個體的架構:

  • 如果 Looker Action Hub 無法解析客戶代管的執行個體 (也就是 Looker Action Hub 無法接收來自 Looker 執行個體的要求),Looker 管理員可以聯絡 Google Cloud 銷售專員,啟用 public_host_url 授權功能。該授權功能會顯示--public-host-url啟動選項,讓管理員指定可解析的 <public_host_url> 主機名稱,與執行個體 <host_looker_url> 不同。public_host_url 會覆寫特定 Looker Action Hub 回呼網址的主機名稱,並透過以 public_host_url 做為可公開解析名稱的反向 Proxy,將這些回呼網址路由傳送出去。這個反向 Proxy 只會接受來自 Looker Action Hub 靜態輸出 IP 位址的要求。使用這個方法的 Looker 管理員必須將輸出 IP 位址新增至允許清單,Looker Action Hub 會從這些 IP 位址向 Looker 執行個體提出要求:35.153.89.114104.196.138.16335.169.42.87

  • 如果 Looker 執行個體可以解析客戶代管的執行個體網址,但 Looker Action Hub 無法將要求傳送至 Looker 執行個體,使用者可能就無法設定或使用支援串流結果或使用 OAuth 的動作。如要解決這個問題,Looker 管理員必須將 Looker Action Hub 向 Looker 執行個體提出要求的輸出 IP 位址 (35.153.89.114104.196.138.16335.169.42.87) 加入允許清單。

  • 如果上述任一解決方案都不適合 Looker 執行個體架構,Looker 管理員可以部署客戶代管的動作中樞,以處理所有動作,或只處理支援串流結果或使用 OAuth 的動作

  • 如要部署客戶代管的動作中心,請務必將 JAR 檔案代管在公開伺服器上,這樣 Looker 動作中心才能與其通訊。不過,我們不建議使用這個解決方案。

此外,如果執行個體使用的 SSL 憑證是由不在根憑證清單中的憑證授權單位 (CA) 核發,客戶代管的 Looker 執行個體可能無法使用 OAuth 和串流動作。

建構自訂動作

本節說明如何使用 Looker Action Hub 原始碼,編寫及測試自訂動作。如要查看可運作的程式碼範例,請前往 GitHub 的 looker-open-source/actions 存放區查看現有動作。

您可以透過下列方式建立自訂動作:

  1. 設定開發存放區
  2. 撰寫動作
  3. 測試動作
  4. 在 Looker Action Hub 或您自己的私人動作中心伺服器中發布及啟用動作

與任何動作一樣,您可能需要先使用特定參數設定 LookML 模型,才能使用動作傳送資料。

設定開發存放區

Looker 動作中心是以 TypeScript 編寫的 Node.js 伺服器,是現代 JavaScript 的一小層,可新增型別資訊,協助偵測程式設計錯誤。如果您熟悉 JavaScript,應該會覺得 TypeScript 語言的大部分內容都很熟悉。

如要執行 Looker 動作中心,必須安裝下列軟體:

  • 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. 開始在目錄中填入執行動作所需的檔案。如需檔案結構範例,請參閱 actions GitHub 存放區

Looker 建議您也新增下列項目:

  • README,說明動作的驗證目的和方式
  • PNG 圖示,用於顯示在 Looker 動作中心 (或 Looker 執行個體上的私人動作中心) 和 Looker 資料傳送視窗中
  • 要在動作程式碼上執行的任何測試檔案,這與測試動作不同

撰寫動作

Looker Action Hub 伺服器的設計要求是完全無狀態,因此不允許在動作應用程式或服務中儲存任何資訊。執行動作所需的任何資訊,都必須在動作檔案的要求呼叫中提供。

動作檔案的確切內容會因服務、動作運作的類型或層級,以及需要指定的資料或視覺化格式而異。您也可以為 OAuth 2.0 授權流程設定動作

動作檔案是以 /execute API 方法為基礎。每當使用者在 Looker 中執行動作,系統就會將 DataActionRequest 傳遞至 Looker API 要求。DataActionRequest 包含執行動作所需的所有資料和中繼資料。您也可以使用 /form 方法,在使用者執行動作前收集額外資訊。使用者選取「傳送」或「排定時間」彈出式視窗,將動作設為資料傳送目的地時,系統會顯示您在 /form 中指定的欄位。

撰寫動作檔案時,請在動作定義中加入至少下列標示為「必要」的參數:

參數 必填 說明 資料類型
name 動作的專屬名稱。這個值在 Looker 動作中心的所有動作中都不得重複。 字串
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 動作會顯示在「管理」面板「動作中心」清單中的最低 Looker 版本。 字串

如需參考範例,請前往 GitHub 查看 Looker Action Hub 動作。

支援的動作類型

如動作的 supportedActionTypes 參數所指定,Looker 支援三種動作:查詢、儲存格和資訊主頁。

  • 查詢層級動作:這類動作會傳送整個查詢。舉例來說,「區隔動作」是查詢層級的動作。
  • 儲存格層級動作:儲存格層級動作會傳送資料表中特定儲存格的值。這類動作與資料動作不同,後者可使用 action 參數為維度或指標定義。如要傳送表格中特定儲存格的資訊,Looker 會使用標記將動作對應至相應的儲存格。動作需要在 requiredFields 中指定支援的標記。如要對應動作和欄位,LookML 中的欄位必須使用 LookML tags 參數指定對應的標記。 舉例來說,Twilio Message 動作會使用 phone 標記,因此 LookML 開發人員可以控管 Twilio 動作顯示的電話號碼欄位。
  • 資訊主頁層級動作:資訊主頁層級動作支援傳送資訊主頁圖片。 舉例來說,SendGrid 動作會透過電子郵件傳送資訊主頁圖片。

在自訂動作中加入使用者屬性

如果是自訂動作,您可以在動作檔案的 params 參數中新增使用者屬性。如果參數為必填,則除了 send_to_integration 權限,每位使用者都必須在使用者帳戶或所屬使用者群組中定義這個屬性的值,才能在傳送或排定內容時,將動作視為目的地選項。

如要將使用者屬性新增至動作,請按照下列步驟操作:

  1. 如果對應 user_attribute_param 的使用者屬性不存在,Looker 管理員可能需要建立該屬性
  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 表示使用者必須為該使用者屬性定義非空值和有效值,才能在傳送資料時看到動作,而 sensitive: true 表示使用者屬性經過加密,輸入後不會顯示在 Looker UI 中。您可以指定多個使用者屬性子參數。

  1. 將更新部署至動作中心伺服器。
    • 如果新增動作,Looker 管理員必須在「管理」面板的「動作」頁面中,按一下動作旁的「啟用」按鈕,才能啟用動作。
    • 如要更新現有動作,請按一下「重新整理」按鈕,重新整理動作清單。接著按一下「設定」按鈕。
  2. 在動作設定/啟用頁面上,Looker 管理員必須設定動作的表單欄位,方法是按一下適當欄位右側的使用者屬性圖示 ,然後選取所需的使用者屬性,從使用者屬性中擷取資訊。

儲存格層級動作中的 requiredField 參數

如要執行儲存格層級的動作,您可以設定模型的 LookML 欄位,在動作檔案的 requiredFields 參數中指定動作支援的標記,將資料傳送至該動作目的地。

參數 必填 說明 資料類型
tag 如有這個標記,則會與具有這個標記的欄位相符。 字串
any_tag 如有這個欄位,則會取代 tag,並比對含有任何所提供標記的欄位。 字串
all_tags 如有這個欄位,則會取代 tag,並比對具有所有提供標記的欄位。 字串

支援的資料格式

DataActionRequest 類別會定義動作可使用的資料傳送格式。如果是查詢層級動作,要求會包含附件,附件格式不限。動作可以指定一或多個 supportedFormats,也可以指定所有可能的格式,讓使用者選擇格式。如果是儲存格層級動作,儲存格的值會顯示在 DataActionRequest

設定 OAuth 的動作

您可以設定動作,讓使用者透過 OAuth 驗證動作。即使 Looker 動作中心必須保持無狀態,您仍可透過 Looker Action API 的表單要求強制執行狀態。

Looker 動作 OAuth 流程

如要設定布林值,指出使用者需要哪些 OAuth 方法才能驗證動作,您可以擴充 Looker 動作中心中的 OAuthAction,而不是 Hub.Action。對於每個啟用 OAuth 或狀態的動作,Looker 會儲存每個使用者和每個動作的狀態,因此每個動作和使用者組合都有獨立的 OAuth 事件。

建立動作的流程通常會先發出 /form 要求,再發出 /execute 要求。如果是 OAuth,/form 要求應具備判斷使用者是否已在目標服務中完成驗證的方法。如果使用者已通過驗證,動作應根據 /execute 要求傳回正常的 /form。如果使用者未通過驗證,動作會傳回可初始化 OAuth 流程的連結。

使用 OAuth 網址儲存狀態

Looker 會將 HTTP POST 要求連同空白主體傳送至 ActionList 端點。如果動作在其定義中傳回 uses_oauth: true,則動作會在 Looker 的每個 /form 要求中收到一次性使用的 state_urlstate_url 是特殊的一次性網址,可為特定動作設定使用者狀態。

如果使用者未透過端點完成驗證,傳回的 /form 應包含 form_field (類型為 oauth_link),該 form_field 會前往動作的 /oauth 端點。state_url 應加密並儲存為傳回的 oauth_url 中的 state 參數。例如:

{
        "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 端點會在 OAuth 動作的 oauthUrl(...) 方法中建構重新導向,如 Dropbox OauthUrl 所示。

含有該加密 state_urlstate 參數應傳遞至 Looker 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. 新增您在編寫動作時使用的任何 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 等雲端平台,如下列範例所示。或者,您也可以使用任何符合上述規定的平台。

設定本機動作中心伺服器

在本範例中,我們會採用在 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,確認動作中心正在運作。如果忘記公開網址,可以在指令列中執行下列指令:

    heroku info -s | grep web_url
    

    Heroku 會傳回公開網址。例如:https://my-heroku-action-server-1234.herokuapp.com

  4. 在指令列中,設定動作中心基準網址:

    heroku config:set ACTION_HUB_BASE_URL="https://my-heroku-action-server-1234.herokuapp.com"
    
  5. 設定動作中心標籤:

    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. 使用密鑰設定動作中心密鑰:

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"
    

    客戶代管的部署作業可能需要設定其他環境變數,本文未列出這些變數。

  8. 如要在本機 Looker 執行個體中新增動作,請依序前往「管理」 >「動作」

    • 在動作清單底部,按一下「新增動作中心」
    • 輸入動作中心網址,並視需要輸入密鑰
    • 在 Looker 的「管理」選單中,找到「動作」清單中的動作。
    • 按一下「啟用」

如果動作需要從 Looker 傳遞特定類型的資料,請務必設定所有模型,加入適當的 tags 參數。

現在可以測試動作了!

測試資訊主頁層級和查詢層級的動作

在 Looker 執行個體中,視需要使用標記設定 LookML 模型。建立並儲存 Look。在已儲存的 Look 中,按一下右上方的選單,然後選取「傳送」,並將動作設為目的地。如有表單要傳送,Looker 會在「已傳送」視窗中顯示表單。

按一下「傳送測試」即可傳送資料。動作狀態會顯示在「管理」面板的「排程器記錄」中。如果動作發生錯誤,系統會在「管理」面板中顯示錯誤,並將含有錯誤訊息的電子郵件傳送給執行動作的使用者。

測試儲存格層級動作

使用動作的適當標記設定 LookML 欄位。在 Looker 執行個體中,執行包含該欄位的查詢。在資料表中找出該欄位。按一下儲存格中的「…」,然後從下拉式選單中選取「傳送」。如果收到錯誤訊息,請修正錯誤,然後完整重新整理資料表。

發布及啟用自訂動作

自訂動作有兩種發布選項:

發布動作後,您可以在「管理」面板的「動作」頁面啟用動作

發布至 Looker Action Hub

這種做法最簡單,適用於您想開放給所有 Looker 使用者的任何動作。

測試完動作後,即可將 PR 提交至 GitHub 的 looker-open-source/actions 存放區。

  1. 輸入下列指令:

    git push <your fork> <your development branch>
    
  2. looker-open-source/actions 存放區為目標,建立提取要求。

  3. 填寫 Looker Marketplace 和動作中心提交表單。如要進一步瞭解表單規定,請參閱「將內容提交至 Looker Marketplace」。

    Looker 會審查您的動作代碼。我們保留拒絕 PR 的權利,但可以協助你解決任何問題,並提供改善建議。接著,我們會將程式碼合併至 looker-open-source/actions 存放區,並部署至 actions.looker.com。程式碼部署完成後,所有 Looker 客戶都能使用。

  4. 在 Looker 執行個體中啟用動作,這樣動作就會顯示為資料傳送的選項。

發布至私人動作中心伺服器

如果您有專為貴公司或用途設計的私有自訂動作,請不要將動作新增至 looker-open-source/actions 存放區。請改用與測試動作時相同的 Node.js 架構,建立私人動作中心。

您可以在自己的基礎架構上設定內部動作中心伺服器,也可以使用雲端式應用程式平台 (我們的範例使用 Heroku)。部署前,別忘了將 Looker Action Hub 分支到私人動作中心伺服器。

設定 LookML 模型以搭配動作使用

無論是自訂動作或 Looker 動作中心提供的動作,您都必須在 LookML 模型中使用 tags 參數,找出相關資料欄位。「管理」面板的「動作」頁面會提供服務所需的代碼資訊 (如有)。

舉例來說,Twilio Send Message 整合服務會將訊息傳送至電話號碼清單。在「管理」面板的「動作」頁面中,整合功能會顯示「動作可搭配標記 phone 的欄位查詢使用」的副文字。

也就是說,Twilio Send Message 服務需要包含電話號碼欄位的查詢,並使用 tags 參數來識別查詢中包含電話號碼的欄位。如要在 LookML 中識別電話號碼欄位,請為該欄位指定 tags: ["phone"]。電話號碼欄位的 LookML 可能如下所示:

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

如果整合不需要代碼,管理面板的「動作」頁面會顯示「動作可搭配任何查詢使用」的副文字。

請務必使用 tags 參數,在 LookML 模型中找出所有必填欄位,讓使用者能透過這項服務傳送資料。

後續步驟

瞭解如何將Look 或探索資訊主頁的內容傳送至整合式服務。