pipefy-reports

レポート

使用しているサーフェスに応じて、MCP リファレンスまたはCLI リファレンスを参照してください。関連するリファレンスのみを読み込んでください。

パイプレポートと組織レポート：検出、CRUD、非同期エクスポート。

---

共通パターン

• get_pipe_report_columns と get_pipe_report_filterable_fields を使用して ReportCardsFilter を構築し、一般的でない入力には introspect_type を使用してください。
• get_pipe_reports はクエリに cardCount を含めません（解決時に Pipefy でエラーが発生する可能性があるためです）。

---

パイプレポートのツール

操作	読み取り専用	目的
get_pipe_reports	はい	パイプのすべてのレポートを一覧表示します。
get_pipe_reports	はい	必要に応じて、report_id を指定して単一のレポートを読み込みます。
get_pipe_report_columns	はい	レポートのフィルターで使用できる列を確認します。
get_pipe_report_filterable_fields	はい	レポートでフィルター可能なフィールドを確認します。
create_pipe_report	いいえ	新しいパイプレポートを作成します。
update_pipe_report	いいえ	レポート名またはフィルターを更新します。
delete_pipe_report	いいえ	破壊的な操作です。事前に確認し、承認してください。 選択したサーフェスに確認フローがある場合は、それを使用してください。
export_pipe_report	いいえ	非同期エクスポートを開始します。

組織レポートのツール

操作	読み取り専用	目的
get_organization_reports	はい	組織レベルのすべてのレポートを一覧表示します。
get_organization_report	はい	単一の組織レポートデータを取得します。
create_organization_report	いいえ	組織全体のレポートを作成します。
update_organization_report	いいえ	レポート設定を更新します。
delete_organization_report	いいえ	破壊的な操作です。事前に確認し、承認してください。 選択したサーフェスに確認フローがある場合は、それを使用してください。
export_organization_report	いいえ	非同期エクスポートを開始します。

エクスポートのステータスとダウンロード

操作	目的
get_pipe_report_export	パイプレポートのエクスポートステータスを確認します（export_pipe_report の実行後）。
get_organization_report_export	組織レポートのエクスポートステータスを確認します（export_organization_report の実行後）。
export_pipe_audit_logs	パイプの監査ログをエクスポートします（カードレポートのエクスポートとは別です）。

---

手順 — パイプレポートをエクスポートする

1. 利用可能なレポートを一覧表示します：

   操作：get_pipe_reports pipe_uuid=<PIPE_UUID>（UUID は get_pipe から取得できます）。

2. エクスポートを開始します：

   操作：export_pipe_report pipe_id=67890 pipe_report_id=123

3. 完了するまで確認します：

   操作：get_pipe_report_export export_id=<EXPORT_ID>

   state が done（または failed）になるまで、5～10 秒ごとに繰り返します。

4. ダウンロード： done のエクスポート応答に含まれる署名付き fileURL を HTTPS 経由で使用します。

   リンクは、それを返した読み取りから1時間後に期限切れになります。リンクを持っている人は、期限切れになるまでファイルをダウンロードできます。ユーザーにリンクを渡すときは、1時間で期限切れになることを伝えてください。新しいリンクを取得するには、エクスポートを再度読み込みます。

---

手順 — フィルター付きパイプレポートを作成する

1. フィルター可能なフィールドを確認します：

   操作：get_pipe_report_filterable_fields pipe_uuid=<PIPE_UUID>（UUID は get_pipe から取得できます）。

2. ReportCardsFilter の形式でレポートを作成します（トップレベルの current_phase 配列ではありません）：

   引数：

   create_pipe_report pipe_id=67890 name="Phase subset" filter='{"operator":"and","queries":[{"field":"current_phase","operator":"eq","type":"select","value":"<phase_id>"}]}'
   

   ステップ1で取得した field 文字列をそのまま使用してください。形式が無効な場合は、GraphQL の実行前に拒否され、get_pipe_report_filterable_fields を参照するメッセージが表示されます。

---

成功条件

• get_pipe_report_export（または get_organization_report_export）が終端状態の done または failed に到達すること。
• ダウンロードしたエクスポートに、想定したカード／レポートデータが含まれていること。

障害への対処

• エクスポートが processing のまま止まる： カード数の多い大規模なパイプでは、数分かかることがあります。5～10秒間隔でポーリングして1分経過してもエクスポートが processing の場合は、以降は60秒間隔でポーリングしてください。数分経っても processing の場合は、エクスポートの開始を再試行してください。
• get_pipe_reports が cardCount に null を返す： 既知の Pipefy API の動作です。このツールはそのフィールドを自動的に省略します。
• GraphQL の前にフィルターが拒否される： {"current_phase":["id"]} は渡さないでください。operator と queries を使用してください（上記のステップ2を参照）。
• 作成後にフィルターが機能しない： get_pipe_report_filterable_fields を使用して、正確な field 文字列と value の形式を確認してください。

関連項目

• pipefy-observability — エクスポート自動化ジョブの履歴（パイプレポートとは異なります）。
• pipefy-introspection — 複雑なフィルターに必要な ReportCardsFilter の入力形式を確認します。