Office 365 Users の UserProfileV2 アクションについての話題です。
Power Apps や Power Automate でメールアドレスから表示名を取得したい場合等で Office 365 Users（日本語環境では”Office 365 ユーザー”）コネクターを使いますよね。UserProfileV2 が提供されたコトにより、第二引数で取得するフィールドを指定できるようになったので調べてみた、です。
おことわり
記事投稿時点(2022/04/17)における仕様、画面、情報にて調査・検証しております。記事内容に関しては著者の調査に基づく結果となっております。詳細情報や厳密な仕様は公式情報をご確認ください。
また、投稿時点における歴史の断片として記録を残す意図があります。投稿日以降の VerUp で仕様が変更された場合でも、当記事を最新化・更新する予定は現状ありません。Update がきて、コレはまた大きく変わったなぁ、みたいな際は必要に応じて新規記事を作成するかもです。
以上を予めご理解いただいたうえで読み進めてください。
Office 365 Users コネクター
Microsoft／Office 365 のユーザーに関連する情報を取得できます。組織内のメールアドレス（厳密には UPN）などから氏名（表示名／DisplayName）を取得したり、電話番号などを確認できます。
アクションの V1、V2
前述の Docs を確認いただくと、アクションに V1 と V2 が記載されています。基本的に V1 は非推奨になっています。新規にアプリやフローを作成する際は V2 を利用しましょう。
V2 の説明を確認すると、Graph API の URL が記載されているアクションが確認できます。おそらく、V2 になった際に裏側で Graph API を利用するようになったのではないかな、と想定されますね。
上イメージで参照先に指定されている URL はコチラ。ユーザー情報を取得する Graph API です。
UserProfileV2 アクション
本題の「ユーザープロファイルを取得する (V2)」です。データソースにはメールアドレスだけ管理しておいて、画面表示等のタイミングで最新の表示名や電話番号を取得し画面表示する等のシーンで必須アクションですね。
Power Apps におけるアクションの構文は下記です。
Office365ユーザー.UserProfileV2(
UPN または ID //第一引数 ※必須
,{'$select':"選択するフィールドの一覧(カンマ区切り)"} //第二引数 ※任意
)
Power Automate のアクションでは第一、第二引数が明確に入力欄がわかれるので混乱は少ないでしょうから割愛。
取得できるフィールド
UserProfileV2 アクションで取得できる結果です。 GraphUser_V1 と表記されています。
| 名前 | パス | 型 | 説明 |
|---|---|---|---|
| 自分について | aboutMe | string | 自分について |
| アカウントが有効? | accountEnabled | boolean | アカウントが有効な場合は true、それ以外の場合は false。 このプロパティは、ユーザーの作成時に必要です。 |
| 誕生日 | birthday | date-time | 誕生日 |
| 勤務先電話番号 | businessPhones | array of string | 勤務先電話番号 |
| 市 | city | string | ユーザーが所在する市区町村。 |
| 会社名 | companyName | string | ユーザーが勤務している会社の名前。 |
| 国 | country | string | ユーザーが所在する国/地域; 例: 「米国」または「英国」。 |
| 部署 | department | string | ユーザーが勤務する部署の名前。 |
| 表示名 | displayName | string | 表示名 |
| 名前 | givenName | string | 名前 |
| 採用日 | hireDate | date-time | 採用日 |
| ID | id | string | ID |
| 関心 | interests | array of string | 関心 |
| 役職 | jobTitle | string | 役職 |
| メール | string | メール | |
| ニックネーム | mailNickname | string | ユーザーのメール エイリアス。 このプロパティは、ユーザーの作成時に指定する必要があります。 |
| 携帯電話 | mobilePhone | string | 携帯電話 |
| 自分のサイト | mySite | string | 自分のサイト |
| オフィスの場所 | officeLocation | string | オフィスの場所 |
| 過去のプロジェクト | pastProjects | array of string | 過去のプロジェクト |
| 郵便番号 | postalCode | string | ユーザーの住所の郵便番号。 郵便番号は、ユーザーの国/地域に固有のものです。 アメリカ合衆国では、この属性には郵便番号が含まれています。 |
| 優先する言語 | preferredLanguage | string | 優先する言語 |
| 希望する名前 | preferredName | string | 希望する名前 |
| 責任 | responsibilities | array of string | 責任 |
| 学校 | schools | array of string | 学校 |
| スキル | skills | array of string | スキル |
| 完了状態 | state | string | 完了状態 |
| 番地 | streetAddress | string | 番地 |
| 姓 | surname | string | 姓 |
| ユーザー プリンシパル名 | userPrincipalName | string | ユーザー プリンシパル名 |
| ユーザーの種類 | userType | string | ユーザーの種類 |
なお、上記の項目が M365 のどの項目に連動しているか？は下記 Ippu.I
さんのブログが詳しいので、興味がある方はあわせてご確認ください。
Power Automate Power Apps Office365ユーザーコネクタで取得できる情報の設定場所一覧
Power Apps における第二引数の利用
Power Apps で第二引数へ n個 を指定する際の具体例が皆無で「どうやって書けばいいのさ！」と調査している時に悩んだのですよ。原因はとある定数のせいなんですが。同じような苦労をする方が1名でも減れば嬉しいなぁ、と思って Power Apps における UserProfileV2 アクションの第二引数を利用する際の書き方を案内しておきます。
指定するフィールドが1つの場合
1つの場合は簡単です。例えば、誕生日(birthday)を指定する場合は下記です。アクションの結果を取得したい際は、ドット（.)で続けて該当フィールドを指定してください。
Office365ユーザー.UserProfileV2("UPN",{'$select':"birthday"})
指定するフィールドが n 個の場合
'$select' の後に、取得したいフィールド名を文字列でカンマ区切り指定します。例えば、表示名(displayName)と誕生日の2つを指定してみます。
Office365ユーザー.UserProfileV2("UPN",{'$select':"displayName,birthday"})
上記のように、複数フィールドを指定する場合はカンマ区切りで並べれば OK です。
第二引数に関するアレコレ
指定する第二引数ですが ”DisplayName” や ”displayNAME” 等でも問題無く動作しています。試した限りでは第二引数の文字列は大文字・小文字を意識していない、と見受けられました。
なお、存在しないフィールドを指定してもエラーになりません。結果が取得できないだけなので、スペルミスは非常に気づきにくいです。目的の情報が意図した通りに取得できているか？の確認は必須ですね。
加えて、Power Apps では ”DisplayName” という定数（中身は小文字の ”displayname”）が予め準備されています。この定数を利用する場合は第二引数でダブルコーテーションが不要になるんですよ。コイツは混乱するなぁ…というポイントです。どこかに説明が明記されているのか…「他の定数もあるのか！？」→ 調べても情報見つけられないし、試しても見つからない → 2つ以上指定する場合どうするのさ！！ってなりました(汗
公式情報でベストプラクティスが案内されるまでは、個人的に文字列でチャンと指定しよう、と思いましたｗ
第二引数の効果
Docs に記載あるとおり、取得するフィールドを絞り込みできます。アクションの結果を数式バーで覗いてみると理解しやすいと思います。
第二引数の指定無し
上イメージは取得結果の途中までスクリーンショットした状態ですが、スクロールをすることで他のフィールドも取得されていることが確認できます。是非、お手元の環境で実際に試してください。
第二引数を指定した場合
結果が指定したフィールドのみになっているコトが確認できますね。必要ない項目をそぎ落としてアクションの結果が返却される、という状態と表現しても良いでしょう。
Power Apps の監視結果を確認してみる
Power Apps の監視で動作を確認するのもおススメです。前述同様に指定したフィールドのみ API から返却されている様子が確認できます。
第二引数を指定しない場合がコチラ。該当フィールドがズラっと返却されているのが確認できます。一部、配列になっていたり、と取得したフィールドの型も認識できますね。
下イメージは、第二引数で表示名のみに限定した監視の結果です。
第二引数を指定して絞り込んだほうがスッキリしてます。
まとめ
- Office 365 Users（Office 365 ユーザー）コネクターのアクションは V2 を使いましょう
- UserProfileV2 アクションは第二引数が指定可能
- 取得したいフィールドを限定できる
- 任意の引数なので省略しても問題ありません
- 第二引数の書き方にはご注意（スペルミスでもエラーにならない）
Office 365 Users（Office 365 ユーザー）コネクターは、ユーザー情報を取り扱うアプリであれば利用頻度が高いコネクターだと思います。データ準備が難しいので検証までは実施してませんが、大量のデータを処理する場合に取得するフィールドを限定するとレスポンスが改善されると予想されます。フィールドの絞込みは覚えておいて損はないかな、と思いますね。
それでは皆さま、素晴らしい Power Platform Life を！！