透過簽署嵌入功能,使用者無需個別登入 Looker,即可向使用者顯示私人嵌入的 Look 圖表、視覺化內容、探索、資訊主頁或 LookML 資訊主頁。而是透過您自己的應用程式驗證使用者身分。
如要使用已簽署的嵌入功能,請建立可在 iframe 中使用的特殊 Looker 網址。網址包含您要分享的資訊、系統中的使用者 ID,以及您要授予使用者的權限。接著,使用 Looker 提供的密鑰簽署網址。
如要公開嵌入,請參閱「公開分享、匯入及嵌入 Look」說明文件頁面的「使用 iframe
標記公開嵌入」一節。
如要在 Looker 執行個體上使用簽署的嵌入功能,Looker 管理員必須先在 Looker 管理面板中啟用簽署的嵌入功能,並建立嵌入密鑰。如需操作說明,請參閱「開始嵌入 - 啟用已簽署的嵌入」說明文件頁面。
適當的簽名嵌入代管服務
部分瀏覽器 (例如 Safari,或是安裝了會封鎖廣告或追蹤 Cookie 的擴充功能的瀏覽器) 預設會採用封鎖第三方 Cookie 的 Cookie 政策。啟用「無 Cookie 嵌入」功能後,封鎖第三方 Cookie 的瀏覽器就能在不同網域的嵌入式 iframe 中驗證使用者。無 Cookie 嵌入式驗證需要伺服器端設定。如需設定範例,請參閱「無 Cookie 嵌入」說明文件頁面。
如果未啟用「無 Cookie 嵌入」功能,Looker 會使用 Cookie 進行使用者驗證。在這種情況下,如果瀏覽器封鎖第三方 Cookie,就無法跨網域驗證內嵌 iframe (除非使用者修改瀏覽器的 Cookie 隱私權設定)。舉例來說,如要嵌入 https://mycompany.com
的資訊,請務必確認 Looker 共用相同網域,例如 https://analytics.mycompany.com
。在這種情況下,如果 Looker 代管您的執行個體,請與 Looker 支援團隊聯絡,設定必要的 DNS 設定,啟用自訂網域。這樣一來,Looker 就能與嵌入式應用程式共用相同網域,並使用所有瀏覽器預設接受的第一方 Cookie。
如果您有客戶代管的 Looker 執行個體,請確認將使用簽署嵌入的應用程式與 Looker 執行個體使用相同網域。
使用封閉式系統控管用戶瀏覽權限
在已簽署的嵌入設定中,Looker 使用者通常會向自己的客戶呈現資料,但這些客戶來自不同的公司或群組,彼此不應互相瞭解。在這種情況下,為保護顧客的私人資訊,我們強烈建議您將 Looker 設定為封閉式系統,也就是多租戶安裝。在封閉系統中,內容會受到隔離,避免不同群組的使用者互相瞭解。因此,建議您先啟用「封閉系統」選項,再授予外部使用者執行個體存取權。
詳情請參閱「設計及設定存取層級系統」和「嵌入式數據分析的安全防護最佳做法」說明文件頁面。
產生已簽署的嵌入網址
產生已簽署的嵌入網址有多種方式。你可以選擇下列任一方式:
您可以使用資訊主頁三點選單中的「取得嵌入網址」選項,或 Look 或探索的「探索動作」齒輪選單,產生已簽署的嵌入網址。
使用 Looker 嵌入 SDK。
編碼已簽署的嵌入網址。您必須編寫程式碼,才能正確建構網址,並使用私密金鑰正確編碼網址,以及產生其他安全性相關項目。您可以在 Looker 嵌入範例 GitHub 存放區中找到多個指令碼範例。以下各節將說明您需要提供給這些指令碼的資訊,以及如何建構已簽署的嵌入網址 (不使用指令碼)。
手動編碼已簽署的嵌入網址
如要編寫已簽署的嵌入網址,請先收集必要的 Looker 資訊,然後建立已簽署的嵌入網址。
收集必要的 Looker 資訊
如要開始建構網址,請先判斷需要納入的所有資訊。你需要:
嵌入網址
擷取要嵌入的 Look、探索、查詢視覺化或資訊主頁網址。然後移除網域,並在路徑前放置 /embed
,如下所示:
項目 | 一般網址模式 | 嵌入網址 |
---|---|---|
Look 圖表 | https://instance_name.looker.com/looks/4 |
/embed/looks/4 |
探索 | https://instance_name.looker.com/explore/my_model/my_explore |
/embed/explore/my_model/my_explore |
查詢圖表 | https://instance_name.looker.com/explore/my_model/my_explore?qid=1234567890abcdefghij12 在探索網址中,qid= 參數後方的 22 個英數字元即為 Query.client_id 。Query.client_id 值是代表查詢和視覺化設定的專屬字串。如要嵌入查詢圖表,請擷取查詢圖表的 Query.client_id 值,然後將 Query.client_id 複製到嵌入網址中。您可以使用 Looker Explore UI,透過支援的視覺化效果建立查詢,並從 qid= 參數複製 Query.client_id 值,也可以使用 Looker API (例如 Get Query 方法) 擷取 Query.client_id 。 |
/embed/query-visualization/Query.client_id |
使用者定義的資訊主頁 | https://instance_name.looker.com/dashboards/1 在資訊主頁網址中加入任何資訊主頁篩選器值,或隱藏篩選器值時加入 hide_filter 參數。 |
|
使用者定義的舊版資訊主頁 | https://instance_name.looker.com/dashboards-legacy/1 |
/embed/dashboards-legacy/1 |
LookML 資訊主頁 | https://instance_name.looker.com/dashboards/my_model::my_dashboard |
/embed/dashboards/my_model::my_dashboard |
舊版 LookML 資訊主頁 | https://instance_name.looker.com/dashboards-legacy/my_model::my_dashboard |
/embed/dashboards-legacy/my_model::my_dashboard |
內嵌內容一律會反映內容的正式版。在開發模式下所做的任何變更,如果影響內容且尚未部署至正式環境,就不會顯示在嵌入內容中。
權限
權限集會定義使用者或群組可執行的操作。您可以透過下列兩種方式套用權限:
- 模型專屬:這類權限只會套用至屬於相同角色的模型集。
- 執行個體範圍:這類權限適用於整個 Looker 執行個體。具備例項層級權限的嵌入使用者可以在整個 Looker 例項中執行特定功能,但無法存取不屬於其角色模型集的模型內容。
決定要授予使用者的權限。下表列出簽名嵌入功能的所有可用權限。簽署嵌入功能不支援下列清單以外的權限:
權限 | 取決於 | 類型 | 定義 |
---|---|---|---|
access_data |
無 | 特定型號 | 允許使用者存取資料 (查看 Looker、資訊主頁或探索時必須具備這項權限) |
see_lookml_dashboards |
access_data |
特定型號 | 允許使用者查看 LookML 資訊主頁 |
see_looks |
access_data |
特定型號 | 允許使用者查看外觀 |
see_user_dashboards |
see_looks |
特定型號 | 允許使用者查看使用者定義的資訊主頁,以及瀏覽嵌入內容中的資料夾 |
explore |
see_looks |
特定型號 | 允許使用者查看「探索」頁面 |
create_table_calculations |
explore |
整個執行個體 | 在「探索」中建立資料表計算時需要用到 |
create_custom_fields |
explore |
整個執行個體 | 在「探索」中建立自訂欄位時需要 |
can_create_forecast |
explore |
整個執行個體 | 允許使用者在視覺化圖表中建立或編輯預測。 |
save_content |
see_looks |
整個執行個體 | 允許使用者變更及儲存 Look 和資訊主頁 |
send_outgoing_webhook |
see_looks |
特定型號 | 允許使用者將 Looker 內容傳送排程設定為任意 Webhook |
send_to_s3 |
see_looks |
特定型號 | 允許使用者將 Looker 內容傳送排程設定至 Amazon S3 bucket |
send_to_sftp |
see_looks |
特定型號 | 允許使用者排定將 Looker 內容傳送至 SFTP 伺服器 |
schedule_look_emails |
see_looks |
特定型號 | :允許使用者將 Looker 內容傳送排程設定為傳送至自己的電子郵件地址 (如果設定了名為「email」的使用者屬性),或是傳送至符合允許電子郵件網域清單限制的電子郵件地址。允許具備 create_alerts 權限的使用者,將快訊通知傳送至電子郵件網域許可清單所設限制內的電子郵件地址。 |
schedule_external_look_emails |
schedule_look_emails |
特定型號 | 允許使用者將 Looker 內容傳送至任何電子郵件網域。允許具備 create_alerts 權限的使用者將快訊通知傳送至任何電子郵件網域。 |
send_to_integration |
see_looks |
特定型號 | 使用者可透過 Looker Action Hub,將 Looker 內容傳送至與 Looker 整合的第三方服務。這項權限與資料動作無關。 |
create_alerts |
see_looks |
整個執行個體 | 使用者可以在資訊主頁圖塊上建立快訊,在符合或超過指定條件時收到通知。使用者可以編輯、複製及刪除自己的快訊,以及其他使用者的公開快訊。如果使用者的 Slack 工作區未連線至 Looker 執行個體,使用者就無法建立會將通知傳送至 Slack 的快訊。 |
download_with_limit |
see_looks |
整個執行個體 | 允許使用者下載查詢結果,並套用限制 |
download_without_limit |
see_looks |
整個執行個體 | 讓使用者下載查詢結果,且不設限 |
see_sql |
see_looks |
特定型號 | 讓使用者查看查詢的 SQL,以及執行查詢時產生的任何 SQL 錯誤 |
clear_cache_refresh |
access_data |
特定型號 | 使用者可以清除快取,並重新整理內嵌資訊主頁、舊版資訊主頁、資訊主頁圖塊、Look 和探索。 |
see_drill_overlay |
access_data |
特定型號 | 讓使用者深入探索,不必前往完整的「探索」頁面。 |
manage_spaces |
無 | 整個執行個體 | 啟用內容瀏覽器,讓使用者可以建立、複製、移動及刪除資料夾。使用者也需要資料夾的「管理存取權」和「編輯」內容存取權,或是上層資料夾的「管理存取權」和「編輯」內容存取權 (如要建立新資料夾)。 |
embed_browse_spaces |
無 | 整個執行個體 | 啟用內容瀏覽器,讓使用者可以從嵌入內容瀏覽資料夾。獲得 embed_browse_spaces 權限的任何嵌入使用者,都能存取個人嵌入資料夾和貴機構的「共用」資料夾 (如有)。建議為具備 save_content 權限的使用者授予 embed_browse_spaces 權限,這樣使用者在選取內容儲存位置時,就能瀏覽資料夾。如要查看資料夾中的內容,使用者也需要 see_looks 、see_user_dashboards 和 see_lookml_dashboards 權限。如要將資訊主頁或 Look 標示為最愛項目,嵌入使用者必須具備 embed_browse_spaces 權限,因為標示內容為最愛項目時,需要存取「我的最愛」資料夾。 |
embed_save_shared_space |
無 | 整個執行個體 | 如果使用者也擁有 save_content 權限,即可在「儲存」對話方塊中,前往機構的「共用」資料夾 (如有)。如果使用者擁有 save_content 權限,但沒有 embed_save_shared_space 權限,只能將內容儲存至個人嵌入資料夾。embed_save_shared_space 權限不會覆寫內容存取權。舉例來說,如要讓使用者能夠將檔案儲存至「已共用」資料夾,他們仍需具備「管理存取權」和「編輯」權限。此外,如果使用者具備 save_content 權限,且擁有「共用」資料夾的「管理存取權」和「編輯」存取權,即使沒有 embed_save_shared_space 權限,只要能透過其他方式前往「共用」資料夾 (例如使用內嵌資訊主頁的「從這裡探索」選項),就能將內容儲存到該資料夾。 |
模型存取權
決定使用者應具備哪些 LookML 模型的存取權。這只會是模型名稱清單。
使用者屬性
決定使用者應具備哪些使用者屬性 (如有)。您需要 Looker 的使用者屬性名稱,以及使用者應有的該屬性值。
群組
決定使用者應屬於哪些群組 (如有)。您需要的是群組 ID,而不是群組名稱。將已簽署的嵌入使用者新增至 Looker 群組,即可管理該使用者對 Looker 資料夾的存取權。已簽署的嵌入使用者有權存取與 Looker 群組成員共用的任何資料夾。
您也可以使用 external_group_id
參數建立群組,這類群組不屬於一般的 Looker 群組。在這種情況下,具有相同 external_group_id
的已簽署嵌入使用者將有權存取外部群組專屬的共用資料夾 (名為「Group」)。
內嵌角色
permissions
和 models
參數會為嵌入使用者建立 role。這個角色會顯示在 Looker「管理」部分的「使用者」頁面中,並標示為「內嵌角色」。如果嵌入網址中指定了 permissions
、models
和 group_ids
參數,嵌入的角色會加成 group_ids
參數中列出的群組已指派的角色。這與標準角色相同,因為 Looker 中的所有角色都是累加的。
舉例來說,假設您在 Looker 中有一個現有群組,群組 ID 為 1
,且該群組已擁有名為 model_one
的模型的 explore
權限,而您使用下列參數建立嵌入網址:
group_ids
=["1"]
permissions
=["access_data","see_looks"]
models
=["model_two"]
在這種情況下,嵌入使用者會繼承在 model_one
上查看及探索資料的權限,而使用上述參數建立的嵌入角色也會授予在 model_two
上查看資料的權限。
建立嵌入網址
已簽署的嵌入網址格式如下:
https://HOST/login/embed/EMBED URL?PARAMETERS&signature=SIGNATURE
主機
主機是代管 Looker 執行個體的位置。例如,analytics.mycompany.com
。如果尚未啟用通訊埠轉送,請務必加入通訊埠編號,例如 analytics.mycompany.com:9999
。
嵌入網址
嵌入網址已在先前決定。格式如下:
/embed/looks/4
/embed/explore/my_model/my_explore
/embed/query-visualization/Query.client_id
/embed/dashboards/1
或/embed/dashboards-legacy/1
/embed/dashboards/my_model::my_dashboard
或/embed/dashboards-legacy/my_model::my_dashboard
這表示最終到達網址會顯示 /embed//embed/
模式,這是正確的。
如果您使用內嵌 JavaScript 事件,請務必在內嵌網址結尾新增 embed_domain
(使用 iFrame 的網域),如下所示:
/embed/looks/4
/embed/looks/4?embed_domain=https://mywebsite.com
embed_domain
會加在嵌入網址之後,以及任何參數之前。因此,如果您有現有參數 (例如 nonce=626
),新增 embed_domain
後會如下所示:
/embed/looks/4?nonce=626
/embed/looks/4?embed_domain=https://mywebsite.com?nonce=626
如果您使用 Embed SDK,請務必新增 embed_domain
,並在嵌入網址結尾加入 sdk=2
,如下所示:
/embed/looks/4
/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
Looker 可透過 sdk=2
參數判斷 SDK 是否存在,並運用 SDK 提供的額外功能。由於這個參數屬於已簽署的網址,SDK 無法自行新增。
參數
下列網址參數用於指定已簽署嵌入的必要資訊:
參數 | 預設值 | 說明 | 資料類型 | 範例 |
---|---|---|---|---|
nonce |
必須提供值 | 任何您喜歡的隨機字串,但一小時內不得重複,且長度必須少於 255 個字元。這樣一來,攻擊者就無法重新提交合法使用者的網址,以收集不應取得的資訊。 | JSON 字串 | "22b1ee700ef3dc2f500fb7" |
time |
必須提供值 | 目前時間 (UNIX 時間戳記)。 | 整數 | 1407876784 |
session_length |
必須提供值 | 使用者應保持登入 Looker 的秒數,須介於 0 至 2,592,000 秒 (30 天) 之間。 | 整數 | 86400 |
external_user_id |
必須提供值 | 在嵌入 Looker 的應用程式中,每位使用者的 ID。Looker 會使用 external_user_id 區分已登入的嵌入使用者,因此每位使用者都必須有專屬 ID。只要是該使用者專屬的字串,您都可以為使用者建立 external_user_id 。每個 ID 都會與一組權限、使用者屬性和模型相關聯。單一瀏覽器一次只能支援一個 external_user_id 或使用者工作階段。工作階段期間無法變更使用者的權限或屬性。為確保安全性,請勿在不同互動式使用者的不同嵌入工作階段中使用相同的 external_user_id ,也不要在具有不同權限、使用者屬性值或模型存取權的單一使用者中使用相同的 external_user_id 。如果多位使用者或同一位使用者使用相同的 external_user_id ,且具有多項權限、使用者屬性或模型集,則使用者可能會看到原本無法存取的資料。 |
JSON 字串 | "user-4" |
permissions |
必須提供值 | 使用者應具備的權限清單。如要查看允許的權限清單,請參閱本頁的「權限」一節。 | 字串陣列 | [ "access_data", "see_looks" ] |
models |
必須提供值 | 使用者應可存取的模型名稱清單。 | 字串陣列 | [ "model_one", "model_two" ] |
group_ids |
[] | 使用者應加入的 Looker 群組清單 (如有)。請使用群組 ID,而非群組名稱。 | 字串陣列 | ["4", "3"] |
external_group_id |
"" | 使用者在嵌入 Looker 的應用程式中所屬群組的專屬 ID。凡是擁有儲存內容權限的使用者,只要共用外部群組 ID,就能在名為「群組」的共用 Looker 資料夾中儲存及編輯內容。external_group_id 參數是建立嵌入式使用者外部群組的唯一可用方法。您無法在 Looker UI 中設定外部嵌入使用者群組。external_group_id 的長度不得超過 81 個字元。系統會為群組建立對應的資料夾,資料夾名稱的長度上限為 100 個字元。資料夾名稱會加上「Embed Shared Group 」前置字串,因此 external_group_id 最多只能有 81 個字元,才能符合 100 個字元以內的限制。 |
JSON 字串 | "Accounting" |
user_attributes |
{} | 使用者應具備的使用者屬性清單 (如有)。包含使用者屬性名稱清單,後面接著使用者屬性值。如果LookML 模型已本地化,您可以在嵌入網址中使用 locale 使用者屬性,為嵌入內容指定語言。舉例來說,加入 user_attributes { "locale" : "fr_FR" } 參數會導致嵌入內容載入法文。 |
字串的雜湊值 | { "vendor_id" : "17", "company" : "xactness" } |
access_filters |
必須提供值 | Looker 3.10 已移除這個參數,但網址中仍須包含這個參數。請使用空白預留位置搭配 access_filters ,例如 access_filters={} 。 |
空白預留位置 | {} |
first_name |
"" | 使用者的名字,如果留空,first_name 會保留上次要求的值,或在未曾設定名字時設為「Embed」。 |
JSON 字串 | "Alice" |
last_name |
"" | 使用者的姓氏,如果留空,last_name 會保留上次要求的值,如果從未設定姓氏,則會是「Embed」。 |
JSON 字串 | "Jones" |
user_timezone |
"" | 如果已啟用「使用者專屬時區」,系統會為嵌入式 Look 或資訊主頁的「時區」下拉式選單設定「檢視者時區」選項的值。這項參數不會直接變更內容顯示的時區,使用者必須從下拉式選單中選取時區。如需有效值,請參閱「已簽署的嵌入時區參考資料」說明文件頁面。即時通訊團隊提示:如要讓嵌入內容預設採用檢視者的時區,請使用下列任一方法:?query_timezone=user_timezone 參數。例如:/embed/dashboards/1?query_timezone=user_timezone |
JSON 字串或空值 | "US/Pacific" - 或 -null |
force_logout_login |
必須提供值 | 如果一般 Looker 使用者已登入 Looker,並查看已簽署的嵌入項目,您可以選擇是否:1) 使用者應使用目前的憑證查看項目或2) 登出後,使用已簽署的嵌入憑證重新登入。 | 布林值 (true 或 false) | true |
簽名
Looker 會使用簽名驗證嵌入網址中是否使用正確的嵌入密鑰產生簽名,以及嵌入網址中的參數是否未變更。如果嵌入密碼或網址參數不同或已變更,簽章就不會相符,驗證也會遭到拒絕。
因此,嵌入網址中的簽章可提供加密強度高的證明,確保嵌入網址在傳輸過程中未遭修改,且是由擁有嵌入密鑰的受信任方所建立。
如要產生簽章,請按照下列步驟操作。
- 依序收集下列參數值:
- 主機,後面加上
login/embed/
(例如analytics.mycompany.com/login/embed/
) - 嵌入網址
- Nonce
- 目前時間
- 工作階段時間長度
- 外部使用者 ID
- 權限
- 模型
- 群組 ID
- 外部群組 ID
- 使用者屬性
- 存取篩選器 (必須提供空白預留位置)
- 主機,後面加上
- 將主機和嵌入網址以外的所有值設為 JSON 格式
- 以換行符號 (
\n
) 串連值 - 使用 Looker 嵌入密鑰,以 HMAC-SHA1 簽署串連的字串
編碼
最後一個步驟是對網址進行網址編碼。
編碼網址前,使用所有可能參數的正確格式嵌入網址可能如下所示:
https://analytics.mycompany.com/login/embed//embed/dashboards/1?
nonce="22b1ee700ef3dc2f500fb7"&
time=1407876784&
session_length=86400&
external_user_id="user-4"&
permissions=["access_data","see_user_dashboards","see_looks"]&
models=["model_one","model_two"]&
group_ids=[4,3]&
external_group_id="Allegra K"&
user_attributes={"vendor_id":"17","company":"xactness"}&
access_filters={}&
first_name="Alice"&
last_name="Jones"&
user_timezone="US/Pacific"&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL
如先前所述,網址中出現 /embed//embed/
是正確的。
編碼後的網址如下所示:
https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards%2F1?
nonce=%2222b1ee700ef3dc2f500fb7&%22&
time=1407876784&
session_length=86400&
external_user_id=%22user-4%22&
permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
models=%5B%22model_one%22%2C%22model_two%22%5D&
group_ids=%5B4%2C3%5D&
external_group_id=%22Allegra%20K%22&
user_attributes=%7B%22vendor_id%22%3A%2217%22%2C%22company%22%3A%22xactness%22%7D&
access_filters%7B%7D%26%0A
first_name=%22Alice%22&
last_name=%22Jones%22&
user_timezone=%22US%2FPacific%22&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL
使用 Create Signed Embed Url API 端點
Looker API 包含「建立已簽署的嵌入網址」端點,可接受一組已簽署的嵌入參數 (包括要嵌入內容的網址),並傳回完整的編碼加密簽署網址。
如要從網路伺服器使用這個 API 端點,網路伺服器必須能夠透過管理員權限驗證 Looker API。網路伺服器網域也必須列在「嵌入網域許可清單」中。
您也可以使用 API Explorer,產生使用這個端點的已簽署網址。您可以從 Looker Marketplace 在 Looker 執行個體上安裝 API Explorer。產生已簽署網址後,請務必完整複製,且只能使用一次,否則會失敗。此外,您也可以使用 API Explorer 產生已簽署的網址,並與手動建立的已簽署網址進行比較,以利排解問題。
如要進一步瞭解 Looker API,請參閱「Looker API 入門」說明文件頁面。
測試嵌入網址
如要測試最終到達網址,請將網址貼到 Looker「管理」部分的「嵌入」頁面中的「嵌入 URI 驗證工具」。這個選項無法判斷您設想的資料和權限是否已正確設定,但可以驗證驗證程序是否正常運作。