弃用 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 界面中的术语保持一致，API 4.0 将一些已废弃的 API 3.x 端点替换为等效或经过改进的端点，如下所示：

“聊天室”端点已重命名。请改用同义的“文件夹”端点。

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\"}"

“主页”端点已移除。使用扩展功能“板”端点。

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"
      )
    )

c网址 示例

    #####################
    ##### 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 参考差异工具确定哪些 ID 字段在 3.1 和 4.0 之间发生了变化。使用最新的（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 命令，以添加一个环境变量，该变量会使“拒绝 API 3.x 请求”切换开关可见（注意：执行该命令后，您仍然需要在 Looker 界面的“旧版功能”面板中切换该切换开关，才能停止 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 支持团队联系。