このページの内容

API概要

ProcessMind APIの呼び出し方法

このガイドでは、データの取得、情報の送信、ワークフローの自動化を行うためにProcessMind APIを呼び出す際の例とベストプラクティスを紹介します。

リクエスト/レスポンス形式を含むエンドポイントの完全なドキュメントについては、APIリファレンスを参照してください。

追加の例とクライアントライブラリについては、GitHubのAPIドキュメントを参照してください。

APIベースURL

すべてのAPIリクエストは、次のURLに送信してください:

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

APIキーはProcessMindアカウント設定から取得できます。手順については、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
});

**注:**本文のロールフィールド(isAdminInTenantaccessisDashboardViewer)は、記載された値どおりに適用されます。ユーザー管理エンドポイントはテナント管理者向けの全機能を備えているため、管理権限を委ねてもよい信頼できる呼び出し元にのみ、書き込み権限付きのAPIキーを発行してください。System APIから招待メールは送信されません。ユーザーのオンボーディングはお客様の責任で行ってください。

ファイルのアップロード

ProcessMindにファイルをアップロードする一般的な流れは次のとおりです:

  1. getPresignedUploadUrl呼び出しを使って署名付きURLを取得します。
  2. ファイルの内容を指定して、そのURLにPUTリクエストを送信します。
  3. 署名付き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を取得してください。
  • apiKeyは常に安全に管理し、クライアント側(公開フロントエンドなど)に公開しないでください。

完全な例

以下では、さまざまな言語でそのままコピー&ペーストして使える完全な例を紹介します。

Bashの例:ファイルのアップロード

2回のcurl呼び出しでProcessMindにファイルをアップロードする最小限のBashスクリプトです。すべての値にプレースホルダーが用意されています。

BASH例をダウンロード

Node.jsの例:ローカルCSVファイルのアップロード

署名付きURLを使って、ローカルCSVファイルをProcessMindにアップロードします。

手順:

  1. APIから署名付きアップロードURLを取得します。
  2. ローカルファイルをディスクから読み込みます。
  3. HTTP PUTを使って、署名付きURLにファイルをアップロードします。

設定:

  • uploadFile()の呼び出し時に、APIキー、tenantId、datatableId、filePathを指定します。
  • APIベースURLはhttps://api.processmind.comに設定されています。
NodeJS例をダウンロード

Pythonの例:ローカルCSVファイルのアップロード

署名付きURLを使って、ローカルCSVファイルをリモートAPIにアップロードします。

手順:

  1. APIから署名付きアップロードURLを取得します。
  2. ローカルファイルをディスクから読み込みます。
  3. HTTP PUTを使って、署名付きURLにファイルをアップロードします。

設定:

  • 必要に応じて、api_key、tenant_id、datatable_id、file_pathを更新します。
Python例をダウンロード

ページネーション

一覧エンドポイントはlimitoffsetのクエリパラメーターを受け付け、ラッパーのない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サンプルリポジトリでIssueを作成してください。