透過已簽署的嵌入功能,使用者無需個別登入 Looker,即可向使用者顯示私人嵌入的 Look 圖表、視覺化內容、探索、資訊主頁或 LookML 資訊主頁。而是透過您自己的應用程式驗證使用者。
簽署嵌入功能會建立您要在 iframe 中使用的特殊 Looker 網址。這個網址包含您要分享的資訊、系統中使用者的 ID,以及您希望使用者擁有的權限。接著,您會使用 Looker 提供的密鑰簽署網址。
如要瞭解公開嵌入功能,請參閱「Look 的公開分享、匯入和嵌入」說明文件頁面中的「使用 iframe
標記進行公開嵌入」一節。
在 Looker 執行個體上使用已簽署的嵌入功能前,Looker 管理員必須在 Looker 管理面板中啟用已簽署的嵌入功能,並建立嵌入密鑰。如需操作說明,請參閱「開始使用嵌入功能 - 啟用已簽署的嵌入功能」說明文件頁面。
適當的署名嵌入代管服務
部分瀏覽器 (例如 Safari) 或安裝了可封鎖廣告或追蹤 Cookie 的擴充功能的瀏覽器,預設 Cookie 政策會封鎖第三方 Cookie。啟用無 Cookieless 嵌入功能後,封鎖第三方 Cookie 的瀏覽器就能在不同網域的嵌入式 iframe 中驗證使用者。無 Cookie 嵌入驗證需要進行伺服器端設定。如需設定範例,請參閱「不含 Cookie 的嵌入」說明文件頁面。
如果未啟用 Cookieless Embed 功能,Looker 會使用 Cookie 進行使用者驗證。在這種情況下,如果瀏覽器封鎖第三方 Cookie,就無法跨網域驗證嵌入的 iframe (除非使用者修改瀏覽器的 Cookie 隱私權設定)。舉例來說,如果您想在 https://mycompany.com
上嵌入資訊,請務必確保 Looker 與 https://analytics.mycompany.com
共用相同網域。在這種情況下,如果 Looker 代管您的執行個體,請與 Looker 支援團隊聯絡,設定必要的 DNS 設定,以便使用自訂網域。這樣一來,Looker 就能與嵌入應用程式共用相同網域,並使用第一方 Cookie,所有瀏覽器都會預設接受這類 Cookie。
如果您使用的是客戶代管的 Looker 執行個體,請確認要使用已簽署嵌入功能的應用程式,與 Looker 執行個體使用相同的網域。
使用封閉系統控制用戶端瀏覽權限
在已簽署的嵌入設定中,Looker 使用者通常會向自己的客戶呈現資料,同時提供來自不同公司或群組的客戶,而這些客戶不應彼此認識。在這種情況下,為了保護客戶的私人資訊,我們強烈建議您將 Looker 設為封閉系統,也就是所謂的多租戶安裝程序。在封閉系統中,內容會分隔開來,以免不同群組的使用者互相認識。因此,建議您先啟用封閉式系統選項,再將執行個體存取權授予任何外部使用者。
詳情請參閱「設計及設定存取層級系統」和「嵌入式分析工具的安全性最佳做法」說明文件。
產生已簽署的嵌入網址
產生已簽署的嵌入網址的方法有很多種。您可以使用下列任一方法:
您可以使用資訊主頁三點資訊主頁選單或「探索」或「探索」的「探索動作」齒輪選單,透過「取得嵌入網址」選項產生已簽署的嵌入網址。
使用 Looker Embed 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 探索 UI 建立支援的圖表查詢,然後從 qid= 參數複製 Query.client_id 值,或者使用 Looker API 擷取 Query.client_id ,例如使用 Get Query 方法。 |
/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 |
無 | 特定模型 | 允許使用者存取資料 (查看 Look、資訊主頁或探索時必須具備的權限) |
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 |
整個執行個體 | 允許使用者對外觀和資訊主頁進行變更並儲存 |
send_outgoing_webhook |
see_looks |
特定模型 | 讓使用者將 Looker 內容提交作業排程至任意 webhook |
send_to_s3 |
see_looks |
特定模型 | 讓使用者安排 Looker 內容提交至 Amazon S3 值區 |
send_to_sftp |
see_looks |
特定模型 | 讓使用者排定 Looker 內容傳送至安全檔案傳輸通訊協定伺服器 |
schedule_look_emails |
see_looks |
特定模型 | 讓使用者將 Looker 內容的傳送時間排定為自己的電子郵件地址 (如果使用「電子郵件」使用者屬性設定),或是 電子郵件網域許可清單設定的限制範圍內的電子郵件地址。讓具有 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 權限的嵌入使用者,都會獲得個人嵌入資料夾的存取權,以及貴機構的共用資料夾 (如果有)。建議將 embed_browse_spaces 權限授予具備 save_content 權限的使用者,這樣使用者就能在選取內容儲存位置時瀏覽資料夾。如要查看資料夾中的內容,使用者還需要具備 see_looks 、see_user_dashboards 和 see_lookml_dashboards 權限。 |
embed_save_shared_space |
無 | 整個執行個體 | 讓擁有 save_content 權限的使用者,在「Save」對話方塊中前往機構的「Shared」資料夾 (如果有)。擁有 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
參數會為嵌入使用者建立角色。這個角色會在 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://主機名稱/login/embed/嵌入網址?參數&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
sdk=2
參數可讓 Looker 識別 SDK 是否存在,並利用 SDK 提供的其他功能。這個參數是已簽署網址的一部分,因此 SDK 無法自行新增。
參數
下列網址參數可用於指定已簽署嵌入項目的必要資訊:
參數 | 預設值 | 說明 | 資料類型 | 範例 |
---|---|---|---|---|
nonce |
必須提供值 | 任何隨機字串 (但不得在 1 小時內重複使用,且長度不得超過 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 的使用者,可以在名為「Group」的共用 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 會保留上次要求的值,如果從未設定過名字,則會是「嵌入」。 |
JSON 字串 | "Alice" |
last_name |
"" | 使用者的姓氏。如果留空,last_name 會保留上次要求的值,如果從未設定姓氏,則會是「嵌入」。 |
JSON 字串 | "Jones" |
user_timezone |
"" | 如果已啟用使用者專屬時區,請在嵌入式報表或資訊主頁的「時區」下拉式選單中,設定「觀眾時區」選項的值。這項參數不會直接變更內容顯示的時區,使用者必須從下拉式選單中選取時區。如需有效值,請參閱已簽署嵌入時區參考資料說明文件頁面。Chat 團隊提示:如果您希望嵌入的內容預設為觀眾的時區,請使用下列任一方法:?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 包含「Create Signed Embed Url」端點,可接受一組已簽署的嵌入參數,其中包含要嵌入的內容網址,並傳回完整的已編碼加密簽署網址。
如要透過網路伺服器使用這個 API 端點,網路伺服器必須能夠以管理員權限驗證 Looker API。網路伺服器網域也必須列在嵌入網域許可清單中。
您也可以使用 API Explorer 產生使用這個端點的已簽署網址。您可以從 Looker Marketplace 在 Looker 執行個體上安裝 API Explorer。產生後,您必須完全複製已簽署網址,且只能使用一次,否則系統會失敗。如要產生已簽署網址,並與手動建立的已簽署網址進行比較,以便排解問題,API Explorer 也是不錯的選擇。
如要進一步瞭解 Looker API,請參閱「Looker API 入門」說明文件頁面。
測試嵌入網址
如要測試最終網址,請將網址貼到 Looker 管理區段的「嵌入」頁面中「嵌入 URI 驗證工具」中。雖然這個選項無法告訴您設定的資料和權限是否正確,但可以驗證驗證機制是否正常運作。