- 2023年1月23日
はじめに
こんにちは、ユニフェイスの上村です！
今回は 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 イベントの「追加・更新・削除」に伴うトリガー発火のパターンとして、基本的には大きく２つを意識する必要があると思います。
- 自身が開催した予定（以下、自開催予定 と呼称）
- 出席者として自身が追加された、他者が開催した予定（以下、他者開催予定 と呼称）
（他にも「代理人アクセス」や「共有メールボックス」といった設定などによっても変わってくるかもしれませんが、そこまでは検証できていないので割愛・・・）
上記２パターンに対する「追加・更新・削除」時の挙動は以下となります。
（実際に検証して１つ１つ差異を洗い出しました・・・）
| パターン | 操作 | 自予定のトリガーの挙動（アクション／回数） |
|---|---|---|
| 自開催予定 | 追加 | 追加が２回、更新が複数回 ※※「AD場所」の指定時 ※※ “location”（AD場所名）は最初から追加されているが、 “resourceAttendees”（AD場所メールアドレス）は 最初空文字で、後から更新時に追加される |
| 変更 | 更新が複数回 | |
| 削除 | 削除が１回（出力される項目が減る） | |
| 他者開催予定 | 追加 | 自開催と同じ（追加が２回、更新が複数回） |
| 変更 | 自開催と同じ（更新が複数回） | |
| 開催者が 自身の予定から 削除 | 更新が１回（削除はされず、削除待ち扱いで更新） ・件名に取り消し線が表示される ・件名の先頭に “Canceled: ” または “キャンセル済み: ” が付く （⇒ ユーザー個別の地域／言語設定などが影響？） |
それぞれのアクションとトリガーの発火に伴う各項目の変化は以下となります。
（追加時や更新時にトリガーが何度も発火していますが、出力内容だけ見ても差がない場合もあるので、複数回発火している理由はよく分かりません。）
| アクション | トリガー 発火回数 | ActionType | IsAdded | IsUpdated | importance | showAs |
|---|---|---|---|---|---|---|
| 予定追加時 | １回目 | added | true | false | normal | busy |
| ２回目 | added | true | true | normal | busy | |
| （”resourceAttendees” の 更新はこのタイミング） | ３回目 以降 | updated | false | true | normal | busy |
| 予定更新時 | １回目 以降 | updated | false | true | normal | busy |
| 他者開催の 予定キャンセル時 | １回 | updated | false | true | high | free |
| 自予定削除時 | １回 | deleted | false | false | low | free |
項目別の特記事項
上記に記載した内容と重複する部分もありますが、各項目の特記事項を纏めます。
| 項目名 | 特記事項 |
|---|---|
| ActionType （アクションの種類） | 予定追加時：added 予定更新時：updated 他者開催の予定キャンセル時：updated 自予定から削除時：deleted |
| IsAdded （追加されたか） | 予定追加時：true 上記以外：false |
| IsUpdated （更新されたか） | 予定追加時と自予定から削除時：false 上記以外：true |
| subject（件名） | 出席者として自身が追加された、他者が開催した予定がキャンセルされた場合： ・件名に取り消し線が表示される ・件名の先頭に “Canceled: ” または “キャンセル済み: ” が付く （※ 自予定から削除時は項目ごと出力されない） |
| start（開始日時） | （※ 自予定から削除時は項目ごと出力されない） |
| end（終了日時） | （※ 自予定から削除時は項目ごと出力されない） |
| startWithTimeZone （タイムゾーン付きの 開始日時） | （※ 自予定から削除時は項目ごと出力されない） |
| endWithTimeZone （タイムゾーン付きの 終了日時） | （※ 自予定から削除時は項目ごと出力されない） |
| body（本文） | （※ 自予定から削除時は項目ごと出力されない） |
| isHtml（HTMLか） | ー |
| responseType （応答の種類） | ー |
| responseTime （応答した日時） | 他者開催予定の招待に、承諾や辞退などを返信した日時 （※ 自予定から削除時は項目ごと出力されない） |
| id | 一意なイベント識別子。他のユーザーを出席者として共有している同じイベントの場合でも、それぞれ異なるＩＤとなる。 |
| createdDateTime （作成日時） | （※ 自予定から削除時は項目ごと出力されない） |
| lastModifiedDateTime （更新日時） | （※ 自予定から削除時は項目ごと出力されない） |
| organizer（イベント 開催者のメールアドレス） | （※ 自予定から削除時は項目ごと出力されない） |
| timeZone （タイムゾーン） | （※ 自予定から削除時は項目ごと出力されない） |
| seriesMasterId | 定期的なイベント間の一意な識別子。 （※ 自予定から削除時は項目ごと出力されない） |
| iCalUId | カレンダー間のイベントの一意の識別子。他ユーザーと共有している同じイベントの場合は同じＩＤとなる。 （※ 自予定から削除時は項目ごと出力されない） |
| categories（分類） | リボンの [予定]タブ -> [タグ] グループ 内にある “分類” ⇒ ”黄の分類”, “オレンジの分類” などが定義されている → こんな機能あるの初めて意識した・・・ （※ 自予定から削除時は項目ごと出力されない） |
| webLink | Outlook 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登録された場所を選択すると、下記イメージのように [必須] と [場所] の２箇所にAD場所の名称が追加されます。
Exchange イベントの変化の流れとしては、先ず追加（または更新）時に “location” にAD場所名（”会議室１”）が指定されます。その後、追って “resourceAttendees” にAD場所メールアドレス（例：”room1@xxxxx.co.jp”）が更新されます。
しかし、手動でAD場所名だけを消して登録すると “会議室１” は出席者として扱われてしまいます。
この場合は、Exchange イベントの追加（または更新）時に “location” や “resourceAttendees” には内容が反映されず、”requiredAttendees“（必須出席者）にメールアドレスが反映されてしまう点に注意してください。
（何でこんなややこしい仕組みになっているのかは分かりません・・・）
Exchange イベントの”出席者のみ”の変更時
Outlook から Exchange イベントを更新した際、出席者全員に影響のない内容の更新（”必須出席者”を新たに１人追加したなど）をした場合、以下の確認ダイアログが表示されます。
[“出席者に更新を送信する” 確認ダイアログ]
このダイアログで「追加または削除された出席者にのみ更新を送信する」が選択されると、それ以外の出席者の Exchange イベントではトリガーが発火しないため注意が必要です。
（出席者として共有している予定でも、ユーザー個々の Exchange イベントは独立しているため）
定期的な（繰り返しの）予定について
定期的な予定を作成した場合、大きく「開始時の予定」と「それ以降の予定」とで区別されるようです。開始時の予定は【親イベント】、それ以降の繰り返しの予定は【子イベント】のような扱いとなり、【子イベント】のトリガーで出力される情報は【親イベント】のものとなってしまう模様。
【参考URL】PowerAutomateでキャンセル済みの予定を自動削除しよう – note
そのため、通常の Exchange イベントを処理するものとは別に、定期的な予定については意識して処理を実装する必要があります。
さいごに
Exchange は普段から触れているものの、改めて挙動を確認すると非常にややこしかったです。
また各種の権限に関わるものや、WEB版Outlook（OWA：Outlook Web App）まで意識する必要がでてきたりなど、思ったよりも知識が必要となり時間がとられました。。。
「イベントが追加、更新、削除されたとき (V3)」トリガーによって自動化したフローを実行する場合は、意図せず複数回の呼び出しが行われることを前提に、冪等性が担保される（何回呼ばれても同じ結果が得られる）ようにするか、前回呼び出し時の内容と比較して変更がなければスキップするなどを考慮した設計をする必要がありそうです。