テンプレート管理
ノートブックテンプレートの完全なCRUD操作。すべてのエンドポイントはグローバルAPIキーが必要です。
グローバルテンプレートの一覧取得
GET /api/templates
すべてのテナントにわたって利用可能なグローバルテンプレートを返します。
レスポンス (200 OK)
{
"templates": [
{
"templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"name": "Process Discovery",
"description": "標準のプロセス発見ワークフロー",
"category": "Templates",
"processName": "Order to Cash",
"tenantId": null,
"isGlobal": true,
"hasThumbnail": true,
"autoAddedDefaultSortOrder": 100,
"dateModified": "2024-01-15T10:30:00Z"
}
],
"totalCount": 1
}
テナントのテンプレート一覧取得
GET /api/templates/tenant/{tenantId}
グローバルおよびテナント固有のテンプレートを含む、特定のテナントで利用可能なすべてのテンプレートを返します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
tenantId |
GUID | 必須 | テナントの識別子 |
レスポンス (200 OK)
{
"templates": [
{
"templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"name": "Process Discovery",
"description": "標準のプロセス発見ワークフロー",
"category": "Templates",
"processName": "Order to Cash",
"tenantId": null,
"isGlobal": true,
"hasThumbnail": true,
"autoAddedDefaultSortOrder": 100,
"dateCreated": "2024-01-01T00:00:00Z",
"dateModified": "2024-01-15T10:30:00Z",
"createdByName": "System",
"modifiedByName": "System"
},
{
"templateId": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
"name": "Custom Analysis",
"description": "テナント固有のカスタム分析",
"category": "Custom",
"processName": null,
"tenantId": "12345678-1234-1234-1234-123456789012",
"isGlobal": false,
"hasThumbnail": false,
"autoAddedDefaultSortOrder": 0,
"dateCreated": "2024-02-01T09:00:00Z",
"dateModified": "2024-02-15T14:30:00Z",
"createdByName": "API",
"modifiedByName": "API"
}
],
"totalCount": 2
}
カテゴリ別テンプレート一覧取得
GET /api/templates/category/{category}
カテゴリでフィルタリングされたテンプレートを返します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
category |
string | 必須 | カテゴリ名: Templates、Custom、または BaseKnowledge |
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
tenantId |
GUID | なし | 特定テナントのテンプレートに絞る |
例
# カスタムテンプレートをすべて取得
curl -X GET "https://your-mindzie-instance.com/api/templates/category/Custom" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY"
# 特定テナントのカスタムテンプレートを取得
curl -X GET "https://your-mindzie-instance.com/api/templates/category/Custom?tenantId=12345678-1234-1234-1234-123456789012" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY"
テンプレート詳細取得
GET /api/templates/{templateId}
MCL構成テキストを含むテンプレートの全詳細を返します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
templateId |
GUID | 必須 | テンプレートの識別子 |
レスポンス (200 OK)
{
"templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"name": "Process Discovery",
"description": "バリアント分析を含む標準のプロセス発見ワークフロー",
"category": "Templates",
"processName": "Order to Cash",
"mclText": "// ノートブロック＆設定を定義するMCL構成\n{\n \"blocks\": [...],\n \"settings\": {...}\n}",
"tenantId": null,
"isGlobal": true,
"hasThumbnail": true,
"autoAddedDefaultSortOrder": 100,
"originatingNotebookId": null,
"dateCreated": "2024-01-01T00:00:00Z",
"dateModified": "2024-01-15T10:30:00Z",
"createdBy": null,
"createdByName": "System",
"modifiedBy": null,
"modifiedByName": "System"
}
レスポンス項目
| 項目 | 型 | 説明 |
|---|---|---|
templateId |
GUID | ユニーク識別子 |
name |
string | テンプレート名 |
description |
string | テンプレート説明 |
category |
string | カテゴリ（Templates、Custom、BaseKnowledge） |
processName |
string | 関連プロセス名 |
mclText |
string | MCL構成テキスト |
tenantId |
GUID | テナントID（グローバルテンプレートはnull） |
isGlobal |
boolean | グローバルテンプレートかどうか |
hasThumbnail |
boolean | サムネイル画像の有無 |
autoAddedDefaultSortOrder |
integer | 表示の並び順 |
originatingNotebookId |
GUID | 既存ノートブックから作成された場合の元ノートブックID |
dateCreated |
datetime | 作成日時 |
dateModified |
datetime | 最終更新日時 |
createdBy |
GUID | 作成者ユーザーID |
createdByName |
string | 作成者ユーザー名 |
modifiedBy |
GUID | 最終更新者ユーザーID |
modifiedByName |
string | 最終更新者ユーザー名 |
エラー応答
Not Found (404)
{
"error": "Template with ID 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' not found"
}
テンプレートのサムネイル取得
GET /api/templates/{templateId}/thumbnail
テンプレートのサムネイル画像を返します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
templateId |
GUID | 必須 | テンプレートの識別子 |
レスポンス (200 OK)
JPEG画像データを Content-Type: image/jpeg で返します。
エラー応答
Not Found (404)
{
"error": "Thumbnail not found for template 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'"
}
テンプレート作成
POST /api/templates/tenant/{tenantId}
新しいテナント固有テンプレートを作成します。グローバルテンプレートはAPI経由で作成できません。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
tenantId |
GUID | 必須 | テナントの識別子 |
リクエストボディ
{
"name": "Custom Analysis Template",
"description": "月次報告用のカスタム分析ワークフロー",
"mclText": "// MCL構成テキスト",
"category": "Custom",
"processName": "Monthly Report",
"isGlobal": false,
"autoAddedDefaultSortOrder": 0
}
リクエスト項目
| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
name |
string | 必須 | テンプレート名（ユニークである必要があります） |
description |
string | 任意 | テンプレート説明 |
mclText |
string | 必須 | MCL構成テキスト |
category |
string | 任意 | カテゴリ（デフォルト: "Custom"） |
processName |
string | 任意 | 関連プロセス名 |
isGlobal |
boolean | 任意 | API作成時は必ずfalse |
autoAddedDefaultSortOrder |
integer | 任意 | 表示の並び順 |
レスポンス (201 Created)
{
"templateId": "cccccccc-dddd-eeee-ffff-000000000000",
"name": "Custom Analysis Template",
"description": "月次報告用のカスタム分析ワークフロー",
"category": "Custom",
"processName": "Monthly Report",
"mclText": "// MCL構成テキスト",
"tenantId": "12345678-1234-1234-1234-123456789012",
"isGlobal": false,
"hasThumbnail": false,
"autoAddedDefaultSortOrder": 0,
"dateCreated": "2024-03-01T10:00:00Z",
"dateModified": "2024-03-01T10:00:00Z",
"createdByName": "API"
}
エラー応答
Bad Request (400) - バリデーションエラー
{
"error": "Validation failed",
"validationErrors": ["Name is required", "MclText is required"]
}
Conflict (409) - 名前重複
{
"error": "A template with this name already exists"
}
テンプレート更新
PUT /api/templates/{templateId}
既存のテナント固有テンプレートを更新します。グローバルテンプレートはAPI経由で更新できません。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
templateId |
GUID | 必須 | テンプレートの識別子 |
リクエストボディ
{
"name": "Updated Template Name",
"description": "更新された説明",
"mclText": "// 更新されたMCL構成",
"category": "Custom",
"processName": "Updated Process",
"autoAddedDefaultSortOrder": 10
}
すべてのフィールドは任意 - 指定されたフィールドのみ更新されます。
レスポンス (200 OK)
更新後のテンプレート詳細を返します。
エラー応答
Bad Request (400) - グローバルテンプレート
{
"error": "Cannot update global templates through the API"
}
Not Found (404)
{
"error": "Template not found"
}
Conflict (409) - 名前重複
{
"error": "A template with this name already exists"
}
テンプレート削除
DELETE /api/templates/{templateId}
テナント固有のテンプレートを削除します。グローバルテンプレートはAPI経由で削除できません。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
templateId |
GUID | 必須 | テンプレートの識別子 |
レスポンス (200 OK)
{
"message": "Template deleted successfully"
}
エラー応答
Bad Request (400) - グローバルテンプレート
{
"error": "Cannot delete global templates"
}
Not Found (404)
{
"error": "Template not found"
}
実装例
cURL
# テナントのすべてのテンプレート一覧
curl -X GET "https://your-mindzie-instance.com/api/templates/tenant/12345678-1234-1234-1234-123456789012" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY"
# テンプレート詳細取得
curl -X GET "https://your-mindzie-instance.com/api/templates/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY"
# テンプレート作成
curl -X POST "https://your-mindzie-instance.com/api/templates/tenant/12345678-1234-1234-1234-123456789012" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Custom Template",
"description": "Custom analysis workflow",
"mclText": "// MCL configuration",
"category": "Custom"
}'
# テンプレート更新
curl -X PUT "https://your-mindzie-instance.com/api/templates/cccccccc-dddd-eeee-ffff-000000000000" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Name"}'
# テンプレート削除
curl -X DELETE "https://your-mindzie-instance.com/api/templates/cccccccc-dddd-eeee-ffff-000000000000" \
-H "Authorization: Bearer YOUR_GLOBAL_API_KEY"
Python
import requests
BASE_URL = 'https://your-mindzie-instance.com'
TENANT_ID = '12345678-1234-1234-1234-123456789012'
class TemplateManager:
def __init__(self, global_api_key):
self.headers = {
'Authorization': f'Bearer {global_api_key}',
'Content-Type': 'application/json'
}
def list_templates(self, tenant_id=None):
"""テナントでフィルタリング可能なテンプレート一覧取得"""
if tenant_id:
url = f'{BASE_URL}/api/templates/tenant/{tenant_id}'
else:
url = f'{BASE_URL}/api/templates'
response = requests.get(url, headers=self.headers)
response.raise_for_status()
return response.json()
def get_template(self, template_id):
"""MCLテキストを含むテンプレート詳細取得"""
url = f'{BASE_URL}/api/templates/{template_id}'
response = requests.get(url, headers=self.headers)
response.raise_for_status()
return response.json()
def create_template(self, tenant_id, name, mcl_text, description=None, category='Custom'):
"""新規テナント固有テンプレート作成"""
url = f'{BASE_URL}/api/templates/tenant/{tenant_id}'
data = {
'name': name,
'mclText': mcl_text,
'description': description,
'category': category
}
response = requests.post(url, json=data, headers=self.headers)
response.raise_for_status()
return response.json()
def update_template(self, template_id, **kwargs):
"""テンプレート更新。更新するフィールドのみ渡す"""
url = f'{BASE_URL}/api/templates/{template_id}'
response = requests.put(url, json=kwargs, headers=self.headers)
response.raise_for_status()
return response.json()
def delete_template(self, template_id):
"""テナント固有テンプレート削除"""
url = f'{BASE_URL}/api/templates/{template_id}'
response = requests.delete(url, headers=self.headers)
response.raise_for_status()
return response.json()
# 使用例
manager = TemplateManager('your-global-api-key')
# テンプレート一覧取得
templates = manager.list_templates(TENANT_ID)
print(f"{templates['totalCount']}件のテンプレートを取得")
for t in templates['templates']:
print(f" - {t['name']} ({'グローバル' if t['isGlobal'] else 'テナント'})")
# テンプレート作成
new_template = manager.create_template(
tenant_id=TENANT_ID,
name='My Analysis Template',
mcl_text='// MCL configuration here',
description='カスタムワークフロー'
)
print(f"作成されたテンプレートID: {new_template['templateId']}")
# テンプレート更新
updated = manager.update_template(
new_template['templateId'],
name='Renamed Template'
)
# テンプレート削除
manager.delete_template(new_template['templateId'])
print("テンプレートを削除しました")
JavaScript/Node.js
const BASE_URL = 'https://your-mindzie-instance.com';
const TENANT_ID = '12345678-1234-1234-1234-123456789012';
class TemplateManager {
constructor(globalApiKey) {
this.headers = {
'Authorization': `Bearer ${globalApiKey}`,
'Content-Type': 'application/json'
};
}
async listTemplates(tenantId = null) {
const url = tenantId
? `${BASE_URL}/api/templates/tenant/${tenantId}`
: `${BASE_URL}/api/templates`;
const response = await fetch(url, { headers: this.headers });
if (!response.ok) throw new Error(`Failed: ${response.status}`);
return response.json();
}
async getTemplate(templateId) {
const url = `${BASE_URL}/api/templates/${templateId}`;
const response = await fetch(url, { headers: this.headers });
if (!response.ok) throw new Error(`Failed: ${response.status}`);
return response.json();
}
async createTemplate(tenantId, name, mclText, description = null, category = 'Custom') {
const url = `${BASE_URL}/api/templates/tenant/${tenantId}`;
const response = await fetch(url, {
method: 'POST',
headers: this.headers,
body: JSON.stringify({ name, mclText, description, category })
});
if (!response.ok) throw new Error(`Failed: ${response.status}`);
return response.json();
}
async updateTemplate(templateId, updates) {
const url = `${BASE_URL}/api/templates/${templateId}`;
const response = await fetch(url, {
method: 'PUT',
headers: this.headers,
body: JSON.stringify(updates)
});
if (!response.ok) throw new Error(`Failed: ${response.status}`);
return response.json();
}
async deleteTemplate(templateId) {
const url = `${BASE_URL}/api/templates/${templateId}`;
const response = await fetch(url, {
method: 'DELETE',
headers: this.headers
});
if (!response.ok) throw new Error(`Failed: ${response.status}`);
return response.json();
}
}
// 使用例
const manager = new TemplateManager('your-global-api-key');
// テンプレート一覧取得
const templates = await manager.listTemplates(TENANT_ID);
console.log(`${templates.totalCount}件のテンプレートが見つかりました`);
// テンプレート作成
const newTemplate = await manager.createTemplate(
TENANT_ID,
'My Analysis Template',
'// MCL configuration',
'Custom workflow'
);
console.log(`作成されたテンプレートID: ${newTemplate.templateId}`);
// テンプレート削除
await manager.deleteTemplate(newTemplate.templateId);
ベストプラクティス
- グローバルAPIキーの使用: テンプレート操作にはグローバルAPIキーが必要です
- ユニークな名前: テンプレート名はスコープ内で一意である必要があります
- MCLテキスト: 再現可能なノートブックのために完全なMCL構成を保存してください
- カテゴリの活用: 整理のため標準カテゴリを利用してください
- サムネイル: API経由で作成されたテンプレートは自動でサムネイルが付きません