fatsand/JIAP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
03100cab08
JIAP/JIAP_Develop.md
fatsand c036c8c168 first commit
2024-12-19 10:15:23 +08:00

15 KiB
Raw Blame History

九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol, JIAP) 开发文档

JIAP 是“九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol)”的缩写，它定义了一套统一、高效、可扩展的机器人流程自动化（RPA）框架。该协议旨在实现跨多种自动化工具和平台的无缝集成，同时确保与主流标准兼容。

开发文档

九鑫智能自动化协议 (JIAP) 开发文档

目录

  1. 简介
  2. 系统架构
  3. API 设计与通信标准
  4. 模块与方法
  5. 数据模型
  6. 认证与安全
  7. 错误处理
  8. 可扩展性
  9. 示例与使用场景
  10. 常见问题

1. 简介

九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol, JIAP) 提供了一套标准化框架，用于设计、执行和管理 RPA 工作流。目标如下：

  • 实现无缝集成：支持多样化的系统。
  • 简化自动化任务：通过统一的接口执行操作。
  • 确保兼容性：与主流 RPA 平台和协议兼容。

核心特点：

  • 模块化：提供文件操作、数据处理、系统任务等功能模块。
  • 可扩展性：支持动态添加新模块及定制化工作流。
  • 兼容性：支持 RESTful API、WebSocket 等主流协议的集成。
  • 安全性：高级认证机制与加密数据传输。

2. 系统架构

核心组件

  1. RPA 控制器：

    • 负责任务调度、机器人协调及资源分配。
    • 提供外部系统可调用的 API 接口。

  2. 机器人代理：

    • 执行由控制器分配的自动化任务。
    • 与控制器通信，报告任务状态和结果。

  3. 活动模块：

    • 独立的功能单元，例如文件处理、Excel 操作、数据库访问等。
    • 易于扩展，可根据需求添加新功能。

  4. 日志与监控系统：

    • 记录任务执行日志。
    • 提供性能分析与故障排查信息。

3. API 设计与通信标准

3.1 通信协议

  • RESTful API：

    • 基础 URL: https://api.jiuxinai.com/v1/jiap
    • 用于同步任务请求与查询操作。

  • WebSocket：

    • URL: wss://api.jiuxinai.com/ws
    • 支持异步任务执行与实时通信。

3.2 标准请求格式

{
  "method": "<模块>.<操作>",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

3.3 标准响应格式

{
  "status": "success",  // success 或 error
  "message": "操作描述",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

4. 模块与方法

4.1 文件操作模块

方法名 描述 参数
File.Copy 复制文件 source_path, destination_path, overwrite
File.Delete 删除文件 file_path
File.Rename 重命名文件 file_path, new_name
File.ListFiles 列出目录中的文件 directory_path, filter_by_extension

4.2 Excel 操作模块

方法名 描述 参数
Excel.ReadCell 读取 Excel 单元格数据 file_path, sheet_name, cell_name, password
Excel.WriteCell 写入 Excel 单元格数据 file_path, sheet_name, cell_name, value, password
Excel.MergeCells 合并或取消合并单元格 file_path, sheet_name, range_name, action

4.3 网络模块

方法名 描述 参数
Network.HttpGet 执行 HTTP GET 请求 url, headers
Network.HttpPost 执行 HTTP POST 请求 url, headers, body
Network.DownloadFile 下载文件 url, save_path

4.4 OCR 模块

方法名 描述 参数
OCR.ExtractText 从图像中提取文本 image_path
OCR.ExtractFromPDF 从 PDF 中提取文本 pdf_path

4.5 扩展模块

其他模块（如数据库操作、系统命令）可根据需要动态添加。有关详细信息，请参考可扩展性部分。

5. 数据模型

文件元数据模型

{
  "path": "/path/to/file.txt",
  "size": 1024,
  "created_at": "2024-04-01T10:00:00Z",
  "modified_at": "2024-04-28T10:00:00Z"
}

Excel 单元格数据模型

{
  "file_path": "/path/to/excel.xlsx",
  "sheet_name": "Sheet1",
  "cell_name": "A1",
  "value": "123"
}

6. 认证与安全

6.1 认证

  • OAuth 2.0：

    • 使用访问令牌进行 API 请求。
    • 认证端点: https://api.jiuxinai.com/auth/token

  • API 密钥：

    • 简化认证流程，适用于内部场景。

6.2 数据安全

  • 使用 HTTPS 和 WSS 进行加密通信。
  • 敏感数据（如密码）采用行业标准加密存储。

7. 错误处理

标准化错误响应，确保交互可预测且易于调试。

示例错误响应

{
  "status": "error",
  "message": "文件未找到",
  "data": null,
  "timestamp": "2024-04-28T12:00:00Z"
}

8. 可扩展性

添加新模块

  1. 在配置文件中定义模块和方法。
  2. 在后端实现模块逻辑。
  3. 通过控制器公开新模块。

自定义操作

开发者可通过配置文件或脚本添加自定义工作流，从而扩展协议的功能。

9. 示例与使用场景

示例：文件复制操作

请求：

{
  "method": "File.Copy",
  "params": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  }
}

响应：

{
  "status": "success",
  "message": "文件复制成功",
  "data": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

10. 常见问题

  1. 如何进行 API 请求认证？
    使用 OAuth 2.0 令牌或 API 密钥。

  2. JIAP 是否支持主流 RPA 平台集成？
    是的，JIAP 通过 RESTful API 实现了与主流 RPA 工具的兼容。

以上文档为实现和集成 九鑫智能自动化协议 (JIAP) 提供了全面指导。如需更多信息，请联系 九鑫智能技术支持：[xiaoyigong@9xin.ai]。

协议英文名称

JiuXin Intelligent Automation Protocol (JIAP)

JIAP stands for "JiuXin Intelligent Automation Protocol," which defines a unified, efficient, and extensible framework for robotic process automation (RPA). The protocol is designed for seamless integration across various automation tools and platforms while ensuring compatibility with mainstream standards.

开发文档

JiuXin Intelligent Automation Protocol (JIAP) Developer Documentation

Table of Contents

  1. Introduction
  2. System Architecture
  3. API Design and Communication Standards
  4. Modules and Methods
  5. Data Models
  6. Authentication and Security
  7. Error Handling
  8. Extensibility
  9. Examples and Use Cases
  10. FAQ

1. Introduction

JiuXin Intelligent Automation Protocol (JIAP) provides a standardized framework for designing, executing, and managing RPA workflows. It aims to:

  • Enable seamless integration across diverse systems.
  • Simplify automation tasks through a unified interface.
  • Ensure compatibility with mainstream RPA platforms and protocols.

Key Features:

  • Modularity: Functional modules for file operations, data processing, system tasks, etc.
  • Extensibility: Support for adding new modules and customizing workflows.
  • Compatibility: Integration with RESTful APIs, WebSocket, and other widely adopted protocols.
  • Security: Advanced authentication and encrypted data transmission.

2. System Architecture

Core Components

  1. RPA Controller:

    • Manages task scheduling, robot orchestration, and resource allocation.
    • Exposes APIs for external systems to interact with RPA workflows.

  2. Robot Agents:

    • Executes automation tasks assigned by the controller.
    • Communicates with the controller to report task status and results.

  3. Activity Modules:

    • Encapsulated units for performing specific operations (e.g., file handling, Excel processing, database access).
    • Easily extendable to accommodate new requirements.

  4. Logging and Monitoring System:

    • Records task execution logs.
    • Provides insights into performance and troubleshooting information.

3. API Design and Communication Standards

3.1 Communication Protocols

  • RESTful API:

    • Base URL: https://api.jiuxinai.com/v1/jiap
    • Used for synchronous task requests and query operations.

  • WebSocket:

    • URL: wss://api.jiuxinai.com/ws
    • Supports asynchronous task execution and real-time communication.

3.2 Standard Request Format

{
  "method": "<module>.<operation>",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

3.3 Standard Response Format

{
  "status": "success",  // success or error
  "message": "Operation description",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

4. Modules and Methods

4.1 File Operations Module

Method Description Parameters
File.Copy Copy a file source_path, destination_path, overwrite
File.Delete Delete a file file_path
File.Rename Rename a file file_path, new_name
File.ListFiles List files in a folder directory_path, filter_by_extension

4.2 Excel Operations Module

Method Description Parameters
Excel.ReadCell Read data from a cell file_path, sheet_name, cell_name, password
Excel.WriteCell Write data to a cell file_path, sheet_name, cell_name, value, password
Excel.MergeCells Merge or unmerge cells file_path, sheet_name, range_name, action

4.3 Network Module

Method Description Parameters
Network.HttpGet Perform HTTP GET url, headers
Network.HttpPost Perform HTTP POST url, headers, body
Network.DownloadFile Download a file url, save_path

4.4 OCR Module

Method Description Parameters
OCR.ExtractText Extract text from an image image_path
OCR.ExtractFromPDF Extract text from a PDF pdf_path

4.5 Extended Modules

Additional modules such as database operations, system commands, and more can be added dynamically. See the extensibility section for details.

5. Data Models

File Metadata Model

{
  "path": "/path/to/file.txt",
  "size": 1024,
  "created_at": "2024-04-01T10:00:00Z",
  "modified_at": "2024-04-28T10:00:00Z"
}

Excel Cell Data Model

{
  "file_path": "/path/to/excel.xlsx",
  "sheet_name": "Sheet1",
  "cell_name": "A1",
  "value": "123"
}

6. Authentication and Security

6.1 Authentication

  • OAuth 2.0:

    • Obtain access tokens for API requests.
    • Endpoint: https://api.jiuxinai.com/auth/token

  • API Key:

    • Simplified authentication for internal use cases.

6.2 Data Security

  • Encrypted communication using HTTPS and WSS.
  • Sensitive data (e.g., passwords) stored securely using industry-standard encryption.

7. Error Handling

Standardized error responses to ensure predictable and debuggable interactions.

Example Error Response

{
  "status": "error",
  "message": "File not found",
  "data": null,
  "timestamp": "2024-04-28T12:00:00Z"
}

8. Extensibility

Adding New Modules

  1. Define the module and methods in the configuration file.
  2. Implement the module logic in the backend.
  3. Expose the module through the controller.

Custom Operations

Developers can add custom workflows using configuration files or scripts, extending the protocol to meet specific needs.

9. Examples and Use Cases

Example: File Copy Operation

Request:

{
  "method": "File.Copy",
  "params": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  }
}

Response:

{
  "status": "success",
  "message": "File copied successfully",
  "data": {
    "source_path": "/source/file.txt",
    "destination_path": "/destination/file.txt",
    "overwrite": true
  },
  "timestamp": "2024-04-28T12:00:00Z"
}

10. FAQ

  1. How do I authenticate API requests?
    Use OAuth 2.0 tokens or API keys depending on your deployment.

  2. Can I integrate JIAP with other RPA platforms?
    Yes, JIAP is designed to be compatible with mainstream RPA tools through RESTful APIs.

This documentation provides a foundation for implementing and integrating JIAP in a wide range of automation scenarios. For more information, contact JiuXin Intelligent Support at [xiaoyigong@9xin.ai].