uniface.hub

uniface.hub

ユニフェイスの開発者ブログ


Title 【Power Automate】Exchange 予定表のトリガーについて
  • 2023年1月23日
  • 上村晃史
【Power Automate】Exchange 予定表のトリガーについて

はじめに

こんにちは、ユニフェイスの上村です!
今回は Power Automate で Exchange 予定表に関する操作をフローのトリガーとした場合の処理について纏めます。主に Exchange の挙動や「イベントが追加、更新、削除されたとき (V3)」トリガーの内容が中心となるため、正直 Automate の内容は薄いです。

Power Platform を活用する場合には Exchange と連携したいシーンが多そうに感じますが、個人的にめちゃくちゃややこしかったので、忘れないうちに纏めておきます。
※ 正確ではない情報も多々ありそうなので、ご承知おきをお願いします・・・。

【参考URL:GraphAPI を利用したイベント情報の取得についてはコチラ!】

前提

Exchange で予定(以下、Exchange イベント と呼称)が「追加・更新・削除」されたタイミングでフローを実行する場合、「自動化したクラウドフロー」の下記のトリガーを使用します。

イベントが追加、更新、または削除されたとき (V3) – Office 365 Outlook

[フロー作成時のイメージ]

[フロー処理のイメージ]

自身の予定表にイベントが「追加・更新・削除」されたときに実行されて、対象の Exchange イベントの情報を取得できるようになります。

Exchange イベントの取得情報

上記のフローをテスト実行すると、以下イメージのように Exchange イベントの取得情報を確認できます。

[Exchange イベント情報の出力内容例] ※ 一部マスク済み

{
    "headers": {
        "Pragma": "no-cache",
        "Transfer-Encoding": "chunked",
        "Retry-After": "3600",
        "Vary": "Accept-Encoding",
        "x-ms-request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "Cache-Control": "no-store, no-cache",
        "Location": "https://japan-001.azure-apim.net/apim/office365/XXXXXXXXXXXXXX/datasets/calendars/v3/tables/XXXXXXXXXXXXX",
        "Set-Cookie": "ARRAffinity=XXXXXXXXXXX;Path=/;HttpOnly;Secure;Domain=office365-jw.azconn-jw.p.azurewebsites.net,ARRAffinitySameSite=XXXXXXXXXX;Path=/;HttpOnly;SameSite=None;Secure;Domain=office365-jw.azconn-jw.p.azurewebsites.net",
        "Timing-Allow-Origin": "*",
        "x-ms-apihub-cached-response": "true",
        "x-ms-apihub-obo": "false",
        "Date": "Tue, 04 Oct 2022 02:52:23 GMT",
        "Content-Type": "application/json; charset=utf-8",
        "Expires": "-1",
        "Content-Length": "2622"
    },
    "body": {
        "ActionType": "added",
        "IsAdded": true,
        "IsUpdated": false,
        "subject": "件名",
        "start": "2022-10-04T03:00:00.0000000",
        "end": "2022-10-04T04:00:00.0000000",
        "startWithTimeZone": "2022-10-04T03:00:00+00:00",
        "endWithTimeZone": "2022-10-04T04:00:00+00:00",
        "body": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; ・・・~",
        "isHtml": true,
        "responseType": "none",
        "responseTime": "0001-01-01T00:00:00+00:00",
        "id": "AAXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXAAA=",
        "createdDateTime": "2022-10-04T02:52:22.5862695+00:00",
        "lastModifiedDateTime": "2022-10-04T02:52:13.701+00:00",
        "organizer": "a.uemura@xxxxxxxxx.co.jp",
        "timeZone": "UTC",
        "seriesMasterId": "AAXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXAAA=",
        "iCalUId": "000000000000000000000000000000XXXXXXXXXXXXXXXXXXXXXXXX",
        "categories": [],
        "webLink": "https://outlook.office365.com/owa/?itemid=AAXXXXXXXXXXXXXXXXXXAAA%3D&exvsurl=1&path=/calendar/item",
        "requiredAttendees": "a.uemura@xxxxxxxxx.co.jp",
        "optionalAttendees": "",
        "resourceAttendees": "",
        "location": "",
        "importance": "normal",
        "isAllDay": false,
        "recurrence": "none",
        "reminderMinutesBeforeStart": 15,
        "isReminderOn": true,
        "showAs": "busy",
        "responseRequested": true,
        "sensitivity": "normal"
    }
}

上記の “body” の内容は「GraphCalendarEventClientWithActionType」モデルで定義されているものです。(多分)

トリガー発火のパターン

Exchange イベントの「追加・更新・削除」に伴うトリガー発火のパターンとして、基本的には大きく2つを意識する必要があると思います。

  1. 自身が開催した予定(以下、自開催予定 と呼称)
  2. 出席者として自身が追加された、他者が開催した予定(以下、他者開催予定 と呼称)

(他にも「代理人アクセス」や「共有メールボックス」といった設定などによっても変わってくるかもしれませんが、そこまでは検証できていないので割愛・・・)

上記2パターンに対する「追加・更新・削除」時の挙動は以下となります。
(実際に検証して1つ1つ差異を洗い出しました・・・)

パターン操作自予定のトリガーの挙動(アクション/回数)
自開催予定追加追加が2回、更新が複数回
※※「AD場所」の指定時 ※※
“location”(AD場所名)は最初から追加されているが、
“resourceAttendees”(AD場所メールアドレス)は

最初空文字で、後から更新時に追加される
変更更新が複数回
削除削除が1回(出力される項目が減る)
他者開催予定追加自開催と同じ(追加が2回、更新が複数回)
変更自開催と同じ(更新が複数回)
開催者が
自身の予定から

削除
更新が1回(削除はされず、削除待ち扱いで更新)
・件名に取り消し線が表示される
・件名の先頭に “Canceled: ” または “キャンセル済み: ” が付く
(⇒ ユーザー個別の地域/言語設定などが影響?)

それぞれのアクションとトリガーの発火に伴う各項目の変化は以下となります。
(追加時や更新時にトリガーが何度も発火していますが、出力内容だけ見ても差がない場合もあるので、複数回発火している理由はよく分かりません。)

アクショントリガー
発火回数
ActionTypeIsAddedIsUpdatedimportanceshowAs
予定追加時1回目addedtruefalsenormalbusy
2回目addedtruetruenormalbusy
(”resourceAttendees” の
 更新はこのタイミング)
3回目
以降
updatedfalsetruenormalbusy
予定更新時1回目
以降
updatedfalsetruenormalbusy
他者開催の
予定キャンセル時
1回updatedfalsetruehighfree
自予定削除時1回deletedfalsefalselowfree

項目別の特記事項

上記に記載した内容と重複する部分もありますが、各項目の特記事項を纏めます。

項目名特記事項
ActionType
(アクションの種類)
予定追加時:added
予定更新時:updated
他者開催の予定キャンセル時:updated
自予定から削除時:deleted
IsAdded
(追加されたか)
予定追加時:true
上記以外:false
IsUpdated
(更新されたか)
予定追加時と自予定から削除時:false
上記以外:true
subject(件名)出席者として自身が追加された、他者が開催した予定がキャンセルされた場合:
・件名に取り消し線が表示される
・件名の先頭に “Canceled: ” または “キャンセル済み: ” が付く
(※ 自予定から削除時は項目ごと出力されない)
start(開始日時)(※ 自予定から削除時は項目ごと出力されない)
end(終了日時)(※ 自予定から削除時は項目ごと出力されない)
startWithTimeZone
(タイムゾーン付きの
 開始日時)
(※ 自予定から削除時は項目ごと出力されない)
endWithTimeZone
(タイムゾーン付きの
 終了日時)
(※ 自予定から削除時は項目ごと出力されない)
body(本文)(※ 自予定から削除時は項目ごと出力されない)
isHtml(HTMLか)
responseType
(応答の種類)
responseTime
(応答した日時)
他者開催予定の招待に、承諾や辞退などを返信した日時
(※ 自予定から削除時は項目ごと出力されない)
id一意なイベント識別子。他のユーザーを出席者として共有している同じイベントの場合でも、それぞれ異なるIDとなる。
createdDateTime
(作成日時)
(※ 自予定から削除時は項目ごと出力されない)
lastModifiedDateTime
(更新日時)
(※ 自予定から削除時は項目ごと出力されない)
organizer(イベント
開催者のメールアドレス)
(※ 自予定から削除時は項目ごと出力されない)
timeZone
(タイムゾーン)
(※ 自予定から削除時は項目ごと出力されない)
seriesMasterId定期的なイベント間の一意な識別子。
(※ 自予定から削除時は項目ごと出力されない)
iCalUIdカレンダー間のイベントの一意の識別子。他ユーザーと共有している同じイベントの場合は同じIDとなる。
(※ 自予定から削除時は項目ごと出力されない)
categories(分類)リボンの [予定]タブ -> [タグ] グループ 内にある “分類”
 ⇒ ”黄の分類”, “オレンジの分類” などが定義されている
  → こんな機能あるの初めて意識した・・・
(※ 自予定から削除時は項目ごと出力されない)
webLinkOutlook Web App の対象イベントの URL
(※ 自予定から削除時は項目ごと出力されない)
requiredAttendees
(必須出席者)
複数のメールアドレスをカンマ区切りで格納。
予定追加時には反映されず空文字が入り、追って更新時に反映される。
(※ 自予定から削除時は空文字)
optionalAttendees
(任意出席者)
複数のメールアドレスをカンマ区切りで格納。
(※ 自予定から削除時は空文字)
resourceAttendees
(リソース出席者)
複数のメールアドレスをカンマ区切りで格納。
(※ 自予定から削除時は空文字)
location(場所名)複数の場所名をカンマ区切りで格納。
ADに定義されていない場所も自由入力可能。
(※ 自予定から削除時は項目ごと出力されない)
importance(重要度)他者開催の予定キャンセル時:high
自予定から削除時:low
上記以外:指定した重要度
(通常時:normal)
isAllDay
(終日イベントか)
recurrence
(繰り返しの周期)
なし、毎日、毎週、毎月、毎年
(none, daily, weekly, monthly or yearly)
recurrenceEnd
(繰り返しの終了日)
(※ 定期的な予定で「終了日」を指定した場合のみ有る項目)
(※ 自予定から削除時は項目ごと出力されない)
numberOfOccurences
(繰り返しの反復回数)
(※ 定期的な予定で「反復回数」を指定した場合のみ有る項目)
(※ 自予定から削除時は項目ごと出力されない)
reminderMinutesBeforeStart
(何分前に通知するか)
(※ 自予定から削除時は項目ごと出力されない)
isReminderOn
(通知するか)
(※ 自予定から削除時は項目ごと出力されない)
showAs
(ユーザーの状況)
他者開催の予定招待時:tentative(保留)
他者開催の予定キャンセル時:free(空き時間)
自予定から削除時:free(空き時間)
上記以外:指定した公開方法
(通常時:busy(取り込み中))
responseRequested
(応答を要求するか)
イベントの承諾または拒否時に送信者の応答を希望するか
(※ 自予定から削除時は項目ごと出力されない)
sensitivity(機密度)通常時:normal(標準)
非公開設定時:private

要注意事項

AD場所の指定について

「場所」ダイアログからAD登録された場所を選択すると、下記イメージのように [必須] と [場所] の2箇所にAD場所の名称が追加されます。

Exchange イベントの変化の流れとしては、先ず追加(または更新)時に “location” にAD場所名(”会議室1”)が指定されます。その後、追って “resourceAttendees” にAD場所メールアドレス(例:”room1@xxxxx.co.jp”)が更新されます。

しかし、手動でAD場所名だけを消して登録すると “会議室1” は出席者として扱われてしまいます。

この場合は、Exchange イベントの追加(または更新)時に “location” や “resourceAttendees” には内容が反映されず、”requiredAttendees“(必須出席者)にメールアドレスが反映されてしまう点に注意してください。
(何でこんなややこしい仕組みになっているのかは分かりません・・・)

Exchange イベントの”出席者のみ”の変更時

Outlook から Exchange イベントを更新した際、出席者全員に影響のない内容の更新(”必須出席者”を新たに1人追加したなど)をした場合、以下の確認ダイアログが表示されます。

[“出席者に更新を送信する” 確認ダイアログ]

このダイアログで「追加または削除された出席者にのみ更新を送信する」が選択されると、それ以外の出席者の Exchange イベントではトリガーが発火しないため注意が必要です。
(出席者として共有している予定でも、ユーザー個々の Exchange イベントは独立しているため)

定期的な(繰り返しの)予定について

定期的な予定を作成した場合、大きく「開始時の予定」と「それ以降の予定」とで区別されるようです。開始時の予定は【親イベント】、それ以降の繰り返しの予定は【子イベント】のような扱いとなり、【子イベント】のトリガーで出力される情報は【親イベント】のものとなってしまう模様。

【参考URL】PowerAutomateでキャンセル済みの予定を自動削除しよう – note

そのため、通常の Exchange イベントを処理するものとは別に、定期的な予定については意識して処理を実装する必要があります。

さいごに

Exchange は普段から触れているものの、改めて挙動を確認すると非常にややこしかったです。
また各種の権限に関わるものや、WEB版Outlook(OWA:Outlook Web App)まで意識する必要がでてきたりなど、思ったよりも知識が必要となり時間がとられました。。。

「イベントが追加、更新、削除されたとき (V3)」トリガーによって自動化したフローを実行する場合は、意図せず複数回の呼び出しが行われることを前提に、冪等性が担保される(何回呼ばれても同じ結果が得られる)ようにするか、前回呼び出し時の内容と比較して変更がなければスキップするなどを考慮した設計をする必要がありそうです。