介绍 Shopify Functions 中的 functionHandle

截至 2025-10 API 版本，我们引入了对用户定义句柄的支持，将其作为 GraphQL 变更中 Shopify Functions 的标识符。在创建或管理函数所有者的变更中，您无需传递全局唯一的 functionId，而是可以传递您在 shopify.extension.toml 中定义的、稳定的应用范围句柄。当前接受 functionId 的所有 GraphQL 变更现在也将接受 functionHandle。

注意：每次调用必须提供 'functionId' 或 'functionHandle' 其中之一，不能同时提供两者。同时提供两者将导致用户错误。

这为您带来的好处

函数 ID 在部署到不同环境时会发生变化，这迫使开发者在创建或更新函数所有者之前查询最新的 ID。而句柄在不同环境中保持稳定且限定于您的应用范围，从而消除了创建函数所有者前查询 shopifyFunction 的需求。

无需开发人员操作

这些更改不会破坏您现有的集成。functionId 将继续有效。但是，我们建议您更新代码以改用 functionHandle：

• 移除在运行时查询 functionId 的代码。
• 直接在 GraphQL 变更中使用您在 shopify.extension.toml 中定义的 functionHandle。

关于 functionId 的正式弃用和移除时间表将另行公布。

使用示例

1. 从函数的 shopify.extension.toml 获取 functionHandle：

[[extensions]] name = "Payment Customization Function" handle = "YOUR_FUNCTION_HANDLE" type = "function"

1. 使用 Handle 函数创建支付定制 functionHandle

mutation { paymentCustomizationCreate(paymentCustomization: { title: "Payment Customization Title", enabled: true, functionHandle: "YOUR_FUNCTION_HANDLE", }) { paymentCustomization { id } userErrors { message } } }