URL生成

エンティティURLの生成

GET /api/{tenantId}/url/generate

mindzieStudioのページおよびエンティティへの直接URLを生成します。このAPIは、プロジェクト、ダッシュボード、インベスティゲーション、ノートブック、ブロックなどのエンティティへ移動するための正しくフォーマットされたURLを作成します。

認証

Bearerトークン認証が必要です：

Authorization: Bearer {api_key}

リクエスト

GET /api/{tenantId}/url/generate?type={urlType}&entityId={id}&parentId={parentId}
Authorization: Bearer {token}

パスパラメータ

パラメータ	種類	必須	説明
tenantId	GUID	必須	テナント識別子

クエリパラメータ

パラメータ	種類	必須	説明
type	文字列	必須	生成するURLの種類（以下のURLタイプを参照）
entityId	GUID	条件付き	エンティティ固有のページのためのエンティティID
parentId	GUID	条件付き	親ID（タイプに応じてprojectIdまたはnotebookId）
baseUrl	文字列	任意	ベースURLの上書き（デフォルトはリクエストのオリジン）

URLタイプ

一覧ページ

これらのURLタイプは一覧・インデックスページへの直接URLを返します：

タイプ	parentId 必須	生成されるURLパターン
projects	不要	/projects?tenantId={tenantId}
apps	不要	/apps?tenantId={tenantId}
investigations	必須 (projectId)	/investigations?projectId={parentId}
dashboards-list	必須 (projectId)	/dashboards?projectId={parentId}
datasets	必須 (projectId)	/manage-datasets?projectId={parentId}
actions	必須 (projectId)	/actions?projectId={parentId}
bpmn	必須 (projectId)	/bpmn-editor?projectId={parentId}

エンティティページ

これらのURLタイプは特定のエンティティにルーティングする/navigate URLを返します：

タイプ	entityId	parentId	説明
dashboard	dashboardId	-	単一のダッシュボードビュー
analysis	notebookId	-	ノートブック/分析ページ
block	blockId	notebookId	ノートブックページの特定のブロック
enrichment	enrichmentNotebookId	projectId (任意)	エンリッチメントノートブック

レスポンス

レスポンス構造

{
  "url": "https://your-instance.mindziestudio.com/projects?tenantId=...",
  "entityType": "projects",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

レスポンスフィールド

フィールド	種類	説明
url	文字列	リクエストされたページまたはエンティティへの完全修飾URL
entityType	文字列	生成されたURLの種類（typeパラメータと一致）
entityId	GUID または null	エンティティ特定のURLの場合のエンティティID
tenantId	GUID	リクエストに使用されたテナントID

例

一覧ページ

プロジェクト一覧URLの取得

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=projects"

レスポンス:

{
  "url": "https://host/projects?tenantId=660e8400-e29b-41d4-a716-446655440000",
  "entityType": "projects",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

プロジェクトのインベスティゲーション一覧URLの取得

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=investigations&parentId={projectId}"

レスポンス:

{
  "url": "https://host/investigations?projectId=770e8400-e29b-41d4-a716-446655440001",
  "entityType": "investigations",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

プロジェクトのダッシュボード一覧URLの取得

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=dashboards-list&parentId={projectId}"

エンティティページ

ダッシュボードへの直接リンク

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=dashboard&entityId={dashboardId}"

レスポンス:

{
  "url": "https://host/navigate?type=dashboard&id=880e8400-e29b-41d4-a716-446655440002",
  "entityType": "dashboard",
  "entityId": "880e8400-e29b-41d4-a716-446655440002",
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

ノートブック/分析への直接リンク

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=analysis&entityId={notebookId}"

特定のブロックへの直接リンク

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=block&entityId={blockId}&parentId={notebookId}"

レスポンス:

{
  "url": "https://host/navigate?type=block&id=990e8400-e29b-41d4-a716-446655440003&notebookId=aa0e8400-e29b-41d4-a716-446655440004",
  "entityType": "block",
  "entityId": "990e8400-e29b-41d4-a716-446655440003",
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

JavaScript例

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

  async generateUrl(type, options = {}) {
    const params = new URLSearchParams({ type });

    if (options.entityId) {
      params.append('entityId', options.entityId);
    }
    if (options.parentId) {
      params.append('parentId', options.parentId);
    }
    if (options.baseUrl) {
      params.append('baseUrl', options.baseUrl);
    }

    const response = await fetch(
      `${this.baseUrl}/api/${this.tenantId}/url/generate?${params}`,
      { headers: this.headers }
    );

    if (!response.ok) {
      throw new Error(`Failed to generate URL: ${response.status}`);
    }

    return response.json();
  }

  // 利便性向上のメソッド
  async getProjectsUrl() {
    return this.generateUrl('projects');
  }

  async getInvestigationsUrl(projectId) {
    return this.generateUrl('investigations', { parentId: projectId });
  }

  async getDashboardUrl(dashboardId) {
    return this.generateUrl('dashboard', { entityId: dashboardId });
  }

  async getBlockUrl(blockId, notebookId) {
    return this.generateUrl('block', {
      entityId: blockId,
      parentId: notebookId
    });
  }
}

// 利用例
const urlGen = new UrlGenerator(
  'https://your-instance.mindziestudio.com',
  'tenant-guid',
  'your-api-token'
);

// プロジェクト一覧のURLを取得
const projectsUrl = await urlGen.getProjectsUrl();
console.log('Projects URL:', projectsUrl.url);

// 特定のダッシュボードへのURLを取得
const dashboardUrl = await urlGen.getDashboardUrl('dashboard-guid');
console.log('Dashboard URL:', dashboardUrl.url);

// 特定のブロックへのURLを取得
const blockUrl = await urlGen.getBlockUrl('block-guid', 'notebook-guid');
console.log('Block URL:', blockUrl.url);

Python例

import requests
from typing import Optional, Dict, Any

class UrlGenerator:
    def __init__(self, base_url: str, tenant_id: str, token: str):
        self.base_url = base_url
        self.tenant_id = tenant_id
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def generate_url(
        self,
        url_type: str,
        entity_id: Optional[str] = None,
        parent_id: Optional[str] = None,
        base_url_override: Optional[str] = None
    ) -> Dict[str, Any]:
        """指定されたタイプとエンティティのURLを生成する"""
        params = {'type': url_type}

        if entity_id:
            params['entityId'] = entity_id
        if parent_id:
            params['parentId'] = parent_id
        if base_url_override:
            params['baseUrl'] = base_url_override

        url = f"{self.base_url}/api/{self.tenant_id}/url/generate"
        response = requests.get(url, params=params, headers=self.headers)
        response.raise_for_status()
        return response.json()

    # 一覧ページ用の利便性メソッド
    def get_projects_url(self) -> str:
        return self.generate_url('projects')['url']

    def get_investigations_url(self, project_id: str) -> str:
        return self.generate_url('investigations', parent_id=project_id)['url']

    def get_dashboards_list_url(self, project_id: str) -> str:
        return self.generate_url('dashboards-list', parent_id=project_id)['url']

    def get_datasets_url(self, project_id: str) -> str:
        return self.generate_url('datasets', parent_id=project_id)['url']

    def get_actions_url(self, project_id: str) -> str:
        return self.generate_url('actions', parent_id=project_id)['url']

    # エンティティページ用の利便性メソッド
    def get_dashboard_url(self, dashboard_id: str) -> str:
        return self.generate_url('dashboard', entity_id=dashboard_id)['url']

    def get_analysis_url(self, notebook_id: str) -> str:
        return self.generate_url('analysis', entity_id=notebook_id)['url']

    def get_block_url(self, block_id: str, notebook_id: str) -> str:
        return self.generate_url('block', entity_id=block_id, parent_id=notebook_id)['url']

    def get_enrichment_url(self, enrichment_id: str, project_id: Optional[str] = None) -> str:
        return self.generate_url('enrichment', entity_id=enrichment_id, parent_id=project_id)['url']


# 利用例
url_gen = UrlGenerator(
    'https://your-instance.mindziestudio.com',
    'tenant-guid',
    'your-api-token'
)

# 各種URLを取得
projects_url = url_gen.get_projects_url()
print(f"Projects: {projects_url}")

investigations_url = url_gen.get_investigations_url('project-guid')
print(f"Investigations: {investigations_url}")

dashboard_url = url_gen.get_dashboard_url('dashboard-guid')
print(f"Dashboard: {dashboard_url}")

block_url = url_gen.get_block_url('block-guid', 'notebook-guid')
print(f"Block: {block_url}")

MCPサーバー統合

AIコーディングアシスタントはMCPサーバーを使用してURLを生成できます：

mindzie_generate_url type="dashboard" entityId="{dashboardId}"

完全なドキュメントは MCPサーバー統合 を参照してください。

ユースケース

共有リンク

特定のダッシュボード、インベスティゲーション、または分析ブロックへの共有可能なURLを生成します。

統合ワークフロー

mindzieStudioへのディープリンクを外部システムに作成します。

AIアシスタントナビゲーション

AIツールが特定のページを生成し、アプリケーションで開くことを可能にします。

自動レポーティング

関連するダッシュボードや分析への直接リンクを自動レポートに含めます。

エラー処理

ステータスコード	説明
200	成功 - URLが生成されました
400	不正なリクエスト - 無効なtypeまたは必須パラメータの不足
401	認証エラー - 無効または不足している認証トークン
404	未検出 - エンティティが見つかりません（エンティティ固有URLの場合）