跳到主要内容

OpenSCOW Protobuf文件

OpenSCOW API和Hook的数据结构和服务都通过Protocol Buffer格式统一定义并分发。要想使用OpenSCOW API和Hook，您需要首先获取proto文件，通过proto文件生成您对应的语言的代码，然后才能进行开发。

获取Proto文件​

我们将OpenSCOW API和Hook的proto文件放到了代码仓库中，您可以直接从代码仓库中获取。代码仓库中protos目录下则为proto文件：master分支protos目录链接

proto文件分为common, portal, server, audit和hook。其中，

  • common中定义了公用的数据结构
  • portal定义了门户系统的OpenSCOW API。portal-server门户系统后端实现了portal中定义的服务，您可以通过portal下的文件与portal-server交互
  • server定义了管理系统的OpenSCOW API。mis-server管理系统后端实现了server中定义的服务，您可以通过server下的文件与mis-server交互
  • audit定义了审计系统的OpenSCOW API。audit-server审计系统系统后端实现了audit中定义的服务，您可以通过audit下的文件与audit-server交互
  • hook定义了OpenSCOW Hook的事件和服务。portal-server和mis-server将会通过hook下的文件与您配置的OpenSCOW Hook服务器交互

除了直接从代码仓库中获取，我们更推荐使用工具获取Protobuf文件。您可以通过以下方式获取到OpenSCOW的Protobuf文件

1. 使用Buf获取和生成代码（推荐）​

Buf是一个管理gRPC API和proto文件的一站式工具，可完成获取文件、生成代码等常见功能。我们推荐通过使用Buf直接从GitHub上获取代码并生成您的语言的模板的代码的工作。

# 使用本地buf.gen.yaml生成模板，使用v0.3.0版本的OpenSCOW API(v0.3.0开始可以通过此方式，推荐)
buf generate --template buf.gen.yaml https://github.com/PKUHPC/OpenSCOW.git#subdir=protos,branch=api-v0.3.0

# 使用本地buf.gen.yaml生成模板，使用OpenSCOW仓库的master分支的代码对应的OpenSCOW API
buf generate --template buf.gen.yaml https://github.com/PKUHPC/OpenSCOW.git#subdir=protos,branch=master

详细的示例请参考：

2. 通过npm获取proto文件​

您可以通过npm从npmjs.org上获取任意版本的proto文件

# 最新版本的API文件
npm install -g @scow/grpc-api

# 特定版本(0.1.2)的API
npm install -g @scow/grpc-api@0.1.2

# 安装好后，可以去npm的全局模块的目录中查找到这个包，并获取内部的文件
cd $(npm root -g)/@scow/grpc-api

# 如果您使用npm对您的项目进行依赖管理，则可以在您的项目中安装此包，并直接在此包的node_modules中获取到proto文件
npm install --save @scow/grpc-api
cd node_modules/@scow/grpc-api

API版本控制​

我们通过npm以及package.json文件对API版本进行控制。当前的版本为：npm

API的版本通过@scow/grpc-api包的版本进行定义。OpenSCOW gRPC API版本控制原则：

  • 不影响API的修改，例如lint文件：提高PATCH号
  • 修改了API，但是兼容当前的API：提高MINOR号
  • 不兼容已有的配置文件，提高MAJOR版本

当前，我们并不保证新版本OpenSCOW对老版本API的兼容性。OpenSCOW每次发布版本时，会同时公布此版本支持的OpenSCOW API的版本号。