本页内容

API概览

如何调用ProcessMind API

本指南提供示例和最佳实践，介绍如何调用ProcessMind API来获取数据、提交信息或自动执行工作流。

如需查看包含请求和响应格式的完整端点文档，请参阅API参考。

如需更多示例和客户端库，请访问GitHub上的API文档。

API基础URL

所有API请求均应发送至：

https://api.processmind.com

所有路由均使用/v1版本管理。完整的机器可读API规范（OpenAPI 3.1）可在此处获取：

GET https://api.processmind.com/v1/openapi.json

身份验证

除公开的OpenAPI文档（/v1/openapi.json）和MCP OAuth端点外，所有API请求都必须在x-api-key标头中提供您的API密钥：

x-api-key: your-api-key-here

您可以在ProcessMind账户设置中获取API密钥。操作说明请参阅获取API密钥。

状态码

ProcessMind API采用标准HTTP状态码：

状态码	含义
`200 OK`	请求成功
`201 Created`	资源已创建
`204 No Content`	请求成功，无响应正文
`400 Bad Request`	请求无效，或参数缺失/无效
`401 Unauthorized`	API密钥缺失或无效
`403 Forbidden`	已通过身份验证，但无权执行此操作
`404 Not Found`	资源不存在
`500 Internal Server Error`	意外的服务器错误

关键概念

apiKey：所有API请求使用的身份验证令牌。
tenantId：标识您的工作空间/组织范围，可在账户设置中找到。
datatableId：标识用于数据操作的特定数据表。您可以在ProcessMind数据集设置菜单的获取数据表ID选项中找到。

可执行的操作

ProcessMind API支持您执行以下操作：

管理环境：获取环境信息、更新设置、查看统计数据
管理用户：在环境和组织中添加、更新或删除用户
管理流程：创建流程、上传BPMN模型、整理到文件夹
连接数据：将数据表映射到流程以供分析
上传数据：将CSV/XLSX文件直接上传到数据表
管理数据集：列出、查看和删除数据集及数据表

常见示例

以下实用示例介绍如何使用ProcessMind API执行常见操作。

获取预签名上传URL

如需将文件上传到数据表，请先获取预签名URL：

const presignedUrl = await getPresignedUploadUrl({
	apiKey,
	tenantId: "tenant-123",
	datatableId: "table-456"
});
console.log(presignedUrl); // https://s3.amazonaws.com/…?X-Amz-Signature=…

列出数据集

获取您所在环境中的所有数据集：

const datasets = await getDatasets({
	apiKey,
	tenantId: "tenant-123"
});
console.log(datasets);

获取环境信息

获取您的环境详情：

const tenantInfo = await getTenant({
	apiKey,
	tenantId: "tenant-123"
});
console.log(tenantInfo);

创建流程

在您的环境中创建新流程：

const process = await createProcess({
	apiKey,
	tenantId: "tenant-123",
	displayName: "Order to Cash"
});
console.log(process.id); // Use this ID for subsequent operations

上传BPMN模型

上传BPMN文件以定义流程模型：

const fs = require("fs");
const bpmnXml = fs.readFileSync("./my-process.bpmn", "utf8");

await uploadBpmn({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	bpmnXml
});

将数据映射到流程

将数据表连接到流程以供分析：

const mapping = await createProcessMapping({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	dataTableId: "datatable-789",
	displayName: "Sales Data 2024",
	showByDefault: true
});

向环境添加用户

向您的环境添加用户：

const result = await addTenantUser({
	apiKey,
	tenantId: "tenant-123",
	id: "user-456",
	email: "colleague@example.com",
	isAdminInTenant: false,
	isActiveInTenant: true,
	sendInvitationEmail: true
});

**注意：**正文中的角色字段（isAdminInTenant、access、 isDashboardViewer）将按原值处理。用户管理端点提供完整的环境管理员权限，因此只应向您信任其管理权限的调用方发放具有写入权限的API密钥。系统API不会发送邀请邮件，您需要负责引导用户完成入驻。

上传文件

向ProcessMind上传文件的一般流程如下：

使用getPresignedUploadUrl调用获取预签名URL。
向该URL发送包含文件内容的PUT请求。
预签名URL授权您直接向云存储上传文件，无需其他凭据。

以下是使用fetch的简化示例：

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Obtain a presigned URL
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Step 2: Upload the file via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
}

info

预签名URL会在设定时间后过期（上传和下载默认有效期为一小时）。获取URL后请尽快使用。
如果上传失败（例如网络中断），请重新获取预签名URL后再试。
请妥善保管apiKey，切勿在客户端代码中公开（例如放在公开的前端代码中）。

完整示例

以下提供多种语言的完整示例，可直接复制使用。

Bash示例：上传文件

使用两次curl调用将文件上传到ProcessMind的最简Bash脚本，所有值均为占位符

下载BASH示例

#!/bin/bash
# Minimal Bash script to upload a file to ProcessMind using two curl calls, with placeholders for all values

# Replace the following placeholders with your actual values:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

curl -s -H "x-api-key: <API_KEY>" \
	"https://api.processmind.com/v1/tenant/<TENANT_ID>/datatables/<DATATABLE_ID>/uploads/presigned-url" \
	| grep -oP '"PreSignedUploadUrl"\s*:\s*"\K[^"]+' \
	| xargs -I {} curl -s -X PUT --upload-file "<FILE_PATH>" "{}"

Node.js示例：上传本地CSV文件

使用预签名URL将本地CSV文件上传到ProcessMind。

步骤：

从API获取预签名上传URL。
从磁盘读取本地文件。
使用HTTP PUT将文件上传到预签名URL。

配置：

调用uploadFile()时，请提供您的API密钥、tenantId、datatableId和filePath。
API基础URL设置为https://api.processmind.com

下载Node.js示例

/**
 * Uploads a local CSV file to ProcessMind using a presigned URL.
 *
 * Steps:
 * 1. Fetch a presigned upload URL from the API.
 * 2. Read the local file from disk.
 * 3. Upload the file to the presigned URL using HTTP PUT.
 *
 * Configuration:
 * - Provide your API key, tenantId, datatableId, and filePath when calling uploadFile().
 * - The API base URL is set to https://api.processmind.com
 */

const fs = require("node:fs");

/**
 * Uploads a file to ProcessMind datatable using a presigned URL.
 * @param {string} apiKey - Your API key for authentication.
 * @param {string} tenantId - Your tenant identifier.
 * @param {string} datatableId - Your datatable identifier.
 * @param {string} filePath - Path to the file to upload.
 */

async function getApi({path, apiKey, apiUrl = "https://api.processmind.com"}) {
	try {
        const response = await fetch(`${apiUrl}${path}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey
            }
        });
        const body = await response.json();
        if (!response.ok) {
            console.error(`Error loading from API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

async function getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl = "https://api.processmind.com"}) {
	return (await getApi({apiKey, path: `/v1/tenant/${tenantId}/datatables/${datatableId}/uploads/presigned-url`, apiUrl})).PreSignedUploadUrl;
}

async function getDatasets({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/datasets`, apiUrl});
}

async function getTenant({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}`, apiUrl});
}

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/organization`, apiUrl});
}

async function uploadFile({apiKey, tenantId, datatableId, filePath, apiUrl = "https://api.processmind.com"}) {
    try {
        const uploadUrl = await getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl});

		console.log("Uploading file...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Error reading file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Upload failed:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File uploaded successfully.");
                }
            } catch (uploadErr) {
                console.error("Error uploading file:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

// Export the function for use in other modules
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Python示例：上传本地CSV文件

使用预签名URL将本地CSV文件上传到远程API。

步骤：

从API获取预签名上传URL。
从磁盘读取本地文件。
使用HTTP PUT将文件上传到预签名URL。

配置：

根据需要更新api_key、tenant_id、datatable_id和file_path。

下载Python示例

"""
Uploads a local CSV file to a remote API using a presigned URL.

Steps:
1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:
- Update api_key, tenant_id, datatable_id, file_path as needed.
"""

import requests

# === Configuration ===
api_key = ""  # API key for authentication
tenant_id = ""  # Tenant identifier
datatable_id = ""  # Datatable identifier
file_path = ""  # Path to the file to upload


print("Fetching upload URL...")
api_url = "https://api.processmind.com"  # Base API URL
presign_url = f"{api_url}/v1/tenant/{tenant_id}/datatables/{datatable_id}/uploads/presigned-url"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Error fetching upload URL: {presign_res.status_code}, {presign_res.reason}: {presign_res.text}")
	exit(1)

presign_body = presign_res.json()
upload_url = presign_body.get("PreSignedUploadUrl")
if not upload_url:
	print("No presigned upload URL returned.")
	exit(1)

print("Uploading file...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Upload failed: {upload_res.status_code}, {upload_res.reason}")
else:
	print("File uploaded successfully.")

分页

列表端点接受limit和offset查询参数，并返回纯JSON数组（无封装对象，也不含总数）：

参数	类型	默认值	最大值
`limit`	整数	`100`	1,000（数据表列表为250）
`offset`	整数	`0`	无

GET /v1/tenant/{tenantId}/processes?limit=50&offset=100

如需获取全部结果，请持续使用offset += limit发起请求，直到响应数组长度小于请求的limit（或数组为空）。超过最大值的请求将被拒绝，并返回400。版本化数据端点（数据集、版本、webhook）采用相同规则，两个数据表列表的limit上限为250。

版本管理与弃用

所有路由均使用/v1版本管理；发布破坏性变更时会推出新版本，不会悄然更改/v1。
路由变更和移除会在发行说明中公布。
面向客户端的重大变更都会列入更新日志；升级固定版本的API客户端前，请订阅更新或查看最新信息。

后续步骤

API参考：所有端点的完整文档，包含请求和响应格式
GitHub示例：可下载的示例和客户端库
获取API密钥：了解如何获取和管理API密钥