本页内容

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

身份验证

所有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密钥。System 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

下载NodeJS示例

/**
 * 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
`offset`	整数	`0`	无

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

如需分页获取全部内容，请持续使用offset += limit发起请求，直到响应数组短于请求的limit（或为空）。超过最大值的参数会被400拒绝。版本化数据端点（数据集、数据表、版本和Webhook）遵循相同约定。

版本管理与弃用

所有路由均在/v1下进行版本管理；破坏性变更会在新版本中发布，而不会静默更改/v1。
弃用信息会在变更日志和本页面中公布，且至少提前6个月通知路由移除；在此期间，已弃用路由仍可正常使用。
已弃用路由的响应会携带Sunset标头，其中包含移除日期，并包含Deprecation: true。
主要的客户端可见变更始终会列入变更日志；在升级固定版本的API客户端前，请订阅更新或返回查看。

后续步骤

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

info

如果您对API有疑问或需要帮助，请联系支持团队，或在API示例代码仓库中提交问题。

API概览

如何调用ProcessMind API

API基础URL

身份验证

状态码

关键概念

您可以执行的操作

常见示例

获取预签名上传URL

列出数据集

获取租户信息

创建流程

上传BPMN模型

将数据映射到流程

向租户添加用户

上传文件

完整示例

Bash示例：上传文件

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

Python示例：上传本地CSV文件

分页

版本管理与弃用

后续步骤

相关文档

API文档

API密钥

API参考：组织

API参考：租户

API概览

如何调用ProcessMind API

API基础URL

身份验证

状态码

关键概念

您可以执行的操作

常见示例

获取预签名上传URL

列出数据集

获取租户信息

创建流程

上传BPMN模型

将数据映射到流程

向租户添加用户

上传文件

完整示例

Bash示例：上传文件

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

Python示例：上传本地CSV文件

分页

版本管理与弃用

后续步骤

相关文档

API文档

API密钥

API参考：组织

API参考：租户

我们重视您的隐私