Boxファイル監視をPower AutomateでExcelに書込み - Webhook v2編

前回の記事では、BoxのWebhook v1を利用してファイル監視を実現しました。しかし欠点として、個別のフォルダの指定など出来ず自分の可視範囲全てのフォルダが監視対象となってしまうので、情報量が大きくなりPower Automateのリミット超えたり、データとしてノイズが大きくなる点がありました。

そこで今回、Box APIを利用してWebhook v2を使い、特定のフォルダに対してだけファイル監視を行い、またv1では取得できなかった情報Excel Onlineに書き込むようにしてみようと思います。但し、Webhook v2はGUIではなく、Box APIからでないと設置出来ないので、別途設置管理するアプリを用意する必要があります。

今回使用するサービス

事前準備

設置は別プログラムから

Webhook v2は別途他のプログラムからAPIを叩いて設置する事が必要です。よって、ここでは今回事前準備についてはスルーします。列挙すると

  1. Box Developer ConsoleにてClient IDとClient Secretを作成
  2. OAuth2.0認証を実行し、Access Tokenを取得
  3. Webhook v2をAPIで設置・管理する仕組みの用意

となります。ちなみに、Webhook v2は対象のフォルダを削除すると自動的にWebhookも削除されます。尚、下記スクリーンショットのアプリは以下のページで公開しています。

Box権限管理アプリ

図:自作ツールでWebhook v2設置中の様子

Webhook V2の制限事項

Box Webhook v2には、いくつかの制限事項があります。実際に設置や運用するに当たってはよく把握しておく必要があります。

  • 1個のフォルダ・ファイルに付けられるWebhookは1個のみ(トリガーは複数指定は可能)
  • 1ユーザ、1アプリあたり最大1000個までWebhookは設置可能
  • 通知先URLは、httpsで始まるもののみ。ポートもまた443番のみ(httpsはオレオレ証明書はNGです)
  • ルート直下のフォルダ(IDが0のフォルダ)には、Webhookは設置出来ません

この中で問題になりそうなのは、通知先URLかと。2つ目の最大1000個は細かなファイル単位で設置を行うとリミットに達する可能性はありますが、通常はフォルダに対してWebhookを設置するので、そこまで大きな問題になることはないかと。

Webhook v1との違い

Webhook v2はv1とは異なり、細かな情報を取得できるため、Power Automateで出来ることも広がっています。

  1. Boxイベントで送信できるトリガーがv1よりも多くなっています
  2. Boxイベントの中身がv1よりも様々な情報が入っています
  3. 主にv2で新たに活用出来るのが、親フォルダのIDと名前の取得実行者のメールアドレスの取得などなど。詳細は次項を参照。

メアドが取れるので、メールアドレスからドメインを切り出して、条件分岐にて指定のドメインの人間の場合にだけ、Excelに書き込みなどのフローを作れるようになります(v1だとメアドが取得できない)。また、親フォルダの名前が取得出来るので、IDではなく名前でファイルが今どこに存在してるのかを追跡できるようになります。

受信するWebhookの返り値

Boxから飛んでくるWebhookの内容は以下のようなものです。但し、トリガーによって内容が異なりますので注意が必要です。実際にはここから必要なものだけに絞ってスキーマを作って取り出します。

{
    "headers": {
        "Cache-Control": "max-age=259200",
        "Connection": "keep-alive",
        "Host": "azureのホスト名",
        "User-Agent": "Box-WH-Client/0.1",
        "box-delivery-timestamp": "2021-04-12T19:00:06-07:00",
        "box-delivery-id": "",
        "Surrogate-Capability": """",
        "Content-Length": "1873",
        "Content-Type": "application/json; charset=UTF-8"
    },
    "body": {
        "type": "webhook_event",
        "id": "イベントID",
        "created_at": "2021-04-12T19:00:05-07:00",
        "trigger": "トリガーの名前",
        "webhook": {
            "id": "webhookのid",
            "type": "webhook"
        },
        "created_by": {
            "type": "user",
            "id": "作成者のユーザID",
            "name": "作成者のユーザ名",
            "login": "作成者のメールアドレス"
        },
        "source": {
            "id": "ファイルのID",
            "type": "file",
            "file_version": {
                "type": "file_version",
                "id": "バージョン毎のID",
                "sha1": ""
            },
            "sequence_id": "1",
            "etag": "1",
            "sha1": "",
            "name": "アクション対象のファイル名",
            "description": "",
            "size": 6128,
            "path_collection": {
                "total_count": 3,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "すべてのファイル"
                    },
                    {
                        "type": "folder",
                        "id": "もう一個上の親フォルダのID",
                        "sequence_id": "4",
                        "etag": "4",
                        "name": "もう一個上の親フォルダの名前"
                    },
                    {
                        "type": "folder",
                        "id": "親フォルダのID",
                        "sequence_id": "2",
                        "etag": "2",
                        "name": "親フォルダの名前"
                    }
                ]
            },
            "created_at": "2021-04-12T17:42:32-07:00",
            "modified_at": "2021-04-12T17:42:56-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2021-04-12T17:42:27-07:00",
            "content_modified_at": "2021-04-12T17:42:27-07:00",
            "created_by": {
                "type": "user",
                "id": "作成者のユーザID",
                "name": "作成者のユーザ名",
                "login": "作成者のメールアドレス"
            },
            "modified_by": {
                "type": "user",
                "id": "編集者のユーザID",
                "name": "編集者のユーザ名",
                "login": "編集者のメールアドレス"
            },
            "owned_by": {
                "type": "user",
                "id": "オーナーのユーザID",
                "name": "オーナーのユーザ名",
                "login": "オーナーのメールアドレス"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "親フォルダのID",
                "sequence_id": "2",
                "etag": "2",
                "name": "親フォルダの名前"
            },
            "item_status": "active"
        },
        "additional_info": {
            "after": {
                "id": "変更前ID",
                "type": "folder"
            },
            "before": {
                "id": "変更後ID",
                "type": "folder"
            }
        }
    }
}

Power Automateでフロー作成

前回のフローと見た目は同じですが、JSONの解析と表に行を追加の中身が変わっています。特に、JSONの解析については、Webhook v2はv1とは全く内容がことなり、取れる内容量も異なるので、解析する為のJSONスキーマが重要になります。

図:見た目は前回と同じようなフロー

インスタントフローの作成

HTTP要求の受信時

ログイン後、以下の手順でまずは受け口を作ります。これがIncoming Webhookとなります。前回と異なり、POSTで受信させる必要があります。

  1. マイフローに入り、新規作成にて「インスタントフロー」を選択します。
  2. フロー名を適当に入れて、トリガーはHTTP要求の受信時を選択します。
  3. 要求本文の JSON スキーマには、以下のようなコードを入れます。今回POSTで受信させるのでこのJSONスキーマは必須です。
  4. 詳細オプションを表示するをクリック
  5. methodはPOSTを選択します。

ちなみに、Box側から飛んできた返り値は、フローの実行ログから成功したものをクリックし、HTTP要求の受信時の中にある「出力」⇒「未加工出力の表示」で知ることが可能です。

※このコネクタで生成されるHTTP POSTのURLが、Webhook v2での送信先URLになります。

{
    "type": "object",
    "properties": {
        "key": {
            "type": "string"
        }
    }
}

図:POSTで受信されます

図:成功時にBox側からの返り値を見られます

JSONの解析

次のステップとしてJSONの解析を追加します。設定は以下の通りです。

  1. スキーマには、取り出したいキーと値を指定します。。但し、返り値のすべてをスキーマで指定すると、取り出すキー名が同じ物が沢山あるので、ある程度絞っておくのが肝要です。
  2. コンテンツをクリックして、動的コンテンツの式をクリック
  3. 数式として、以下のような数式を入力し、OKをクリックします
triggerOutputs()['body']

今回は、返り値のうち、body以下の項目を取りたいので、数式のキー名はbodyにしています。問題点は、1.のスキーマですが、手動で作ると大変なので、以下の手順で簡単に作れます。

  1. サンプルから生成をクリック
  2. サンプルJSONペイロードの挿入ダイアログに、必要な項目に絞った以下のような返り値のJSONを貼り付ける
  3. 完了をクリックすると、自動て解析してスキーマを作ってくれます。

但し、Webhookのトリガーによっては、存在しないキー名などもあるので、その場合フローの実行に失敗します。必要最低限のスキーマ定義にしましょう。

{
    "id": "イベントID",
    "trigger": "アクション名",
    "source": {
        "id": "ファイルのID",
        "name": "ファイル名",
        "modified_by": {
            "type": "user",
            "id": "ユーザのID",
            "name": "ユーザ名",
            "login": "ユーザのメアド"
        },
        "parent": {
            "type": "folder",
            "id": "親フォルダのID",
            "name": "親フォルダの名前"
        }
    }
}

図:複雑なJSONのスキーマが簡単に作れる

図:キーがなくエラーになったフロー

現在時刻の取得とタイムゾーン変換

BoxのWebhook v2には日付が含まれていますが、今回は前回同様にタイムスタンプとしてPower Automate側で作ってあげます。しかし、そのまま構築すると見慣れた日付の形式ではない上に、時間帯がUTCとなっている為、日本時間ではありません。ここは、2つのコネクタを利用し、タイムゾーンの変更と日付の形式を整えてあげます。このデータをExcelに追記時に合わせて利用します。2つのコネクタは「日付」で検索すると出てくると思います。

  1. コネクタとして「現在の時刻」を追加します。(時刻で検索すると出てくる)
  2. 次にコネクタとして「タイムゾーンの変換」を追加します。(日時で検索すると出てくる)
  3. タイムゾーンの変換では、基準時間に1.のコネクタを指定します。
  4. 書式設定文字列は「yyyy/MM/dd HH:mm」を入力してカスタム形式として登録します。MMとHHが大文字の理由は、MMでないと分になってしまうという理由と、hhだと12時間表記になってしまうのでHHで24時間表記にする為です。
  5. 変換元のタイムゾーンはUTC(協定世界時)を指定します。
  6. 変換先のタイムゾーンはUTC+9:00 大阪、札幌、東京を指定します。

図:タイムゾーン変換が必要です

Excelに追記

TeamsのチャンネルにファイルとしてExcelを一個追加し、ID, ファイル名, アクション, 日時, 編集者としてタイトルを決めて、範囲をテーブル化しておきます。テーブルでないとPAからは書き込みが出来ないので、注意が必要です。

  1. Power Automateに最後のステップとして、Excel Onlineの表に行を追加を追加
  2. 場所として、アップしたTeamsのチームを選びます。
  3. アップ先指定としてはドキュメントライブラリになるので、ドキュメントを選びます。
  4. ファイルをクリックすると、アップしたファイルが出てくるので、それを選択します。
  5. テーブルでは、そのエクセル内のテーブル名が出てくるので、それを選択します。
  6. 自動的にテーブルのタイトル列を判定してくれるので、ID~編集者までの項目を埋めていきます。
  7. それぞれクリックしたら、動的コンテンツとして、JSONの解析で取得した内容が出てくるので当てはめる
  8. 日時だけは、前項のタイムゾーンの変換を利用するので、変換後の時間を割り当てます。

前回と異なり、同じ名前のキー名がいくつか存在する。例えばnameというキーは今回3つあり、どれがどのJSONスキーマのnameにあたるのか?順番をよく把握して、当て込む必要があります。

※また注意点として、trigger名にはWebhookのトリガー名が入ってるのですが、トリガーによっては存在しないキーなどもあったりするので、

  • トリガー名だけ取得するJSONの解析を一個つくっておく
  • トリガー名で条件分岐して、それぞれに別途JSONの解析とJSONスキーマを用意する
  • 書き込み先は同じファイルでOK

図:同じ名前のキーがあるので注意が必要

図:成功するとレコードが書き込まれる

Webhook v2のデメリット

実際に使ってみてわかった事ですが、Box Webhook v2は確かにv1よりも多くの情報がWebhookで飛ばされてるのと、フォルダ単位で監視できるという大きなメリットがあるのですが、一方で「削除・ゴミ箱行き」に関しては、ファイルのIDおよび作成者のID・名前くらいしかデータが入っておらず、ファイル名といった情報がトレースできません。

ファイルのIDは分かってるので、追跡自体は可能ですが、Excelファイルにログとして記録に残るのが削除した事実とID、日付のみなので、ちょっと残念な仕様です。以下はDelete、Trash時のWebhookで送られてきてるJSON情報です。なお、削除の実行者はcreated_byの情報がそれになりますので、コピーやアップロードなどもModifyではなくCreatedを使うと良いでしょう。

{
    "headers": {
        "Cache-Control": "max-age=259200",
        "Connection": "keep-alive",
        "Host": "",
        "User-Agent": "Box-WH-Client/0.1",
        "box-delivery-timestamp": "2021-04-14T23:02:48-07:00",
        "box-delivery-id": "",
        "Surrogate-Capability": """,
        "Content-Length": "393",
        "Content-Type": "application/json; charset=UTF-8"
    },
    "body": {
        "type": "webhook_event",
        "id": "WebhookイベントのID",
        "created_at": "2021-04-14T23:02:47-07:00",
        "trigger": "FILE.DELETED",
        "webhook": {
            "id": "WebhookのID",
            "type": "webhook"
        },
        "created_by": {
            "type": "user",
            "id": "作成者のID",
            "name": "作成者の氏名",
            "login": "作成者のメアド"
        },
        "source": {
            "id": "ファイルのID",
            "type": "file"
        },
        "additional_info": []
    }
}

関連リンク

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

日本語が含まれない投稿は無視されますのでご注意ください。(スパム対策)