Looker API 3.x 淘汰

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

我們先前曾宣布這項異動將於 2023 年 7 月版本生效。為順應客戶意見，我們將期限延後至 2023 年 8 月，協助客戶順利完成轉換。關閉這個對話方塊即可查看詳細資料。

在 Looker 22.4 中正式發布 API 4.0 後，我們宣布淘汰 3.1 API，以及已淘汰的 3.0 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 端點替換為同等或改良的端點，如下所示：

「Space」端點已重新命名。請改用同義的「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\"}"

「首頁」端點已移除。請改用擴充功能「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 代管的 Looker 23.6、23.8、23.10 和 23.12，管理員目前可以停用所有對 API 3 端點的呼叫。這樣一來，您就能在執行個體上進行測試，確保整合的服務或應用程式在 8 月 14 日截止日期前不會中斷。如要這麼做，請在舊版功能管理面板中，開啟「拒絕 API 3.x 要求」切換鈕。

使用 Looker 23.6、23.8、23.10 和 23.12 的自行託管客戶，可以在啟動 Looker 前執行下列殼層指令，新增環境變數，讓「拒絕 API 3.x 要求」切換鈕顯示 (注意：執行指令後，您仍須在 Looker UI 的「舊版功能」面板中切換切換鈕，才能停止 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 支援團隊聯絡。