はじめに

変更箇所が多かったので、書き直しました。ここはここで、旧仕様のために残しておきます。

mofumofupower.hatenablog.com

2020/07/01 アクション追加に伴い加筆しました

Microsoft Teamsで、チーム内のユーザーや、チャンネル、チームに対しておくる"@メンション"に関して、Power Automateで提供されているTeamsコネクターのアクションでどのように実現するのかご紹介します。

なお、本投稿の中では Flow botからユーザーへのメンション に話題を限定します。ユーザーとして、他のユーザーへのメンションや、チャンネルへのメンションについてはGraph APIを利用することで実現できますので、こちらのブログを参考にしてください。

[2020/06/23 追記] 公式のドキュメントでAdaptive Cardsを利用してメンションを送る方法が公開されました。

Text formatting in cards - Teams | Microsoft Docs

Power AutomateからTeamsにメンション

1. 通常のメッセージ投稿

Flow botからチャンネルに対してメッセージを送るアクション、"メッセージをフローボットとしてチャンネルに投稿する"では、プレーンなテキスト以外に、マークダウン形式、一部のXML(HTML)形式を利用する事が可能です。

(参考: Supported text formatting in conversations - Teams | Microsoft Docs)

メンションをユーザーに送る場合には、専用のタグを利用します。 <at>user@example.com</at> のように、タグのなかにメンションを送りたい相手のメールアドレスを含めることで、Teamsのチャンネル上でメンションとしてメッセージが表示されます。

f:id:mofumofu_dance:20200429232457p:plain

2. アダプティブカードを利用した場合の投稿

アダプティブカードを利用した場合の投稿については kenichiro nakamuraさんのブログ投稿で解説されています。

dev.to

アダプティブカードを利用した場合の投稿で必要になるユーザーの情報は、表示名および GraphAPIで取得できるユーザーID (Azure ADでのユーザーオブジェクトID) の2つです。

アクションには以下のようなJSONを入力します。重要なのは"msteams"以下のデータの記述で、これによって、メンションする対象のユーザー情報を規定しています。

{
   "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", 
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
      {
        "type": "TextBlock",
        "text": "Hi <at>ユーザーの表示名</at>"
      }
    ],
    "msteams": {
      "entities": [
        {
          "type": "mention",
          "text": "<at>ユーザーの表示名</at>",
          "mentioned": {
            "id": "8:orgid:Graph APIで取得できるユーザーID",
            "name": "ユーザーの表示名"
          }
        }
      ]
    }
}

Power Automate上で、ユーザーの表示名およびIDを取得するには、Office 365ユーザーコネクタの "ユーザープロフィールの取得 (V2)" アクションを利用します。あとは、上記のJSONと、ユーザープロフィールの取得アクションで得られた結果、動的なコンテンツを合わせて、アダプティブカードを送信します。

f:id:mofumofu_dance:20200430001315p:plain

Adaptive Card DesignerのページでJSONをコピーした場合には、貼り付けたJSONに"msteams"以下のブロックを足せば、(Bodyでメンションを入れていれば)メンションを実行できます。

f:id:mofumofu_dance:20200430003111p:plain

注意事項

アダプティブカードを送信する際、メンションのタグが利用可能なのはTextBlock内に限られます。FactSetやRichText内では利用できません。
メンションには上記JSONのうち、"msteams"以下のブロックが必須です。ただし、ここに含めたメンション先は必ず"body"の中で利用してください。(エラーになる)
メンションは複数のユーザーに対して行えます。その場合には "entities":[.....]内を以下のように書きます。

      "entities": [
        {
          "type": "mention",
          "text": "<at>ユーザーの表示名1</at>",
          "mentioned": {
            "id": "8:orgid:Graph APIで取得できるユーザーID1",
            "name": "ユーザーの表示名1"
          }
        },
        {
          "type": "mention",
          "text": "<at>ユーザーの表示名2</at>",
          "mentioned": {
            "id": "8:orgid:Graph APIで取得できるユーザーID2",
            "name": "ユーザーの表示名2"
          }
        }
      ]

これで、TextBlockで<at>ユーザーの表示名1</at> ...... <at>ユーザーの表示名2</at>のように、複数ユーザーにもメンションできます。

3. 応答を待つカードを投稿する際の注意事項

Power Automateでは、アダプティブカードの送信アクションにもう1種類、ユーザーの応答を待つアクションがあります。 "アダプティブカードを Teams チャネルに投稿して応答を待機"です。

このアクションは、Power Automateの試験的機能を有効にすることで、組み込みのアダプティブカードデザイナーを利用できるという利点がありますが (詳細は過去の投稿を参照) 動的なコンテンツを利用する場合には少し癖があります。

おすすめの手順は

まず試験的機能を有効にしておいて、カードデザインを作成する。その際、メンションを入れる位置をわかりやすくしておきましょう。(日本語入れる等で)
フローを一度保存します。(大事なので忘れずに)
試験的機能をオフにして、フローを開きなおします。
投稿アクションのメッセージ部分が生身のJSONに置き換わるので、ここに動的コンテンツ＆"msteams"以下の構造を入れます。

すこし手数がかかりますが、おそらくこれが最も簡単かと思います。

f:id:mofumofu_dance:20200430005611p:plain — 応答を待つ場合の手順図解

このように手順が必要ではありますが、無事、応答を待つアクションでもメンションを送ることができました。

f:id:mofumofu_dance:20200430005733p:plain

まとめ・謝辞

今回はPower AutomateからMicrosoft Teamsのユーザーにメンションを送る (Flow botとしてメッセージを投稿する)方法を2種類、紹介しました。

利用ケースとしては、チケットが作成された際のお知らせをチャンネルに送り、かつ担当者にメンションしたり、Plannerのタスク期限をお知らせするときに、Assign Toの人にメンションしたりなどなど、通常のメッセージだけでなく、アクショナブルなアダプティブカードを活用する方法も考えられます。これまであきらめていた方も、ぜひトライしてみてください。

最後に、本投稿を書くにあたり、アダプティブカードでのメンションについて丁寧に教えていただいた、kenichiro nakamuraさん, 一緒に検証してくださり、いつも素晴らしいアイデアを投稿されているLISAさんに心よりお礼申し上げます。