我精通 Looker 的 API Explorer。該怎麼處理?

使用者可以透過 Looker 的 API Explorer 測試 API 呼叫,幾乎不必編寫任何程式碼。如果您已從 Looker Marketplace 安裝 API Explorer 擴充功能,可以按一下 Looker「應用程式」選單中的「API Explorer」,開啟 API Explorer 並查看目前的 API 說明文件。如果尚未安裝 API 瀏覽工具擴充功能,可以前往 Looker Marketplace 的「應用程式」部分安裝。

您可能已透過 API Explorer 找出最佳工作流程,動態建立 Look、更新基礎查詢,並排定時間將 Look 傳送給公司內各利害關係人。接下來常見的問題是,如何在 API Explorer 以外執行這些呼叫或函式?存取 API 的常見方式有三種:

  1. Looker 的 API 軟體開發套件 (SDK)
  2. HTTP 要求
  3. 軟體開發工具

本頁面將逐步說明如何使用這些方法。

事前準備:驗證和通訊埠

無論您如何存取 Looker 的 API,都必須先取得兩項資訊:個人 API 驗證 (以用戶端 ID 和用戶端密碼的形式) 和 Looker 執行個體使用的連接埠號碼。

如要查看用戶端 ID 和用戶端密鑰,請按照下列步驟操作:

  • 如果您是 Looker 管理員,請在 Looker UI 中前往感興趣使用者的「使用者」頁面,然後前往「編輯金鑰」
  • 如果您不是 Looker 管理員,Looker 管理員會提供用戶端 ID 和用戶端密鑰。
請務必記住,請勿將用戶端 ID 和用戶端密鑰提供給任何人。

如果是託管於 Google Cloud 或 Microsoft Azure 的 Looker 執行個體,以及託管於 Amazon Web Service (AWS) 且在 2020 年 7 月 7 日當天或之後建立的執行個體,預設的 Looker API 路徑會使用 443 連接埠。如果是 2020 年 7 月 7 日前建立的 AWS 代管 Looker 執行個體,預設 Looker API 路徑會使用 19999 埠。

如果您自行代管執行個體,請洽詢系統管理員取得連接埠號碼。您可以在 Looker 管理面板的「API 主機網址」欄位中設定。如要查看這項資訊,請前往 Looker 的「管理」選單下拉式選單,然後選取「API」

如要進一步瞭解連接埠,請前往「開始使用 Looker API」說明文件頁面。下列範例使用 API 連接埠 19999,但您應確認執行個體使用的連接埠。

選項 1:使用 Looker 軟體開發套件 (SDK)

Looker 提供官方 Looker API 用戶端 SDK,支援 PythonRubyTypescript 和 JavaScriptSwiftKotlinR。您可以在 Looker 的 sdk-examples GitHub 存放區中找到原始碼和範例。

SDK 提供工具或程式庫,可讓開發人員與特定平台或應用程式互動。在這種情況下,Looker 的 SDK 通常包含 API。以網頁開發人員兼作家 Kristopher Sandoval 的例子來說,「API 是電話線,可讓住家內外通訊。SDK 本身就是房屋,包含所有內容。他在「API 和 SDK 有何不同?」這篇精彩文章中,說明瞭 SDK 的定義,以及 SDK 與 API 的關係。

Looker 的 SDK 包含您可能想用或需要使用的所有 API 端點,並以封裝形式提供,讓您能使用所選程式設計語言與 Looker 順暢互動。這些函式可讓您執行下列工作:

  • 將資料傳送至 Looker
  • 從 Looker 取得資料
  • 更新 Looker 中的資料
  • 刪除 Looker 中的資料
下一節將詳細說明這些動作之間的差異。

以下是使用 Python SDK 更新使用者的範例:

  1. 使用 looker_sdk.init 初始化工作階段。
  2. 使用 sdk.update_user 更新使用者。您會傳遞 user_id,指定要更新的使用者。
  3. 使用 models.WriteUser 指定要如何更新使用者。

    #### Initialize API/SDK for more info go here: https://pypi.org/project/looker-sdk
    from looker_sdk import methods40, models
    sdk = looker_sdk.init40()
    me = sdk.me()
    # print(me)
    new_friend = sdk.update_user(user_id=29,
    body=models.WriteUser(first_name="newnew", last_name="new_again"))
    print(new_friend)
  

使用其中一個 SDK 時,如果您使用 Visual Studio Code 等 IDE,並按住 Command 鍵點選 (Visual Studio Code 預設設定為 F12),然後選取「go to definitions」,即可查看所有方法,以及方法接受或傳回的所有參數。您也可以在 SDK GitHub 存放區中查看這些檔案,尋找方法和模型檔案。

選項 2:使用 curl 或 requests 程式庫發出 HTTP 要求

如果您不想編寫指令碼,也不想花上數月或數年學習新的程式設計語言,該怎麼辦?在這種情況下,您可以使用 curl 發出 HTTP 要求,以使用 Looker 的 API。

HTTP 要求會將訊息傳送至目的地,目的地可以是伺服器、手機,甚至是智慧型電視。HTTP 要求分為幾種不同類型,如何搭配 Looker 的 API 使用這些要求,取決於您在 API 呼叫中傳遞的方法性質。部分方法會提供資料、部分方法會將資料傳送至 Looker、部分方法會更新資料,還有部分方法會從 Looker 刪除或移除資料。

動作 方法
建立 POST
閱讀 GET
更新 PUT
刪除 DELETE

開始打冰壺吧!如需相關背景資訊,請參閱 Zendesk 的實用教學課程「安裝及使用 cURL」。

如要開始對 Looker API 進行 HTTP 呼叫,首先必須使用用戶端 ID 和用戶端密碼呼叫 Looker API 的 login 端點。這樣就會建立存取權杖。然後,您會取得這個存取權杖,並在每次呼叫時傳遞該權杖。存取權杖可確保呼叫來自授權使用者。

本頁面使用幾種符號,指出您應將程式碼範例中的文字替換為自己的資訊。Looker 代管執行個體網址的格式為 https://<hostname>.<subdomain>.<domain>.com;如果在本頁的範例中看到這個符號,請將 <hostname>.<subdomain>.<domain>.com 部分替換為 Looker 執行個體的網址。此外,我們使用 <value> 標記,指出您應輸入適當值的位置,並取代程式碼範例中的 <value>。舉例來說,在下列程式碼中,請將第一個 client_id=<value>&client_secret=<value> 替換成 client_id,第二個 client_id=<value>&client_secret=<value> 替換成 client_secret<value><value>

以下是取得存取權杖的 curl:

  curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login
  

回覆內容如下:

  {"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}
  

收到權杖表示 Looker 認可您的 API 憑證。系統會傳回權杖和 expires_in 值,指出權杖的有效時間長度。通常約為 60 分鐘 (3,600 秒)。

取得存取權杖後,您就可以發出呼叫。Looker API 4.0 參考資料文件會依 API 版本列出所有端點。請注意,Looker 社群網站 是絕佳資源,您可以在這裡向其他 Looker 使用者詢問如何運用 API、瞭解最佳做法,或是與其他使用者分享您透過 API 獲得的成就。

假設您要建立新使用者,方法如下:

  1. 編寫 curl POST 要求,傳遞權杖來告知 Looker 您已獲得授權。
  2. 加入主體 (在本例中為 JSON 格式),告知 Looker 您希望新使用者具備哪些屬性。(API 呼叫有一些必填欄位,因此請參閱 Looker API 4.0 參考資料說明文件)。
  3. 以要使用的端點 (本例為 users) 結束 curl 標示法。

  curl -H "Authorization: token <value>
  " -H "Content-Type: application/json" -d "{\"first_name\": \"<value>\",\"last_name\": \"<value>\", \"email\":\"<value>\"}" https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/users

-H 代表標頭,-d 代表資料。如要進一步瞭解 curl 指令,請參閱這份 GitHub 要點

您剛才建立的使用者,其名字、姓氏和電子郵件地址的值,與您先前輸入的值相同。

如果想在指令碼中編寫這項操作,這樣就不必在每次完成這項工作流程時都寫出這些指令,該怎麼做?您可以使用程式設計語言和程式庫,例如 Python 的 requests 程式庫

舉例來說,以下指令碼會使用 requests 程式庫,透過 Look ID (looks 呼叫中的 <value>) 取得 Look、套用新篩選器,然後將結果下載為 CSV 檔案:

  import requests
  ID = '<value>'
  SECRET = '<value>'
  PARAMS = {'client_id':<value>,
            'client_secret': <value>}
  URL = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/login"
  r = requests.post(url = <value>, params = <value>, verify=False)
  data = r.json()
  token = data['access_token']
  print(token)
  headers = {'Authorization': "Bearer " + token}
  print(headers)
  look_url = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/looks/<value>"
  look = requests.get(look_url, headers=headers, verify=False)
  json = look.json()
  query = json['query']
  ### ADD MODEL HERE
  ### ADD FILTER
  body = {
      "model":"<value>",
      "view":query['view'],
      "fields":query['fields'],
      "filters":{<value>}
  }
  print(body)
  run_inline = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/queries/run/csv"
  run_query = requests.post(run_inline, headers = headers, json=body, verify=False)
  print(run_query._content)
  print(run_query.url)

選項 3:軟體開發工具

使用者可透過 PostmanPaw 等工具,透過圖形使用者介面 (GUI) 互動或運用 API 端點。軟體開發工具的處理方式與 HTTP 要求相同。首先,請使用用戶端密鑰和用戶端 ID 登入。接著,將存取權杖儲存為不記名權杖,授權後續的 API 呼叫,如下圖所示的 Postman 範例。

Postman GUI,其中填入 Looker POST 網址、用戶端密鑰和用戶端 ID。

您可以在 Postman 或其他軟體開發工具 (例如 Paw) 的 UI 中指定授權、主體、參數和標頭,然後產生要求。當您按下「傳送」時,這些端點也會執行。

Go forth! (但請小心)

現在您可以使用 SDK、HTTP 要求和軟體開發工具,透過 Looker 的 API 進行測試!不過請注意,雖然使用 API 有助於自動執行程序 (例如在使用者離開公司後建立或重新指派時間表),但如果 API 使用不當,可能會導致執行個體損壞。

一般注意事項:

  • 編輯權限或刪除使用者時請特別謹慎,尤其是大量編輯或刪除時。您可能會刪除或封鎖許多使用者 (包括管理員),而且這類動作不容易復原。
  • API 呼叫會增加執行個體用量,因此請盡量在離峰時段排定呼叫,以獲得最佳效能。
  • 每個執行個體伺服器都有開啟檔案的限制,因此不當使用 API 可能會導致執行個體當機。
  • 先小規模測試工作流程和函式,再新增至正式環境。
  • 請勿分享 API 憑證,也不要將憑證存放在其他使用者可存取的檔案中。

如有任何問題或想分享絕妙點子,請前往 Looker 社群。如有任何建議或想在文件中新增其他範例,歡迎與我們聯絡。