# Python服务开发

# 1. 服务开发者前言

● 生成依赖命令：如果需要获取当前服务所涉及的依赖库命令行为：pipreqs . --force

● 服务命名规则：小写字母加下划线形式，严禁用特殊符号如：“+”，“$"等

● 方法命名规则：小写字母加下划线形式，严禁用特殊符号如：“+”，“$"等

● 文件的命名规则：英文字母、数字及下划线，严禁特殊符号“+”，“$"以及中文等

# 2. 下载

# 2.1. 下载脚手架工程

is3_plugin_pro.zip

# 2.2. 下载底座sdk：

is3_python_sdk（下面命令也可将sdk进行版本更新）

pip install is3_python_sdk --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple

# 2.3. is3_python_sdk内置接口说明

is3_python_sdk内置接口说明

# 2.4. prjId获取

在数字底座开放-》平台中获取》场景预览

# 3. 脚手架工程介绍

脚手架工程打开方式：通过pycharm、vscode等应用直接打开该脚手架即可；切勿将该工程作为二级或者更深层级打开（确保配置文件能够被正确读取，如下图工程名is3_plugin_pro 必须位于最顶层）。

● load_config.py：【无需改动无需关注】

● local_config.yaml：配置文件

● test_app.py：【本地测试运行，可脱离流程] 可运行文件，无需依赖任务流程执行本地自定义算法逻辑

● local_app.py：【本地测试运行，必须依赖流程，无需改动】可运行文件，启动类，执行需依赖所配置的任务流程

● app_local_flow.py：【执行一次任务流，必须依赖流程】可运行文件，可执行一次任务流，并返回一个任务流实例执行编码。

● app.py：【仅用于打包exe文件，无法运行，无需更改】

● execute_custom.py：【**核心，**自定义代码编辑处】不可运行文件，您自定义的数据分析、处理等程序，该程序主要作用是，获取流程中的上一节点数据以及自身插件的配置，自定义算法逻辑，并将结果返回。

● requirements.txt：工程所依赖的库，可通过下面命令行生成

pipreqs . --force

介绍：下面将对工程中一些文件进行介绍，当然仅涉及您开发需要改动的文件，无需改动的文件您无需理解相关逻辑，感兴趣可以通过debug模式调试查看逻辑：

# 3.1. local_config.yaml文件介绍

● 该文件中，您仅需要关注以下几点：

○ plugin-code：组件编码，基于您已在底座平台完成自定义插件的注册，plugin-code获取方式见组件注册 (opens new window)

○ key：用于权限，获取方式见认证鉴权 (opens new window)

# 3.2. test_app.py文件介绍

● 该文件中，您仅需要关注以下几点：

○ 该文件主要用于本地测试您的代码逻辑，当然您也可以添加任何代码之前直接执行，你将能够看到控制台打印样例数据

○ exampleData为样例数据

○ prjId：项目id，本地测试需要查询底座数据时使用，如果您需要获取底座，prjId获取方式见目录【2.4 prjId获取】

# 3.3. execute_custom.py文件介绍

● 该文件中，您仅需要关注以下几点:

○ 该文件主要您的代码编程核心部分，最终需要一个结果输出，用result接收（已定义）

○ 图中1：获取流程中传入的数据以及配置信息

获取上一个节点的数据，存储在pre_node_data中，数据格式为 array[dict]

获取流程中自定义插件配置信息：存储在plugin_data_config中，数据格式为 (dict)

将结果返回到自定义插件中：result 变量用于获取您的程序中的返回值，result数据格式为 array[dict]

○ 图中2：可调用底座接口，如获取数据，上传文件等等，接口详情可查看[is3_python_sdk内置接口说明 ]

○ 图中3：该位置是您算法逻辑的起点

○ 图中4：结果返回，数据通过您的算法得到的结果，注意，结果返回格式需要时array[dict]，您需要自行构建

# 3.4. app_local_flow.py文件介绍

● 该文件中，您需要关注以下几点：

○ 该文件是一个接口调用，用于执行一次任务流程，这必须基于您已在底座平台完成自定义插件的注册以及流程的配置

○ prjId：项目id，本地测试需要查询底座数据时使用，如果您需要获取底座，prjId获取方式见【2.4 prjId获取】

○ customCode：任务流程编码，获取方式如下

○ json：请求体

json = {
    "customCode": "tkMUD2",   #  任务流编码，基于您已在底座平台完成 自定插件的注册以及流程的配置如下图
    "data": [{
        "year": 2023    # 如同样例数据，将数据发送任务流程中，最终会流转到您本地服务中
    }]
}

# 4. 如何应用脚手架工程

# 4.1. 如果你仅仅需要调试您的代码逻辑，不接入iS3底座数据、不接入任务流程

● 前要：涉及的文件：test_app.py、 execute_custom.py

○ 在execute_custom.py编写您的代码逻辑

○ 运行test_app.py进行测试，该文件中的样例数据即为您输入的数据，见目录【3.1 test_app.py文件介绍】

# 4.2. 如果你仅仅需要调试您的代码逻辑、不接入任务流程、依赖底座数据

● 前要：涉及的文件：test_app.py、 execute_custom.py

○ 在execute_custom.py编写您的代码逻辑

如果您需要获取底座数据，您可以通过下面方式调用底座接口

from is3_python_sdk.data_query import iS3PythonApi

is3Api = iS3PythonApi(dataDto.headers, self.iS3Addr, dataDto.prjId)dataDto.prjId)
query = {} # 请求数据体
response1 = is3Api.getMetaTableList(query)

○ 运行test_app.py进行测试，该文件中的样例数据即为您输入的数据，见目录【3.1 test_app.py文件介绍】

# 4.3. 如果你需要调试您的代码逻辑，接入任务流程、依赖底座数据

● 前要：涉及的文件local_config.yaml、local_app.py、execute_custom.py、app_local_flow.py

○ 通过4.1得到结果符合您的预期，且输出结果满足格式 [{}]

○ 注册您的自定义组件，进入底座平台操作，具体操作见【组件注册 (opens new window)】

○ 基于自定义组件配置任务流程，具体操作见【配置任务流程 (opens new window)】

○ local_config.yaml需要进行相对应的配置，详情见目录【3.1 local_config.yaml文件介绍】

○ 4.1得到结果符合您的预期，execute_custom.py无需改动

○ 运行 local_app.py，会打印正在等待数据，调试阶段请勿关闭该程序

成功执行结果如下：

○ 上一步执行无错误打印，执行app_local_flow.py，执行具体见目录【3.4 app_local_flow.py文件介绍】

成功执行结果如下：

# 4.4. 如果你需要自定义一些配置，您可以通过下面方式进行读取

例如：您需要读取本机上某个文件，您可以自定义一个名字，如：library-path，后面跟上您的文件全路径即可

程序中读取方式：

from config.load_config import load_local_config

config = load_local_config()
library_path = config['library-path']

# 5. 如何将该该工程打包成exe的可执行文件

【注意】打包时候execute_custom.py文件下必须使用 self.config = load_exe_config()，将 self.config = load_local_config()注释掉并引入下面包

from is3_python_sdk.utils import load_exe_config

# 5.1. 打包成exe文件命令

执行后该工程下dist目录会生成app.exe

 pyinstaller --onefile .\app.py

# 6. 测试app.exe文件

【注意】执行app.exe文件之前，与app.exe同级目录下必须创建一个 config.yaml（文件名必须config.yaml）文件，该文件内容等同项目下config文件下的 local_config.yaml

● 进入磁盘app.exe所在目录，双击执行，成功启动页面如下

● 启动任务流，执行app_local_flow.py，成功页面如下

● 数据接入，成功页面如下

至此你已完成一个服务的开发并将其封装成一个exe文件，支持跨机器部署，如果你想在其他机器上部署，你只需要将app.exe以及config.yaml复制到任何一台机器上，执行即可（需要注意的是：一个注册组件所打包的exe文件，确保有且仅有一个在执行）。

← 四、数字孪生 API文档 →