Looker API 3.x 淘汰

API 3.x 將於 2023 年 8 月停用

我們先前曾宣布，這項異動將於 2023 年 7 月生效。根據客戶意見，我們將這項作業的期限延後至 2023 年 8 月，以便順利完成轉換。關閉這個對話方塊即可瞭解詳情。

繼 Looker 22.4 推出 API 4.0 GA 版後，我們宣布除了已淘汰的 3.0 API 外，也將淘汰 3.1 API。

自 2022 年 6 月我們宣布淘汰這項功能後，3.1 API 和 3.0 API (統稱為 3.x) 皆已淘汰。自 2023 年 8 月 Looker 23.14 版發布起，3.x API 版本就會停用。

這項升級作業會在 8 月 14 日至 8 月 24 日的維護時間內，針對 Looker 代管執行個體推出。因此，所有 Looker 代管的執行個體必須在 2023 年 8 月 14 日前升級應用程式，改用 4.0 API 端點，而非 3.x API 端點。在這個變更生效後，任何依賴 3.x 端點的功能都會停止運作。

如果您使用的是自架式執行個體，請先升級應用程式，再將 Looker 執行個體升級至 23.14 以上版本。

4.0 API 完全涵蓋已淘汰的 API 提供的功能，因此大多數客戶都能輕鬆從 3.x 升級至 4.0。

如果客戶無法順利遷移至 API 4.0，請與 Looker 支援團隊聯絡。

時間軸

  • 2022 年前：API 3.0 已淘汰，3.1 為穩定版，4.0 為 Beta 版
  • 2022 年 3 月：API 4.0 進入穩定狀態，並在 Looker 22.4 中正式推出
  • 2022 年 6 月：宣布淘汰 API 3.1
  • 2023 年 8 月：Looker 將停用 API 3.x

適用對象

如果您是透過 Looker 支援的 SDK、社群支援的 SDK 或 API 本身使用 Looker API，請參閱本文。請繼續閱讀，瞭解可能會影響應用程式的破壞性變更，以及如何因應。

我需要做些什麼？

您需要對程式碼進行下列變更。本頁後續會進一步說明這些項目。

  • 將程式碼改為指向新的 API。
  • 找出已移除的端點用途，並將這些參照替換為 API 4.0 的等效項目。
  • 將先前以數字表示的 ID 值更新為字串。

API 4.0 遷移詳細資料

將程式碼改為指向新的 API

透過指令列或 Postman 等程式直接呼叫 API 時，您需要調整用於提出要求的網址。

### API 3.1 ###
GET https://myinstance.looker.com/api/3.1/users/5877

### API 4.0 ###
GET https://myinstance.looker.com/api/4.0/users/5877

如果您使用我們的 SDK，請務必先確認您初始化的 SDK 版本正確無誤。以下是使用 SDK 在兩個版本中執行 Python 指令碼開頭的範例：

### API 3.1 ###
import looker_sdk
sdk = looker_sdk.init31()

### API 4.0 ###
import looker_sdk
sdk = looker_sdk.init40()

對 4.0 API 完成變更後，請測試程式碼，並留意下列變更。

API 3.x 端點替換

為讓 Looker API 和 Looker UI 的用語保持一致，API 4.0 將部分已淘汰的 API 3.x 端點，替換為等同或更優的端點，如下所列：

「聊天室」端點已重新命名。請改用同義的「Folder」端點。

Python SDK 範例

    #####################
    ##### API 3 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_space(
      body=mdls.CreateSpace(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.space(space_id="555")

    # Change name of existing Folder
    response = sdk.update_space(
      space_id="555",
      body=mdls.UpdateSpace(
        name="My Updated Folder"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Create Folder in Shared Folders
    response = sdk.create_folder(
      body=mdls.CreateFolder(
        name="My New Folder",
        parent_id="1"
      )
    )

    # Get Folder info by ID
    response = sdk.folder(folder_id="555")

    # Change name of existing Folder
    response = sdk.update_folder(
      space_id="555",
      body=mdls.UpdateFolder(
        name="My Updated Folder"
      )
    )

cURL 範例

    #####################
    ##### API 3 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/spaces/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/3.1/spaces/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Folder info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/folders/555

    # Change name of existing Folder
    curl -X PATCH https://myinstance.looker.com/api/4.0/folders/555 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"name\": \"My Updated Space\"}"

已移除「Homepage」端點。請改用擴充功能「board」端點。

Python SDK 範例

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    response = sdk.homepage(homepage_id=1348)

    # Update displayed title of Board item
    response = sdk.update_homepage_item(
      homepage_item_id=86,
      body=mdls.WriteHomepageItem(
        custom_title="Volume 3"
      )
    )

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    response = sdk.board(board_id=1348)

    # Update displayed title of Board item
    response = sdk.update_board_item(
      board_item_id=86,
      body=mdls.WriteBoardItem(
        custom_title="Volume 3"
      )
    )

cURL 範例

    #####################
    ##### API 3 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/homepages/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/3.1/homepage_items/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

    #####################
    ##### API 4 #########
    #####################

    # Get Board info by ID
    curl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/boards/1348

    # Update displayed title of Board item
    curl -X PATCH https://myinstance.looker.com/api/4.0/boards/86 -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" -H "Content-Type: application/json" -d "{\"custom_title\": \"Volume 3\"}"

API 4.0 破壞 ID 欄位類型

API 4.0 已將部分 ID 欄位的類型從數字更新為字串。使用我們的 API 參考資料差異比較工具，判斷 3.1 和 4.0 之間有哪些 ID 欄位有所變更。請使用最新 (23.0 以上) 的Looker 支援語言 SDK，確保應用程式在遷移期間和遷移後的型別正確無誤。大多數社群支援的語言 SDK (包括 Kotlin、Swift、R、C# 和 Go) 也已支援更新的類型。

使用自訂程式庫的開發人員應搜尋程式碼中是否有這些欄位的參照，確保這些欄位已妥善處理。

API 4.0 差異比較

除了本說明文件頁面列出的規範之外，Looker API Explorer 還提供3.x API 與 4.0 API 之間的所有差異完整清單。

透過舊版功能切換鈕停用/啟用 API 3.x

對於使用 Looker 23.6、23.8、23.10 和 23.12 的 Looker 代管客戶，管理員目前可以停用所有對 API 3 端點的呼叫。這樣您就能在執行個體上進行測試，確保在 8 月 14 日期限前，不會有任何整合服務或應用程式中斷。如要這麼做，請在舊版功能管理面板中切換「拒絕 API 3.x 要求」的開關。

使用 Looker 23.6、23.8、23.10 和 23.12 的自行主控客戶可以在啟動 Looker 前執行下列 Shell 指令，以便新增環境變數，讓「Deny API 3.x requests」切換按鈕顯示 (注意：執行指令後，您仍需在 Looker UI 的「Legacy Features」面板中切換按鈕，才能停止 API 3 呼叫)：

export FF_DENY_API3=true

常見問題

我不確定我的執行個體是否發出 API 3.x 呼叫。如何查看這項資訊？

自 Looker 23.8 起，管理員 > 查詢面板中的「來源」欄，現在會正確顯示從 Looker API 啟動的查詢 API 版本 (v3 或 v4)。這份報告不會包含管理員或開發人員工作相關資訊，例如建立使用者或 LookML 開發/Git 工作。

我們的內部報表服務提供更詳細的 API 要求資訊，包括用於完成「管理」和 LookML 開發工作的工作。如果客戶的執行個體採用建議的網路設定，可以聯絡 Looker 支援團隊，要求匯出這項資料。

我自行代管執行個體。我是否需要在 2023 年 8 月 14 日前升級？

如果您是自行代管的例項，請先進行變更，再升級至 2023 年 8 月的版本 (23.14 版) 或後續版本。建議您盡快開始這項工作，以便繼續使用支援的版本，獲得最佳的 Looker 體驗。

我的執行個體是 Looker 代管的，但屬於 ESR 計畫。我是否需要在 2023 年 8 月 14 日前升級？

您必須在執行個體升級至 2023 年 8 月的版本 (23.14 版) 或後續版本前，先進行變更。建議您盡快開始這項工作，以免在執行個體升級時措手不及。

我已詳閱說明文件，但仍遇到問題，或不確定如何繼續操作。

如果客戶無法順利遷移至 API 4.0，請與 Looker 支援團隊聯絡。