API 3.x 将于 2023 年 8 月停用
我们之前曾告知用户,这一变更将在 2023 年 7 月发布的版本中推出。根据客户的反馈,我们已将此截止日期延后至 2023 年 8 月,以帮助您更顺利地完成此次过渡。关闭此对话框可了解更多详情。
在 Looker 22.4 中推出 API 4.0 GA 版本后,我们宣布弃用 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 端点替换为了等效或经过改进的端点,如下所示:
“聊天室”端点已重命名。请改用同义词“文件夹”端点。
- 查看文件夹功能文档。
- 请参阅文件夹 API 端点列表。
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" ) )
c网址 示例
##################### ##### API 3 ######### ##################### # Get Folder info by IDcurl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/spaces/555
# Change name of existing Foldercurl -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 IDcurl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/folders/555
# Change name of existing Foldercurl -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\"}"
“主页”端点已移除。请改用扩展的功能“板级”端点。
- 查看开发板功能文档。
- 请参阅板级 API 端点列表。
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 IDcurl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/3.1/homepages/1348
# Update displayed title of Board itemcurl -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 IDcurl -H "Authorization: token Tg7gjGZD7B8c3k7g6XtmbcyYrQgMrXpjkR25dQ2G" https://myinstance.looker.com/api/4.0/boards/1348
# Update displayed title of Board itemcurl -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 3 界面的“旧版功能”面板中切换相应切换开关):如需停止 API
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 支持团队联系。