kurokobo.com

Dify のトリガー機能を試す（Gmail / GitHub 連携）

2025 年 11 月 3 日2025 年 11 月 5 日 @kurokobo コメントをする

はじめに

Dify の 1.10.0-rc.1 で、新しい トリガー機能 がリリースされました。

これは、簡単にいえば、指定したスケジュール や Webhook の受信、SaaS 上での何らかの動き などを契機に、イベントドリブンなワークフローの実行 ができるようになる機能です。

先日リリースされたナレッジパイプラインとあわせて今年の目玉機能のひとつとされていたもので、開発目線では実装へのコントリビューションが積極的に募集され進捗も公開されていた点がめずらしいケースでした。

それはそれとして、1.10.0-rc.1 時点 の情報を、主に SaaS との連携 を中心にまとめます。リリース名の通り現時点では RC 版 であり、正式版では仕様が変わる可能性はもちろんあるので、その点はご了承ください。

TL; DR

スケジュールトリガ は、Dify 以外に必要なものがないため、利用はとても簡単です。Webhook トリガ も、送信側に Dify へのリーチャビリティがありさえすればよく、利用は簡単です。

一方で、SaaS と連携したトリガ を利用するには、Dify が SaaS 側からの POST リクエストを受け取れる必要 があります。したがって、OAuth の認証も考慮すると、多くの場合で Dify 側のエンドポイントを正規の SSL 証明書で HTTPS 化してインタネットに公開する ことが求められるため、セルフホスト環境での利用には一定のハードルがある と考えたほうがよいでしょう。他方、クラウド版 では利用のハードルは低く、比較的気軽に使えると考えられます。

現時点では、1.10.0-rc.1 をセルフホスト すれば、いずれの機能も試用できます。ただし、SaaS と連携したトリガを試したい場合は、プラグインを自分でソースコードからパッケージすること と、前述のとおり 正規の証明書を取得して Dify を HTTPS でインタネットに公開すること が必要になる場合があります。

前提：トリガ機能の種類と仕組み

トリガ機能には、大まかには次の三つの種類があります。

スケジュール機能
Webhook 機能
SaaS 連携機能

スケジュール機能

スケジュールトリガ では、N 時間ごと・日次・週次・月次から選択するか、Cron 形式でのスケジュールを設定できます。

設定すると、worker_beat コンテナ（Dify の 1.7.0 から追加されています）でスケジュールが管理されます。コンテナ名の通り、このあたりの実装は Cerely Beat です。

指定した時間になると worker_beat コンテナからタスクがキックされ、あとは Cerely の Worker たる worker コンテナが後続の処理を担います。

これは組み込みの機能で、プラグインなしで動作 します。Dify 外への接続要件もなく、非常に気軽に使える、便利で強力な機能です。

Webhook 機能

Webhook トリガ を設定すると、ノードごとに一意の URL が発行されます。

これを外部から叩くことで、後続の処理が流れ始める仕組みです。この URL へのリクエストは、api コンテナが受け取っています。

これも組み込みの機能で、プラグインなしで動作 します。Webhook の送信側から Dify の URL に到達できさえすればよく、curl や Invoke-WebRequest などを使えばテストも簡単です。例えば企業のプライベートネットワーク内などでも便利に利用できるでしょう。

SaaS 連携機能

外部の SaaS で発生したイベント をトリガにできる機能で、動作には SaaS ごとに専用のプラグインが必要 です。

プラグインごとの設定で、Dify 側で 目的のイベントに応じた Subscription を作成 すると、その Subscription ごとに一意の URL が発行されます。この URL を SaaS 側の Webhook 送信機能に（手動または自動で）登録することで、Dify に SaaS 側のイベントが届くようになります。この URL へのリクエストは、api コンテナが受け取っています。

その仕様から、つまり、

SaaS 側から Dify 宛に HTTP でイベントを POST してもらう

ことで動作するため、Dify 側のエンドポイントをインタネットに公開する必要がある といえます。さらに、細かい要件は SaaS 側の仕様にも依存するものの、OAuth での認証プロセスも含めると、Dify 側のエンドポイントは 正規の SSL 証明書で保護された HTTPS であることが要求されることも多いでしょう。

この意味で、もともとインタネット上でサービスされている クラウド版の Dify では特別な工夫なく使えるため 利用のハードルは低い といえます。一方で セルフホスト環境 では、そもそもの 環境の用意それ自体に技術的なハードル がありますし、加えて、特に企業でのユースケースではインタネットにエンドポイントを露出させることに対して セキュリティポリシなどの管理面や運用面でもハードル があることが予想されます。

が、いずれにしても、うまく活用できれば強力な機能であることは確かです。

実装面を踏み込んで理解したい場合は、トリガプラグインの開発を解説した公式ドキュメントを参考にできます。

環境の準備

今回は、SaaS 連携を試す ことを目的に環境を準備します。

1.10.0-rc.1 をチェックアウト したうえで、標準の docker-compose.yaml の隣に、今回は次の docker-compose.override.yaml を用意しました（ドメインは example.com に置き換えています）。

services:
  api:
    environment: &env
      CONSOLE_API_URL: https://dify.example.com
      CONSOLE_WEB_URL: https://dify.example.com
      SERVICE_API_URL: https://dify.example.com
      TRIGGER_URL: https://dify.example.com
      APP_API_URL: https://dify.example.com
      APP_WEB_URL: https://dify.example.com
      FILES_URL: https://dify.example.com
      INTERNAL_FILES_URL: https://dify.example.com

  worker:
    environment: *env

  worker_beat:
    environment: *env

  plugin_daemon:
    environment:
      FORCE_VERIFYING_SIGNATURE: "false"
      ENFORCE_LANGGENIUS_PLUGIN_SIGNATURES: "false"

  nginx:
    environment:
      NGINX_HTTPS_ENABLED: "true"

ポイントは以下あたりです。

api サービスで、*_URL 系の指定を正規の HTTPS な URL にしています
- アンカ（&）とエイリアス（*）で、worker と worker_beat にも同じ設定をしています
plugin_daemon サービスで、自分でパッケージしたプラグイン（後述）をインストールできるように、次の二つを false にしています
- FORCE_VERIFYING_SIGNATURE：パッケージの署名の検証を強制する
- ENFORCE_LANGGENIUS_PLUGIN_SIGNATURES： author が langgenus のプラグインは署名を必須にする
nginx サービスで、HTTPS を有効化しています

なお今回、.env ファイルは .env.example をコピーしたまま、何も手を加えずに放置です。.env ファイルをいじらなくても、上記のように docker-compose.override.yaml に書けばそれが優先されます。この手法は、.env ファイルの差分を気にしなくてよくなるうえ、環境変数以外の細かいカスタマイズも一元管理できるので、なかなか楽です。

ファイルができたら、あとは docker compose up -d しておしまいです。試した範囲ではイメージの差し替えは不要でした。

プラグインの準備

現時点ではトリガ機能は正式版ではないので、プラグインはまだマーケットプレイスでは公開されていません。このため、SaaS 連携のトリガを使いたい場合は、開発中のプラグインのソースコードを持ってきて、自分でパッケージします。

開発中のプラグインは、だいたい dify-official-plugins か dify-plugin-sdks の Feature ブランチにあることが多く、今回もそうでした。本エントリ公開時点では以下が入っています。

langgenius/dify-official-plugins： feat/triggers ブランチの triggers ディレクトリ
- GitHub Trigger（今回試したもの）
- Linear Trigger
- Notion Trigger
- RSSHub Trigger
- Typeform Trigger
langgenius/dify-plugin-sdks： feat/trigger ブランチの python/examples ディレクトリ
- Dropbox Trigger
- GitHub Trigger
- Gmail Trigger（今回試したもの）
- Google Drive Trigger
- Lark Trigger
- Slack Trigger
- Telegram Trigger

これを Dify のプラグイン開発の通常のお作法でパッケージします。

dify plugin package ./github_trigger
dify plugin package ./gmail_trigger

今回は Gmail と GitHub を試したかったので、dify-official-plugins から GitHub Trigger を、 dify-plugin-sdks から Gmail Trigger をそれぞれパッケージしました。あとは Dify にインストールするだけです。

なお、Gmail Trigger はそのままでは動かず、修正が必要でした。修正は PR で送っているので、マージ前に手元で試したい場合は差分をあててからパッケージしてください。

Gmail と GitHub 以外のプラグインは細かい確認はしていませんが、manifest.yaml の meta.minimum_dify_version をいじらないとインストールができないパタンが多そうです。また、requirements.txt の dify_plugin は、最低でも 0.6.0b13 以降にしておくと安心です。どのプラグインも成熟しているとはいえないため、すんなり動けばラッキーくらいの気持ちで覚悟を持つとよいと思います。

試行： Gmail 連携

現時点の実装では、Gmail 用のトリガは次の 4 種類のイベントに対応しているようです。

メッセージの受信
メッセージの削除
メッセージのラベルの追加
メッセージのラベルの削除

今回はこのうち、メッセージの受信 を試しました。プラグインの README がけっこう細かいので、それを見ながら設定するとどうにかなりますが、大まかには構成のポイントは次のあたりです。

Gmail の API だけでなく、Cloud Pub/Sub の API も有効にする
Cloud Pub/Sub の Topic に Gmail のイベントが流れるようにする
Cloud Pub/Sub に Push な Subscription を作って、Dify の URL を入れる

Dify 側の Subscription の設定は例えばこんな感じです。Callback URL 欄に表示される URL を、Cloud Pub/Sub の Push 先にします。Label IDs は、今回は INBOX（受信トレイ）だけ選択しています。

Cloud Pub/Sub 側の設定例。Push の Subscription を作っています。

動作確認用のワークフローも作りました。トリガされたことがわかりさえすればよいので、トリガノードの出力を Template でダンプするだけのやつです。

Gmail にメールが届くと、トリガが実行されます。届いたメールと、それによって動いたワークフローのログがこんな感じです。

いい感じですね。

試行： GitHub 連携

現時点の実装では、GitHub 用のトリガは例えば以下のようなイベント（全部で 50 種類）に対応しているようです。

Issue の作成、コメントの追加
Pull Request の作成、レビュ、レビュコメントの追加
スターの追加
リリースの追加
ほか

今回は、シンプルに Issue の作成 を試しました。プラグインの README では PAK での認証が推奨されていましたが、GitHub 側での Webhook の作成がコケたので、OAuth にしています。

Dify 側の Subscription の設定はこんな感じです。リポジトリを選択して、受け取りたいイベントを選択します。今回は Issue 関係を選んでいます。

Subscription ができると、GitHub 側に設定が走り、指定したリポジトリに Webhook が自動で構成されます。投げ先の URL だけでなく、Dify 側で設定したとおりに投げるイベントの種類も自動で構成されました。

この状態で、指定したリポジトリに Issue を作成しました（後から画面を撮ったのでクローズ済みに見えますが、もちろん、作成しただけでイベントは発火します）。

ワークフローがトリガされたことがわかります。

GitHub 側でも、Webhook の送信履歴を確認できます。

いい感じですね。

おわりに

個人的に、SaaS 連携のトリガには Pull 型の実装、つまり Dify への インバウンド通信が必要ないアーキテクチャを期待 していたのですが、今のところは今回紹介したように Push 型 の実装のようでした。仮に Pull 型を目指した場合、Dify 側でサブスクライバ相当のプロセスなりスレッドなりを常駐させる必要も出てきそうなので、オーバヘッドを回避したか、アーキテクチャをシンプルにしたか、何か理由はあるものとは思います。

そんなわけで、正式版がリリースされたらクラウド版ではたいへん便利に使えると思いますが、Dify は残念ながら（運用負荷を飲んででも）セルフホストしたほうが機能が安定する傾向もあるので、セルフホスト環境での利用ハードルがすこし高い点は惜しいポイントです。

とはいえ、未来永劫このままということが決まっているわけでもなく、エンハンスは今後も続いていくでしょうし、引き続きの進化には期待したいですね。

RAG 2.0： Dify の新しいナレッジパイプラインを探る

2025 年 9 月 5 日2025 年 9 月 5 日 @kurokobo 1件のコメント

はじめに

Dify の今年の目玉機能のひとつ、ナレッジパイプライン（Knowledge Pipeline）が、昨日、Dify の 2.0.0 のベータ版（beta.1）の機能のひとつとしてリリースされました。

この機能、ベータ版の公開前から勝手に興味をもって個人的に実際に動かして触ったりバグをちょこっと直したり機能をちょこっと足したりしていたので、ベータ版の公開に合わせて、簡単に紹介します。

ただし、以下の点、ご了承ください。

ベータ版より前の開発途中のソースコードを手掛かりに、公式のドキュメントなどが何もない段階で、自分の体験や理解・解釈に基づいてまとめたものです
開発途中ならではのバグにより実際には動かせなかった部分を推測で補っているところもあります
したがって、本エントリの内容は正式なリリースの内容とは一致しない可能性があります

Dify の Enterprise 版のアーキテクチャをちょっとだけ探る

2025 年 7 月 22 日2025 年 7 月 23 日 @kurokobo コメントをする

はじめに

Dify には有償の Enterprise 版があります。動かすにはライセンスが必要ですし、OSS ではないのでソースコードも見られないのですが、一方で、Enterprise 版のドキュメントや、デプロイに必要なアセット一式は、インタネットで公開されています。

で、Enterprise 版で動く Dify のバージョンが 0.x だった頃に、そういう公開されているいろいろを探索してフムフムと技術的な好奇心を満たしていたのですが、最近、Enterprise 版の Dify が 1.x に引き上げられ、プラグインに対応しました。そんなわけで、改めてちょっとだけ中身を探ったので、簡単に紹介です。Community 版へのコントリビューションを続けるなかで、とくに Enterprise 版でのプラグイン周辺のアーキテクチャが気になっていたのでした。

ドキュメントでも細かくは説明されていない部分なので、Enterprise 版の導入や、導入済みの Enterprise 版のアップグレード（プラグインアーキテクチャへのマイグレーション）を検討している場合は、参考になる…… かも…… しれません。

PSDify： Dify のワークスペースの管理をコマンドで！アプリ・ナレッジ・モデル・メンバ管理用 PowerShell モジュール

2024 年 12 月 1 日2024 年 11 月 30 日 @kurokobo コメントをする

はじめに

Dify がすこぶる便利でおもしろいので、もりもりと使ったりちまちまとコントリビューションをしたりしています。

今回、Dify の 運用管理系 の操作、たとえば、

✨ アプリのインポートやエクスポート
✨ ナレッジの作成とファイルの追加
✨ ワークスペースのメンバの改廃
✨ モデルの追加やシステムモデルの設定

などを、PowerShell のコマンドレットで行える ようにするモジュール PSDify をリリースしたので、かんたんに使い方などを紹介します。

PSDify: A PowerShell module for workspace management for Dify

これは Dify Advent Calendar の 1 日目です。

Ansible の出力にシンプルなタイムスタンプを表示する（community.general.timestamp）

2024 年 5 月 22 日2024 年 5 月 23 日 @kurokobo コメントをする

はじめに

Ansible のプレイブックの実行結果にめちゃくちゃシンプルなタイムスタンプを表示するだけのコールバックプラグイン community.general.timestamp をリリースしました。

簡単に使い方を紹介します。

Virtual Infrastructure JSON API（VI/JSON API）の触り方

2024 年 3 月 9 日2024 年 3 月 9 日 @kurokobo コメントをする

はじめに

前回のエントリで、vSphere に古くから実装されている API である vSphere Web Services API（SOAP API）の触り方を紹介しました。その中で、Virtual Infrastructure JSON API にひとことだけ触れています。

SOAP API を（広義の）REST API のように触れる Virtual Infrastructure JSON API も vCenter Server 8.0 U1 以降が必要で、まだまだ一般的ではありません。
vSphere Web Services API（SOAP API）の触り方 | kurokobo.com

Virtual Infrastructure JSON API（VI/JSON API）は、vCenter Server 8.0 U1 で追加された新しい API で、ひとことで雑に表現するなら、従来の SOAP API の REST API 版 です。

本エントリでは、まだ日本語ではほとんど情報がないこの新しい API について、実例とともに簡単に紹介します。

なお、vSphere の REST API といえば vSphere Automation API が一般的ですが、VI/JSON API はこれとはまったく別物 です。

vSphere Web Services API（SOAP API）の触り方

2024 年 3 月 7 日2024 年 3 月 8 日 @kurokobo コメントをする

はじめに

vSphere 環境をコマンドライン環境や何らかのスクリプトから操作するとき、典型的には PowerCLI や govmomi、pyVmomi、VMware vSphere Automation SDK などのツールがよく利用されますが、こうしたツールを使わずに API を直接触れる と、vSphere に実装された新機能をリリースと同時に使い始められ てたいへん便利です。実際、vSphere vMotion Notifications がリリースされたときも、ツールが更新されるまでは、API を直接触る以外にそれを試す手段がありませんでした。

vSphere の API には、古くからある SOAP API（vSphere Web Services API）と新しい REST API（vSphere Automation API）の大きく二つがあります。操作が簡単なのは間違いなく REST API ですが、SOAP API でしか行えない操作もたくさんあり、また、SOAP API を（広義の）REST API のように触れる Virtual Infrastructure JSON API も vCenter Server 8.0 U1 以降が必要で、まだまだ一般的ではありません。

したがって現状では、昔ながらの SOAP API こそ が、極論、大抵のことはどうにかできる API であると言えます。そこでこのエントリでは、SOAP API（vSphere Web Services API）を直接触る方法 を実例と共に紹介します。

なお、コマンド例は curl と PowerShell で紹介 していますが、結局は HTTP で XML をやりとりするだけなので、お作法さえわかれば他の HTTP クライアントでももちろん利用できます。また、SOAP API は Managed Object Browser（MOB）でも操作できますが、Web ブラウザでの操作であり自動化には向かないため、今回は取り上げません。

AWX の Automation Mesh で Hop Node と Mesh Ingress を使う

2024 年 2 月 19 日2024 年 2 月 19 日 @kurokobo コメントをする

はじめに

AWX の Automation Mesh を構成する機能として、過去に紹介した Execution Node に加えて、Hop Node と Mesh Ingress が最近のリリースで追加されました。

関連する情報は AWX のドキュメントや AWX Operator のドキュメントにもまとまっていますが、本エントリでは Mesh Ingress を中心にこれらの新機能を簡単に紹介します。

AWX のジョブのログを YAML 形式で表示させる

2023 年 12 月 29 日2023 年 12 月 29 日 @kurokobo 2件のコメント

はじめに

Ansible でよくある困りごとのひとつとして、タスクのログに複数行の文字列が含まれるとき、以下のように人間の眼にはやさしくない表示になることが挙げられます。改行がエスケープシーケンスとして表示されるためです。

...
TASK [Referring undefined variable] ********************************************
fatal: [localhost]: FAILED! => {"msg": "The task includes an option with an unde
fined variable. The error was: 'undefined_variable' is undefined. 'undefined_var
iable' is undefined\n\nThe error appears to be in '/runner/project/demo.yaml': l
ine 20, column 7, but may\nbe elsewhere in the file depending on the exact synta
x problem.\n\nThe offending line appears to be:\n\n\n    - name: Referring undef
ined variable\n      ^ here\n"}
...

この対策として、改行が改行として表示されるように 出力を YAML 形式にする 方法がよく知られています。本エントリ公開時点では、次の二つの方法が一般的です。

Ansible の組み込みの機能を利用する（Ansible 2.13 以降のみ）
- ansible.cfg の callback_result_format（または環境変数 ANSIBLE_CALLBACK_RESULT_FORMAT）に yaml を指定する
コレクション community.genral のコールバックプラグイン yaml を利用する
- ansible.cfg の stdout_callback（または環境変数 ANSIBLE_STDOUT_CALLBACK）に community.general.yaml を指定する

一方で、同じ困りごとは AWX でも発生しますが、AWX で同じ対策を試みても意外と素直にいきません。

先日、これに関する質問が Ansible Community Forum に寄せられました。フォーラムでもぼくから回答済みですが、本エントリでは、AWX でジョブのログを YAML 形式で出力させる方法を改めて日本語で簡単に紹介します。

EDA Server を Operator でデプロイして Kubernetes 上での動作を確認する

2023 年 8 月 9 日2023 年 8 月 19 日 @kurokobo 2件のコメント

はじめに

EDA Server のデプロイ方法として、公式のデプロイメントガイドでは Docker Compose と Minikube が案内されています。

その一方で、ひっそりと EDA Server Operator が公開されています。これは、EDA Server をデプロイするための Operator です。

ansible/eda-server-operator

まだ開発中であり、前述のデプロイメントガイドに記載もないことから、完全にサポートされている手段とはまったく言えませんが、本エントリではこれを用いた EDA Server のデプロイと、その後の AWX との連携を、Kubernetes 上での EDA Server の動きを含めて簡単に紹介します。

なお、この Operator の名称は EDA Controller Operator が正しいような気もしており、中の方々の意見を聞く意味も兼ねて Issue と PR を作っていますが、今のところ何ら確証はないので、本エントリでは現時点のドキュメントに従って EDA Server Operator と表記しています。

本エントリ中で利用しているファイルは、GitHub のリポジトリにも配置しています。

追記（2023/08/12）

追記 (1)

公式のデプロイメントガイドが更新され、推奨されるデプロイ方式が Operator になりました。

追記 (2)

当初、一貫してツール名称を EDA Controller と表記していましたが、アップストリーム版は EDA Server であり、EDA Controller は Ansible Automation Platform に含まれる製品版の名称とのことなので、タイトルと本文を修正しました。

Operator の名称も EDA Server Operator で正しいようです。

はじめに

TL; DR

前提： トリガ機能の種類と仕組み

スケジュール機能

Webhook 機能

SaaS 連携機能

環境の準備

プラグインの準備

試行： Gmail 連携

試行： GitHub 連携

おわりに

はじめに

はじめに

はじめに

はじめに

はじめに

はじめに

はじめに

はじめに

はじめに

追記（2023/08/12）

追記 (1)

追記 (2)

前提：トリガ機能の種類と仕組み