尧图网站建设 
InvenTree 插件开发实战使用 APICallMixin 集成外部 API【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree导读APICallMixin是 InvenTree 插件体系中用于“调用外部 API”的官方基础 Mixin它屏蔽了requests底层细节让插件开发者可以用几行声明式配置 一次api_call()调用完成与第三方服务如 ERP、云平台、外部数据库的对接。读完本文你将掌握该 Mixin 的继承顺序、配置项API_URL_SETTING/API_TOKEN_SETTING/API_TOKEN、api_call()全部参数语义以及如何组合SettingsMixin让 URL 与 Token 可在后台安全配置。1. APICallMixin 是什么官方文档docs/docs/plugins/mixins/api.md明确指出The APICallMixin class provides basic functionality for integration with an external API.即为插件提供与外部 API 集成的基础能力。它的定位是“脚手架”——你只需要声明“外部服务的地址存哪个设置、Token 存哪个设置”其余 URL 拼接、请求头构造、JSON 序列化、响应解析都由 Mixin 完成。在源码中它位于 src/backend/InvenTree/plugin/base/integration/APICallMixin.py底层使用 Python 生态标准的requests库并通过structlog接入 InvenTree 的统一日志体系。2. 五步接入法官方推荐流程Mixin 类文档字符串APICallMixin.py给出了明确的接入步骤继承顺序将APICallMixin放在SettingsMixin和InvenTreePlugin之前左侧声明设置项用SettingsMixin定义两个设置分别存放外部服务的 URL 与 Token/密码绑定设置键通过API_URL_SETTING和API_TOKEN_SETTING指向第 2 步设置项的键名可选指定请求头键名API_TOKEN指定外部 API 期望的 Token 请求头名称默认Bearer可选覆盖属性需要扩展 URL 或追加请求头时重写api_url/api_headers。完成上述声明后插件代码中即可通过self.api_call(...)发起请求。Mixin 注册机制在__init__中Mixin 会调用self.add_mixin(PluginMixinEnum.API_CALL, has_api_call, __class__)APICallMixin.py注册键名为api_call见 plugin.py 中的PluginMixinEnum.API_CALL api_call。这意味着框架能在插件元信息中识别“该插件具备 API 调用能力”并可用于运行期能力检查。就绪校验has_api_callhas_api_call属性APICallMixin.py负责检查配置是否完整未定义API_URL_SETTING→ 抛出MixinNotImplementedError(API_URL_SETTING must be defined)未定义API_TOKEN_SETTING→ 抛出MixinNotImplementedError(API_TOKEN_SETTING must be defined)。对应测试见 test_mixins.py缺失任一配置的插件在调用has_api_call()时都会被拒绝加载。3. 最小可运行示例SampleApiCallerPlugin官方文档的示例插件即仓库内的 src/backend/InvenTree/plugin/samples/integration/api_caller.py完整代码如下Sample plugin for calling an external API. from plugin import InvenTreePlugin from plugin.mixins import APICallMixin, SettingsMixin class SampleApiCallerPlugin(APICallMixin, SettingsMixin, InvenTreePlugin): A small api call sample. NAME Sample API Caller SETTINGS { API_TOKEN: { name: API Token, protected: True, default: reqres-free-v1, }, API_URL: { name: External URL, description: Where is your API located?, default: api.example.com, }, } API_URL_SETTING API_URL API_TOKEN_SETTING API_TOKEN API_TOKEN x-api-key def get_external_url(self): Returns data from the sample endpoint. return self.api_call(api/users/2)关键点拆解继承顺序APICallMixin, SettingsMixin, InvenTreePlugin与官方要求完全一致SETTINGS字典API_TOKEN被标记为protected: True表明 Token 属于敏感值InvenTree 后台对其做脱敏处理不展示明文API_URL提供description说明用途并给出默认值API_URL_SETTING API_URL告诉 Mixin 去get_setting(API_URL)取地址API_TOKEN_SETTING API_TOKEN告诉 Mixin 去get_setting(API_TOKEN)取凭证API_TOKEN x-api-key将 Token 以x-api-key请求头发送给外部服务见下文请求头构造逻辑get_external_url()业务方法调用self.api_call(api/users/2)即可访问{base_url}/api/users/2。该示例插件的回归测试见 src/backend/InvenTree/plugin/samples/integration/test_api_caller.py测试断言插件以 slugsample-api-caller注册进registry.plugins并能在 mock 的https://api.example.com/api/users/2端点返回{data: sample}。4. 类属性与动态属性详解4.1 类级常量默认值属性默认值含义API_METHODhttpsURL 协议前缀默认走 HTTPSAPI_URL_SETTINGNone指向外部服务地址的设置键必须定义API_TOKEN_SETTINGNone指向凭证的设置键必须定义API_TOKENBearer发送凭证时使用的请求头名称其中API_URL_SETTING/API_TOKEN_SETTING为None时has_api_call会直接抛错API_TOKEN默认Bearer即默认按标准 OAuth/Bearer 风格发送。4.2 api_url基础地址属性property def api_url(self): Base url path. return f{self.API_METHOD}://{self.get_setting(self.API_URL_SETTING)}见 APICallMixin.py。它把协议与API_URL_SETTING指向的设置值拼成https://api.example.com这样的基址。若设置值本身已含协议前缀如测试中的https://api.example.com可通过重写api_url属性绕过默认拼接——测试 test_mixins.py 即示范了这一做法。4.3 api_headers默认请求头property def api_headers(self): headers {Content-Type: application/json} if getattr(self, API_TOKEN_SETTING, None): token self.get_setting(self.API_TOKEN_SETTING) if token: headers[self.API_TOKEN] token headers[Authorization] f{self.API_TOKEN} {token} return headers见 APICallMixin.py。默认行为固定携带Content-Type: application/json若配置了 Token 且非空则同时发送两个头{API_TOKEN}: {token}示例中即x-api-key: reqres-free-v1Authorization: {API_TOKEN} {token}即Bearer token或x-api-key token风格。测试 test_mixins.py 验证了 POST 请求携带Authorization: x-api-key sample-free-v1与Content-Type: application/json。需要额外头如 Accept、自定义 Trace-ID时重写api_headers并调用父类实现再扩展即可。5. api_call统一请求入口api_call()APICallMixin.py是所有请求的统一入口其完整签名与语义如下参数类型默认值说明endpointstr必填端点路径若endpoint_is_urlTrue则为完整 URLmethodstrGETHTTP 方法需大写如POSTurl_argsdictNone追加到 URL 的查询参数自动拼接为?kvk2v2dataAnyNone请求体数据URL 编码表单方式发送jsonAnyNone请求体数据JSON 序列化后发送headersdictNone自定义请求头为None时使用self.api_headerssimple_responseboolTrue为True时直接返回response.json()解析结果endpoint_is_urlboolFalse为True时不拼接self.api_urlendpoint即完整 URL**kwargs——透传给底层requests.request如timeout、verify5.1 内部处理流程拼接查询参数url_args非空时调用api_build_url_args()生成?keyvalue...追加到 endpoint确定请求头未显式传headers时使用self.api_headers确定目标 URLendpoint_is_url为真则直接使用否则自动去掉 endpoint 开头的/拼成{self.api_url}/{endpoint}数据互斥校验data与json同时传入时抛出ValueError(You can either passdataorjsonto this function.)序列化json参数经json_pkg.dumps(json)序列化后写入data发送请求requests.request(method, urlurl, **kwargs)返回结果simple_responseTrue返回 JSON 解析后的对象否则返回原始Response。最简用法类文档注释中的示例self.api_call(hello) # GET {base_url}/hello自动携带 Token5.2 api_build_url_args查询参数编码见 APICallMixin.py。它把字典转成查询串且可迭代值列表/元组非字符串会自动用逗号连接。测试 test_mixins.py 覆盖了各类输入api_build_url_args({a: abc123}) # ?aabc123 api_build_url_args({a: 1}) # ?a1 api_build_url_args({a: b, c: 42}) # ?abc42 api_build_url_args({a: b, c: [d, efgh, 1337]}) # ?abcd,efgh,13375.3 完整调用示例综合用法以下调用方式在 test_mixins.py 中被逐一验证# GET 查询参数请求 https://api.example.com/repos/inventree/InvenTree/stargazers?page2 self.api_call(repos/inventree/InvenTree/stargazers, url_args{page: 2}) # POST JSON 请求体 完整 URL self.api_call( https://api.example.com/users/, json{name: morpheus, job: leader}, methodPOST, endpoint_is_urlTrue, ) # GET 前导斜杠会被自动去掉 self.api_call(/orgs/inventree, simple_responseFalse) # 自定义请求头与透传 kwargs如超时控制 self.api_call(api/users/2, headers{Accept: application/json}, timeout10)6. 实战要点与注意事项6.1 凭证安全务必在SETTINGS中为 Token 设置protected: TrueInvenTree 后台会将其作为受保护值处理避免明文泄露get_setting()/set_setting()来自SettingsMixinSettingsMixin.py插件的设置项会持久化存储可在后台“插件设置”页面动态修改无需改代码。6.2 错误与异常语义MixinNotImplementedErrorAPI_URL_SETTING/API_TOKEN_SETTING缺失时抛出说明插件配置不完整ValueErrordata与json同时传入时抛出HTTP 错误Mixin 默认不吞错simple_responseTrue时返回的是response.json()结果即使状态码非 2xx需在业务方法中自行判断simple_responseFalse时可拿到完整Response对象检查status_code测试 test_mixins.py 展示了 400/404 场景。6.3 与其它 Mixin 的协作APICallMixin常与以下 Mixin 组合使用SettingsMixin必备搭档提供设置项定义与get_setting/set_setting存储机制ScheduleMixin配合定时任务周期性地轮询外部 APIEventMixin在库存变化、订单状态变更等事件中触发外部同步。6.4 使用前注意事项本 Mixin 依赖外部服务可访问性实际部署时请结合 InvenTree 的代理/网络配置见 docs/docs/start/processes.md示例中的api.example.com为占位地址接入真实服务时请替换为实际域名插件启用与否由 InvenTree 插件注册中心registry统一管理示例测试即通过registry.plugins[sample-api-caller]获取插件实例test_api_caller.py。7. 小结APICallMixin用声明式配置 单一入口api_call()把“插件 ↔ 外部 API”集成成本降到最低开发者只需定义两个设置项并绑定键名即可获得自动 URL 拼接、Token 注入、JSON 序列化与响应解析能力。建议读者以 api_caller.py 为模板起步参考 test_mixins.py 的测试用例理解各参数边界行为正式对接第三方服务时按外部 API 文档重写api_url/api_headers并通过url_args、json、timeout等参数精细化控制请求。【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InvenTree 插件开发实战：使用 APICallMixin 集成外部 API
InvenTree 插件开发实战使用 APICallMixin 集成外部 API【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree导读APICallMixin是 InvenTree 插件体系中用于“调用外部 API”的官方基础 Mixin它屏蔽了requests底层细节让插件开发者可以用几行声明式配置 一次api_call()调用完成与第三方服务如 ERP、云平台、外部数据库的对接。读完本文你将掌握该 Mixin 的继承顺序、配置项API_URL_SETTING/API_TOKEN_SETTING/API_TOKEN、api_call()全部参数语义以及如何组合SettingsMixin让 URL 与 Token 可在后台安全配置。1. APICallMixin 是什么官方文档docs/docs/plugins/mixins/api.md明确指出The APICallMixin class provides basic functionality for integration with an external API.即为插件提供与外部 API 集成的基础能力。它的定位是“脚手架”——你只需要声明“外部服务的地址存哪个设置、Token 存哪个设置”其余 URL 拼接、请求头构造、JSON 序列化、响应解析都由 Mixin 完成。在源码中它位于 src/backend/InvenTree/plugin/base/integration/APICallMixin.py底层使用 Python 生态标准的requests库并通过structlog接入 InvenTree 的统一日志体系。2. 五步接入法官方推荐流程Mixin 类文档字符串APICallMixin.py给出了明确的接入步骤继承顺序将APICallMixin放在SettingsMixin和InvenTreePlugin之前左侧声明设置项用SettingsMixin定义两个设置分别存放外部服务的 URL 与 Token/密码绑定设置键通过API_URL_SETTING和API_TOKEN_SETTING指向第 2 步设置项的键名可选指定请求头键名API_TOKEN指定外部 API 期望的 Token 请求头名称默认Bearer可选覆盖属性需要扩展 URL 或追加请求头时重写api_url/api_headers。完成上述声明后插件代码中即可通过self.api_call(...)发起请求。Mixin 注册机制在__init__中Mixin 会调用self.add_mixin(PluginMixinEnum.API_CALL, has_api_call, __class__)APICallMixin.py注册键名为api_call见 plugin.py 中的PluginMixinEnum.API_CALL api_call。这意味着框架能在插件元信息中识别“该插件具备 API 调用能力”并可用于运行期能力检查。就绪校验has_api_callhas_api_call属性APICallMixin.py负责检查配置是否完整未定义API_URL_SETTING→ 抛出MixinNotImplementedError(API_URL_SETTING must be defined)未定义API_TOKEN_SETTING→ 抛出MixinNotImplementedError(API_TOKEN_SETTING must be defined)。对应测试见 test_mixins.py缺失任一配置的插件在调用has_api_call()时都会被拒绝加载。3. 最小可运行示例SampleApiCallerPlugin官方文档的示例插件即仓库内的 src/backend/InvenTree/plugin/samples/integration/api_caller.py完整代码如下Sample plugin for calling an external API. from plugin import InvenTreePlugin from plugin.mixins import APICallMixin, SettingsMixin class SampleApiCallerPlugin(APICallMixin, SettingsMixin, InvenTreePlugin): A small api call sample. NAME Sample API Caller SETTINGS { API_TOKEN: { name: API Token, protected: True, default: reqres-free-v1, }, API_URL: { name: External URL, description: Where is your API located?, default: api.example.com, }, } API_URL_SETTING API_URL API_TOKEN_SETTING API_TOKEN API_TOKEN x-api-key def get_external_url(self): Returns data from the sample endpoint. return self.api_call(api/users/2)关键点拆解继承顺序APICallMixin, SettingsMixin, InvenTreePlugin与官方要求完全一致SETTINGS字典API_TOKEN被标记为protected: True表明 Token 属于敏感值InvenTree 后台对其做脱敏处理不展示明文API_URL提供description说明用途并给出默认值API_URL_SETTING API_URL告诉 Mixin 去get_setting(API_URL)取地址API_TOKEN_SETTING API_TOKEN告诉 Mixin 去get_setting(API_TOKEN)取凭证API_TOKEN x-api-key将 Token 以x-api-key请求头发送给外部服务见下文请求头构造逻辑get_external_url()业务方法调用self.api_call(api/users/2)即可访问{base_url}/api/users/2。该示例插件的回归测试见 src/backend/InvenTree/plugin/samples/integration/test_api_caller.py测试断言插件以 slugsample-api-caller注册进registry.plugins并能在 mock 的https://api.example.com/api/users/2端点返回{data: sample}。4. 类属性与动态属性详解4.1 类级常量默认值属性默认值含义API_METHODhttpsURL 协议前缀默认走 HTTPSAPI_URL_SETTINGNone指向外部服务地址的设置键必须定义API_TOKEN_SETTINGNone指向凭证的设置键必须定义API_TOKENBearer发送凭证时使用的请求头名称其中API_URL_SETTING/API_TOKEN_SETTING为None时has_api_call会直接抛错API_TOKEN默认Bearer即默认按标准 OAuth/Bearer 风格发送。4.2 api_url基础地址属性property def api_url(self): Base url path. return f{self.API_METHOD}://{self.get_setting(self.API_URL_SETTING)}见 APICallMixin.py。它把协议与API_URL_SETTING指向的设置值拼成https://api.example.com这样的基址。若设置值本身已含协议前缀如测试中的https://api.example.com可通过重写api_url属性绕过默认拼接——测试 test_mixins.py 即示范了这一做法。4.3 api_headers默认请求头property def api_headers(self): headers {Content-Type: application/json} if getattr(self, API_TOKEN_SETTING, None): token self.get_setting(self.API_TOKEN_SETTING) if token: headers[self.API_TOKEN] token headers[Authorization] f{self.API_TOKEN} {token} return headers见 APICallMixin.py。默认行为固定携带Content-Type: application/json若配置了 Token 且非空则同时发送两个头{API_TOKEN}: {token}示例中即x-api-key: reqres-free-v1Authorization: {API_TOKEN} {token}即Bearer token或x-api-key token风格。测试 test_mixins.py 验证了 POST 请求携带Authorization: x-api-key sample-free-v1与Content-Type: application/json。需要额外头如 Accept、自定义 Trace-ID时重写api_headers并调用父类实现再扩展即可。5. api_call统一请求入口api_call()APICallMixin.py是所有请求的统一入口其完整签名与语义如下参数类型默认值说明endpointstr必填端点路径若endpoint_is_urlTrue则为完整 URLmethodstrGETHTTP 方法需大写如POSTurl_argsdictNone追加到 URL 的查询参数自动拼接为?kvk2v2dataAnyNone请求体数据URL 编码表单方式发送jsonAnyNone请求体数据JSON 序列化后发送headersdictNone自定义请求头为None时使用self.api_headerssimple_responseboolTrue为True时直接返回response.json()解析结果endpoint_is_urlboolFalse为True时不拼接self.api_urlendpoint即完整 URL**kwargs——透传给底层requests.request如timeout、verify5.1 内部处理流程拼接查询参数url_args非空时调用api_build_url_args()生成?keyvalue...追加到 endpoint确定请求头未显式传headers时使用self.api_headers确定目标 URLendpoint_is_url为真则直接使用否则自动去掉 endpoint 开头的/拼成{self.api_url}/{endpoint}数据互斥校验data与json同时传入时抛出ValueError(You can either passdataorjsonto this function.)序列化json参数经json_pkg.dumps(json)序列化后写入data发送请求requests.request(method, urlurl, **kwargs)返回结果simple_responseTrue返回 JSON 解析后的对象否则返回原始Response。最简用法类文档注释中的示例self.api_call(hello) # GET {base_url}/hello自动携带 Token5.2 api_build_url_args查询参数编码见 APICallMixin.py。它把字典转成查询串且可迭代值列表/元组非字符串会自动用逗号连接。测试 test_mixins.py 覆盖了各类输入api_build_url_args({a: abc123}) # ?aabc123 api_build_url_args({a: 1}) # ?a1 api_build_url_args({a: b, c: 42}) # ?abc42 api_build_url_args({a: b, c: [d, efgh, 1337]}) # ?abcd,efgh,13375.3 完整调用示例综合用法以下调用方式在 test_mixins.py 中被逐一验证# GET 查询参数请求 https://api.example.com/repos/inventree/InvenTree/stargazers?page2 self.api_call(repos/inventree/InvenTree/stargazers, url_args{page: 2}) # POST JSON 请求体 完整 URL self.api_call( https://api.example.com/users/, json{name: morpheus, job: leader}, methodPOST, endpoint_is_urlTrue, ) # GET 前导斜杠会被自动去掉 self.api_call(/orgs/inventree, simple_responseFalse) # 自定义请求头与透传 kwargs如超时控制 self.api_call(api/users/2, headers{Accept: application/json}, timeout10)6. 实战要点与注意事项6.1 凭证安全务必在SETTINGS中为 Token 设置protected: TrueInvenTree 后台会将其作为受保护值处理避免明文泄露get_setting()/set_setting()来自SettingsMixinSettingsMixin.py插件的设置项会持久化存储可在后台“插件设置”页面动态修改无需改代码。6.2 错误与异常语义MixinNotImplementedErrorAPI_URL_SETTING/API_TOKEN_SETTING缺失时抛出说明插件配置不完整ValueErrordata与json同时传入时抛出HTTP 错误Mixin 默认不吞错simple_responseTrue时返回的是response.json()结果即使状态码非 2xx需在业务方法中自行判断simple_responseFalse时可拿到完整Response对象检查status_code测试 test_mixins.py 展示了 400/404 场景。6.3 与其它 Mixin 的协作APICallMixin常与以下 Mixin 组合使用SettingsMixin必备搭档提供设置项定义与get_setting/set_setting存储机制ScheduleMixin配合定时任务周期性地轮询外部 APIEventMixin在库存变化、订单状态变更等事件中触发外部同步。6.4 使用前注意事项本 Mixin 依赖外部服务可访问性实际部署时请结合 InvenTree 的代理/网络配置见 docs/docs/start/processes.md示例中的api.example.com为占位地址接入真实服务时请替换为实际域名插件启用与否由 InvenTree 插件注册中心registry统一管理示例测试即通过registry.plugins[sample-api-caller]获取插件实例test_api_caller.py。7. 小结APICallMixin用声明式配置 单一入口api_call()把“插件 ↔ 外部 API”集成成本降到最低开发者只需定义两个设置项并绑定键名即可获得自动 URL 拼接、Token 注入、JSON 序列化与响应解析能力。建议读者以 api_caller.py 为模板起步参考 test_mixins.py 的测试用例理解各参数边界行为正式对接第三方服务时按外部 API 文档重写api_url/api_headers并通过url_args、json、timeout等参数精细化控制请求。【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考