プロジェクト API

Blue でプロジェクトを管理するための完全な API リファレンス - プロジェクトの作成、更新、削除、およびクエリ

概要

プロジェクトは Blue のコア組織単位です。プロジェクトにはリスト、タスク、カスタムフィールド、自動化、およびその他の作業関連データが含まれます。プロジェクトは企業に属し、それぞれ独自の権限システム、テンプレート、および設定を持っています。

利用可能な操作

コアプロジェクト操作

操作	説明	リンク
Create Project	新しいプロジェクトを作成するか、テンプレートから作成する	View Details →
List Projects	プロジェクトをクエリおよびフィルタリングする	View Details →
Delete Project	プロジェクトを永久に削除する	View Details →
Archive Project	プロジェクトをアーカイブ/アーカイブ解除する	View Details →
Rename Project	プロジェクト名とスラグを更新する	View Details →
Copy Project	既存のプロジェクトを複製する	View Details →

プロジェクトコンポーネント

コンポーネント	説明	リンク
Lists	プロジェクト内のタスクリストを管理する	View Details →
Templates	プロジェクトテンプレートを扱う	View Details →
Activity	プロジェクトのアクティビティと変更を追跡する	View Details →

主要概念

プロジェクト構造

プロジェクトは企業に属します
各プロジェクトには複数のリストを持つことができます
リストにはタスクが含まれます
プロジェクトはカスタムフィールド、タグ、および自動化をサポートします

権限モデル

プロジェクトには多層の権限システムがあります：

レベル	権限
OWNER	Full control, can delete project
ADMIN	Manage project settings, users, and content
MEMBER	Create and edit content
CLIENT	Limited edit access
VIEW_ONLY	Read-only access
COMMENT_ONLY	Can only comment

プロジェクトカテゴリ

プロジェクトはより良い組織のためにカテゴリ分けできます：

CRM
CROSS_FUNCTIONAL
CUSTOMER_SUCCESS
DESIGN
ENGINEERING
GENERAL (デフォルト)
HR
IT
MARKETING
OPERATIONS
PERSONAL
PROCUREMENT
PRODUCT
SALES

一般的なパターン

基本プロジェクトの作成

mutation CreateProject {
  createProject(input: {
    name: "Q1 Marketing Campaign"
    companyId: "company-123"
    category: MARKETING
  }) {
    id
    name
    slug
  }
}

フィルタを使用したプロジェクトのクエリ

query GetProjects {
  projectList(
    filter: {
      companyIds: ["company-123"]
      isArchived: false
      categories: [MARKETING, SALES]
    }
    sort: [{ field: updatedAt, direction: DESC }]
    take: 20
  ) {
    items {
      id
      name
      category
      todosCount
      todosDoneCount
    }
    pageInfo {
      hasNextPage
      total
    }
  }
}

注意: projectList クエリはプロジェクトをクエリするための推奨アプローチです。レガシー projects クエリも存在しますが、新しい実装には使用しないでください。

プロジェクトリストの管理

# Get all lists in a project
query GetProjectLists {
  todoLists(projectId: "project-123") {
    id
    title
    position
    todosCount
  }
}

# Create a new list
mutation CreateList {
  createTodoList(input: {
    projectId: "project-123"
    title: "To Do"
    position: 1.0
  }) {
    id
    title
  }
}

ベストプラクティス

プロジェクト名の付け方
- 明確で説明的な名前を使用する
- スラグに影響を与える可能性のある特殊文字を避ける
- 名前は50文字以内に収める
権限管理
- 最小限の権限から始める
- 外部関係者には CLIENT ロールを使用する
- 定期的にプロジェクトアクセスを監査する
組織化
- カテゴリを使用して類似のプロジェクトをグループ化する
- 完了したプロジェクトは削除するのではなくアーカイブする
- 繰り返しのプロジェクトタイプにはテンプレートを使用する
パフォーマンス
- 大規模なプロジェクトリストにはページネーションを使用する
- アクティブ/アーカイブ済みのステータスでフィルタリングする
- プロジェクトごとのリスト数を制限する（最大50）

エラーハンドリング

遭遇する可能性のある一般的なエラー：

エラーコード	説明	解決策
`PROJECT_NOT_FOUND`	プロジェクトが存在しないか、アクセス権がない	Verify project ID and permissions
`COMPANY_NOT_FOUND`	企業が存在しない	Check company ID
`FORBIDDEN`	権限が不十分	Ensure proper role level
`BAD_USER_INPUT`	検証エラー（例：名前が長すぎる）	Check input validation requirements

概要