ภาพรวม API

วิธีเรียก API ของ ProcessMind

คู่มือนี้มีตัวอย่างและแนวทางปฏิบัติที่ดีสำหรับเรียกใช้ ProcessMind API เพื่อดึงข้อมูล ส่งข้อมูล หรือทำเวิร์กโฟลว์ให้เป็นอัตโนมัติ.

ดูเอกสาร API ของทุก endpoint พร้อมรูปแบบ request/response ได้ที่เอกสารอ้างอิง API.

ดูตัวอย่างเพิ่มเติมและไลบรารีสำหรับไคลเอนต์ได้ที่เอกสาร API บน GitHub.

URL หลักของ API

ส่งคำขอ API ทั้งหมดไปที่:

https://api.processmind.com

ทุก route จะอยู่ภายใต้เวอร์ชัน /v1 ดูข้อกำหนด API ฉบับเต็มที่เครื่องอ่านได้ (OpenAPI 3.1) ได้ที่:

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

การยืนยันตัวตน

คำขอ API ทั้งหมดต้องมี API key ในส่วนหัว x-api-key ยกเว้นเอกสาร OpenAPI สาธารณะ (/v1/openapi.json) และ MCP OAuth endpoints:

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

คุณดูคีย์ API ได้จากการตั้งค่าบัญชี ProcessMind ดูวิธีทำได้ที่การรับคีย์ API.

รหัสสถานะ

API ของ ProcessMind ใช้รหัสสถานะ HTTP มาตรฐาน:

แนวคิดสำคัญ

• apiKey: โทเค็นยืนยันตัวตนสำหรับคำขอ API ทั้งหมด
• tenantId: ระบุบริบทของพื้นที่ทำงานหรือองค์กร ดูได้จากการตั้งค่าบัญชี
• datatableId: ระบุตารางข้อมูลที่ต้องการใช้ดำเนินการด้านข้อมูล ดูได้จากตัวเลือกดู ID ตารางข้อมูลในเมนูการตั้งค่าชุดข้อมูลของ ProcessMind.

สิ่งที่ทำได้

API ของ ProcessMind ช่วยให้คุณทำสิ่งต่อไปนี้ได้:

• จัดการ Tenant: เรียกดูข้อมูล Tenant อัปเดตการตั้งค่า และดูสถิติ
• จัดการผู้ใช้: เพิ่ม อัปเดต หรือลบผู้ใช้ออกจาก Tenant และองค์กร
• จัดการกระบวนการ: สร้างกระบวนการ อัปโหลดโมเดล 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=…

แสดงรายการชุดข้อมูล

ดึงชุดข้อมูลทั้งหมดใน Tenant ของคุณ:

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

รับข้อมูล Tenant

ดึงรายละเอียดเกี่ยวกับ Tenant ของคุณ:

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

สร้างกระบวนการ

สร้างกระบวนการใหม่ใน Tenant ของคุณ:

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
});

เพิ่มผู้ใช้ใน Tenant

เพิ่มผู้ใช้ใน Tenant ของคุณ:

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

หมายเหตุ: ระบบจะใช้ค่าฟิลด์ Role ใน body ตามที่ระบุทุกประการ (isAdminInTenant, access, isDashboardViewer) endpoint สำหรับการจัดการผู้ใช้ใช้จัดการ Tenant ในระดับผู้ดูแลระบบได้ทั้งหมด ดังนั้นควรออก API key ที่มีสิทธิ์เขียนให้เฉพาะผู้ที่คุณไว้วางใจให้ควบคุมการดูแลระบบเท่านั้น System API จะไม่ส่งอีเมลเชิญ คุณต้องดำเนินการเริ่มต้นใช้งานให้ผู้ใช้เอง.

อัปโหลดไฟล์

ขั้นตอนทั่วไปในการอัปโหลดไฟล์ไปยัง ProcessMind มีดังนี้:

1. รับ URL ที่ลงนามล่วงหน้าผ่านการเรียกgetPresignedUploadUrl ส่งคำขอ PUT ไปยัง URL นั้นพร้อมเนื้อหาไฟล์2. URL ที่ลงนามล่วงหน้าอนุญาตให้อัปโหลดไปยังพื้นที่จัดเก็บบนคลาวด์ได้โดยตรง ไม่ต้องใช้ข้อมูลรับรองเพิ่มเติม3. .

ตัวอย่างแบบย่อที่ใช้ 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
	});
}

ตัวอย่างฉบับเต็ม

ด้านล่างเป็นตัวอย่างฉบับสมบูรณ์ที่พร้อมคัดลอกไปใช้ในภาษาต่างๆ.

ตัวอย่าง Bash: อัปโหลดไฟล์

สคริปต์ Bash แบบสั้นสำหรับอัปโหลดไฟล์ไปยัง ProcessMind โดยใช้คำสั่ง curl สองครั้ง พร้อมตัวแทนค่าทุกจุด

#!/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 ในเครื่อง

อัปโหลดไฟล์ CSV ในเครื่องไปยัง ProcessMind โดยใช้ URL ที่ลงนามล่วงหน้า.

ขั้นตอน:

1. เรียก URL สำหรับอัปโหลดที่ลงนามไว้ล่วงหน้าจาก API
2. อ่านไฟล์จากดิสก์ในเครื่อง
3. อัปโหลดไฟล์ไปยัง URL ที่ลงนามไว้ล่วงหน้าโดยใช้ HTTP PUT

การกำหนดค่า:

• เมื่อเรียก uploadFile() ให้ระบุ API key, tenantId, datatableId และ filePath
• กำหนด URL หลักของ API เป็น https://api.processmind.com

/**
 * 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 ในเครื่อง

อัปโหลดไฟล์ CSV ในเครื่องไปยัง API ระยะไกลโดยใช้ URL ที่ลงนามล่วงหน้า.

ขั้นตอน:

1. เรียก URL สำหรับอัปโหลดที่ลงนามไว้ล่วงหน้าจาก API
2. อ่านไฟล์จากดิสก์ในเครื่อง
3. อัปโหลดไฟล์ไปยัง URL ที่ลงนามไว้ล่วงหน้าโดยใช้ HTTP PUT

การกำหนดค่า:

• แก้ไข api_key, tenant_id, datatable_id และ file_path ตามต้องการ

"""
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.")

การแบ่งหน้า

Endpoint สำหรับแสดงรายการรับพารามิเตอร์ query limit และ offset แล้วส่งกลับอาร์เรย์ JSON โดยตรง (ไม่มี envelope และไม่มีจำนวนรายการทั้งหมด):

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

หากต้องการเรียกดูข้อมูลทั้งหมดทีละหน้า ให้ส่งคำขอซ้ำโดยใช้offset += limitจนกว่าอาร์เรย์ใน response จะมีรายการน้อยกว่าค่าlimitที่ร้องขอ (หรือไม่มีรายการ) ระบบจะปฏิเสธค่าที่เกิน ค่าสูงสุดด้วย400 endpoint ข้อมูลที่มีเวอร์ชัน (ชุดข้อมูล เวอร์ชัน และ webhook) ใช้รูปแบบเดียวกัน ส่วนรายการตารางข้อมูลทั้งสองรายการจำกัดlimitไว้ที่ 250.

การกำหนดเวอร์ชันและการเลิกใช้งาน

• ทุก route ใช้เวอร์ชันภายใต้/v1 การเปลี่ยนแปลงที่ทำให้ใช้งานร่วมกันไม่ได้จะออกในเวอร์ชันใหม่ แทนการเปลี่ยน/v1โดยไม่แจ้งให้ทราบ
• การเปลี่ยนแปลงและการยกเลิก route จะแจ้งไว้ในบันทึกประจำรุ่น
• การเปลี่ยนแปลงสำคัญที่ผู้ใช้ไคลเอนต์เห็นได้จะแจ้งไว้ในบันทึกการเปลี่ยนแปลงเสมอ สมัครรับข่าวสารหรือตรวจสอบก่อนอัปเกรดไคลเอนต์ API ที่ตรึงเวอร์ชันไว้.

ขั้นตอนถัดไป

• เอกสารอ้างอิง API: เอกสาร endpoint ทั้งหมด พร้อมรูปแบบ request/response
• ตัวอย่างบน GitHub: ดาวน์โหลดตัวอย่างและไลบรารีสำหรับ client
• วิธีรับ API Key: วิธีรับและจัดการ API key ของคุณ