ノートブックブロック操作

ノートブック内で分析ブロックを作成および管理します。ブロックは分析ワークフローの基本単位です。

ブロックタイプ

タイプ	説明
`Filter`	特定のケースやイベントにデータを絞り込む
`Calculator`	メトリクス、期間、派生値を計算する
`Opportunity`	改善の機会を特定する
`Insight`	可視化や統計を生成する
`Dashboard`	共有可能なレポートパネルを作成する
`Alert`	監視アラートを定義する

ブロック一覧取得

GET /api/{tenantId}/{projectId}/notebook/{notebookId}/blocks

ノートブック内の全てのブロックを実行順で返します。

パスパラメータ

パラメータ	型	必須	説明
`tenantId`	GUID	はい	テナント識別子
`projectId`	GUID	はい	プロジェクト識別子
`notebookId`	GUID	はい	ノートブック識別子

レスポンス (200 OK)

{
  "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "blocks": [
    {
      "blockId": "11111111-1111-1111-1111-111111111111",
      "blockType": "Filter",
      "operatorName": "ActivityFilter",
      "name": "Select Key Activities",
      "description": "Filter to main process activities",
      "parentId": null,
      "order": 0,
      "configuration": "{\"activities\": [\"Create Order\", \"Approve\", \"Ship\"]}",
      "dateCreated": "2024-01-15T10:30:00Z",
      "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "dateModified": "2024-01-15T10:30:00Z",
      "isActive": true
    },
    {
      "blockId": "22222222-2222-2222-2222-222222222222",
      "blockType": "Calculator",
      "operatorName": "DurationCalculator",
      "name": "Case Duration",
      "description": "Calculate total case duration",
      "parentId": "11111111-1111-1111-1111-111111111111",
      "order": 0,
      "configuration": "{\"unit\": \"days\"}",
      "dateCreated": "2024-01-15T10:35:00Z",
      "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "dateModified": "2024-01-15T10:35:00Z",
      "isActive": true
    }
  ],
  "totalCount": 2
}

ブロックフィールド

フィールド	型	説明
`blockId`	GUID	ブロックの一意識別子
`blockType`	string	タイプ（Filter、Calculator など）
`operatorName`	string	特定のオペレーター名
`name`	string	ブロック表示名
`description`	string	ブロック説明
`parentId`	GUID	親ブロックID（データは親から流れる）
`order`	integer	実行順のヒント
`configuration`	string	オペレーターのJSON設定
`dateCreated`	datetime	作成日時
`createdBy`	GUID	作成者ユーザーID
`dateModified`	datetime	最終更新日時
`isActive`	boolean	ブロックが有効かどうか

ブロック作成

POST /api/{tenantId}/{projectId}/notebook/{notebookId}/blocks

ノートブック内に新しい分析ブロックを作成します。

パスパラメータ

パラメータ	型	必須	説明
`tenantId`	GUID	はい	テナント識別子
`projectId`	GUID	はい	プロジェクト識別子
`notebookId`	GUID	はい	ノートブック識別子

リクエストボディ

{
  "blockType": "Filter",
  "operatorName": "ActivityFilter",
  "name": "Filter by Status",
  "description": "Keep only completed orders",
  "configuration": "{\"activities\": [\"Complete\", \"Shipped\"]}",
  "insertAfterBlockId": "11111111-1111-1111-1111-111111111111"
}

リクエストフィールド

フィールド	型	必須	説明
`blockType`	string	いいえ	タイプ（Filter、Calculator など）デフォルト: Filter
`operatorName`	string	はい	使用する特定のオペレーター
`name`	string	はい	ブロック表示名
`description`	string	いいえ	ブロック説明
`configuration`	string	いいえ	オペレーターのJSON設定
`insertAfterBlockId`	GUID	いいえ	このブロックの後に挿入（デフォルトは末尾）

レスポンス (201 Created)

{
  "blockId": "33333333-3333-3333-3333-333333333333",
  "blockType": "Filter",
  "operatorName": "ActivityFilter",
  "name": "Filter by Status",
  "description": "Keep only completed orders",
  "parentId": "11111111-1111-1111-1111-111111111111",
  "order": 0,
  "configuration": "{\"activities\": [\"Complete\", \"Shipped\"]}",
  "dateCreated": "2024-03-01T10:00:00Z",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dateModified": "2024-03-01T10:00:00Z",
  "isActive": true
}

ブロック実行順取得

GET /api/{tenantId}/{projectId}/notebook/{notebookId}/blocks/order

ブロックの現在の実行順を返します。

レスポンス (200 OK)

{
  "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "blockCount": 3,
  "blockOrder": [
    {
      "blockId": "11111111-1111-1111-1111-111111111111",
      "parentId": null,
      "position": 1
    },
    {
      "blockId": "22222222-2222-2222-2222-222222222222",
      "parentId": "11111111-1111-1111-1111-111111111111",
      "position": 2
    },
    {
      "blockId": "33333333-3333-3333-3333-333333333333",
      "parentId": "22222222-2222-2222-2222-222222222222",
      "position": 3
    }
  ]
}

ブロック並び替え

PUT /api/{tenantId}/{projectId}/notebook/{notebookId}/blocks/order

ノートブック内のブロックの実行順を変更します。

リクエストボディ

{
  "blockIds": [
    "11111111-1111-1111-1111-111111111111",
    "33333333-3333-3333-3333-333333333333",
    "22222222-2222-2222-2222-222222222222"
  ]
}

リクエストフィールド

フィールド	型	必須	説明
`blockIds`	array	はい	実行順に並べたブロックIDの配列

レスポンス (200 OK)

更新されたブロック順を返します。

ブロック実行フロー

ブロックはチェーンを形成し、各ブロックは親からデータを受け取ります：

[Investigation Start]
       |
       v
[Filter: Activity Filter] -> 特定のアクティビティに絞り込み
       |
       v
[Calculator: Duration] -> 絞り込みデータの期間計算
       |
       v
[Insight: Statistics] -> 計算結果の統計を生成

ブロックの並び替え時には親チェーンも自動で更新されます。

実装例

Python

import requests
import json

BASE_URL = 'https://your-mindzie-instance.com'
TENANT_ID = '12345678-1234-1234-1234-123456789012'
PROJECT_ID = '87654321-4321-4321-4321-210987654321'

class BlockManager:
    def __init__(self, api_key):
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def list_blocks(self, notebook_id):
        """ノートブック内の全ブロックを一覧取得します。"""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}/blocks'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_block(self, notebook_id, block_type, operator_name, name,
                     description=None, configuration=None, insert_after=None):
        """新しいブロックを作成します。"""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}/blocks'
        data = {
            'blockType': block_type,
            'operatorName': operator_name,
            'name': name,
            'description': description,
            'configuration': json.dumps(configuration) if configuration else None,
            'insertAfterBlockId': insert_after
        }
        response = requests.post(url, json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_block_order(self, notebook_id):
        """現在のブロック実行順を取得します。"""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}/blocks/order'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def reorder_blocks(self, notebook_id, block_ids):
        """ノートブック内のブロックを並び替えます。"""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}/blocks/order'
        response = requests.put(url, json={'blockIds': block_ids}, headers=self.headers)
        response.raise_for_status()
        return response.json()

# 使い方
manager = BlockManager('your-api-key')
notebook_id = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'

# ブロック一覧取得
blocks = manager.list_blocks(notebook_id)
print(f"{blocks['totalCount']} 件のブロックを取得しました")

# フィルターブロック作成
filter_block = manager.create_block(
    notebook_id,
    block_type='Filter',
    operator_name='ActivityFilter',
    name='Select Key Activities',
    configuration={'activities': ['Create Order', 'Approve', 'Ship']}
)
print(f"作成したフィルターのID: {filter_block['blockId']}")

# フィルター後に計算ブロック作成
calc_block = manager.create_block(
    notebook_id,
    block_type='Calculator',
    operator_name='DurationCalculator',
    name='Case Duration',
    configuration={'unit': 'days'},
    insert_after=filter_block['blockId']
)
print(f"作成した計算ブロックのID: {calc_block['blockId']}")

# 実行順取得
order = manager.get_block_order(notebook_id)
print(f"ブロック実行順: {[b['blockId'] for b in order['blockOrder']]}")

JavaScript/Node.js

const BASE_URL = 'https://your-mindzie-instance.com';
const TENANT_ID = '12345678-1234-1234-1234-123456789012';
const PROJECT_ID = '87654321-4321-4321-4321-210987654321';

class BlockManager {
  constructor(apiKey) {
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async listBlocks(notebookId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/${notebookId}/blocks`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return response.json();
  }

  async createBlock(notebookId, blockType, operatorName, name, options = {}) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/${notebookId}/blocks`;
    const body = {
      blockType,
      operatorName,
      name,
      description: options.description,
      configuration: options.configuration ? JSON.stringify(options.configuration) : null,
      insertAfterBlockId: options.insertAfter
    };
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(body)
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return response.json();
  }

  async reorderBlocks(notebookId, blockIds) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/${notebookId}/blocks/order`;
    const response = await fetch(url, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify({ blockIds })
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return response.json();
  }
}

// 使い方
const manager = new BlockManager('your-api-key');
const notebookId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';

// ブロック一覧取得
const blocks = await manager.listBlocks(notebookId);
console.log(`${blocks.totalCount} 件のブロックを取得しました`);

// ブロック作成
const filter = await manager.createBlock(notebookId, 'Filter', 'ActivityFilter', 'Key Activities', {
  configuration: { activities: ['Create', 'Approve'] }
});

const calc = await manager.createBlock(notebookId, 'Calculator', 'DurationCalculator', 'Duration', {
  insertAfter: filter.blockId
});

ベストプラクティス

ブロックの順序が重要: データは親から子へ流れるため、ワークフローを計画しましょう
テンプレートを利用する: 複雑なワークフローはテンプレートから作成しましょう
設定はJSON文字列で保存: オペレーター固有の設定はJSON文字列で管理しましょう
InsertAfterを使う: insertAfterBlockId でブロックの位置を制御しましょう
実行を忘れずに: ブロック作成後はノートブックを実行して結果を確認しましょう

ノートブック ブロック操作

ブロックタイプ

ブロック一覧取得

パスパラメータ

レスポンス (200 OK)

ブロックフィールド

ブロック作成

パスパラメータ

リクエストボディ

リクエストフィールド

レスポンス (201 Created)

ブロック実行順取得

レスポンス (200 OK)

ブロック並び替え

リクエストボディ

リクエストフィールド

レスポンス (200 OK)

ブロック実行フロー

実装例

Python

JavaScript/Node.js

ベストプラクティス

ノートブックブロック操作