はじめに
Graph APIを活用してメンションを行う
- チーム・チャネルへのメンションを行う
- 全体に対してメンションを行う
おわりに

はじめに

Microsoft Teamsでは以下5種類のメンションを行うことができます。

ユーザー
タグ
チーム
チャネル
全体

ユーザーへのメンションはすべてのチャットの種類に対して行えて、タグ・チーム・チャネルへのメンションはチャネルのスレッドにて行えますね。
全体(皆様)へのメンションはグループチャット内で行うことができます。

こちらのメンションを行うためのアクションは現在Power Automateでは"タグ"と"ユーザー"が提供されています。

learn.microsoft.com

チームとチャネル、そして全体へのメンショントークンの取得アクションは提供されていません。

ではどうやってメンションを行うかというと、"Microsoft Graph HTTP 要求を送信する"アクションを用いてGraph APIを投げます。

learn.microsoft.com

Graph APIを活用してメンションを行う

チーム・チャネルへのメンションを行う

まず、チャネルへのメッセージの投稿は以下APIを利用します。

POST /teams/{team-id}/channels/{channel-id}/messages

Body

{
  "body": {
    "content": "Hello World"
  }
}

learn.microsoft.com

{team-id}および{channel-id}は対象のチャネルへのリンクをコピーすることで取得することが可能です。

コピーしたリンクをテキストエディタなどに貼り付けて以下要素を取得することで得られます。

https://teams.microsoft.com/l/channel/{channel-id}/Sample?groupId={team-id}&tenantId={tenant-id}

もちろん"チャネルの一覧表示"アクションなどで取得した動的なコンテンツを利用するのでもOKです。

メンションを行いたい場合は、少し特殊で以下のような構成でBodyに設定することになります。

{
    "body": {
        "contentType": "html",
        "content": "<at id=\"0\">[Display Name]</at>"
    },
    "mentions": [
        {
            "id": 0,
            "mentionText": "[Display Name]",
            "mentioned": {
                "conversation": {
                    "id": "[id]",
                    "conversationIdentityType": "[Type]"
                }
            }
        }
    ]
}

"[ ]"の箇所にはそれぞれ自身の環境に合わせて値を変更します。
それぞれ以下のように設定します。

コンテンツ	設定する値
Display Name	チーム・チャネルの表示名
id	チーム・チャネルのID
Type	チームの場合は"team" チャネルの場合は"channel"

気を付ける点は、

<at id=> で設定した数値と mentions 配列内の id プロパティは同じ数値とすること
<at> タグ内のテキストと mentions 配列内の mentionText プロパティは同じテキストとすること

ですかね。

実際に設定すると以下のようになります。

https://graph.microsoft.com/v1.0/teams/@{outputs('team-id')}/channels/@{outputs('channel-id')}/messages

{
  "body": {
    "content": "<at id=\"0\">@{outputs('team-displayName')}</at> <br/>Message <br/><at id=\"1\">@{outputs('channel-displayName')}</at>",
    "contentType": "html"
  },
  "mentions": [
    {
      "id": 0,
      "mentionText": "@{outputs('team-displayName')}",
      "mentioned": {
        "user": {
          "id": "@{outputs('team-id')}",
          "conversationIdentityType": "team"
        }
      }
    },
    {
      "id": 1,
      "mentionText": "@{outputs('channel-displayName')}",
      "mentioned": {
        "conversation": {
          "id": "@{outputs('channel-id')}",
          "conversationIdentityType": "channel"
        }
      }
    }
  ]
}

チームメンションとチャネルメンションを同時に行っているので、こんな感じのメンションが送られます。

余談ですが、ユーザーへメンションしたい場合は以下になります。

{
  "body": {
    "content": "<at id=\"0\">User</at>",
    "contentType": "html"
  },
  "mentions": [
    {
      "id": 0,
      "mentionText": "User",
      "mentioned": {
        "user": {
          "id": "@{outputs('user-id')}",
          "userIdentityType": "aadUser"
        }
      }
    }
  ]
}

conversationIdentityType ではなく userIdentityType をプロパティとして設定する必要があり、 "aadUser" を値として設定する必要があるわけですね。

また、テキストは揃ってればなんでもいいのでちょっと変わったメンションを送ることも可能です。

全体に対してメンションを行う

まず、グループへのメッセージの投稿は以下APIを利用します。

POST /chats/{chat-id}/messages

Body

{
  "body": {
    "content": "Hello World"
  }
}

learn.microsoft.com

{chat-id} は対象のグループチャットへのリンクをコピーすることで取得することが可能です。
(グループチャット内で右クリックすると取得できます)

https://teams.microsoft.com/l/message/{chat-id}/{id}?context=%7B%22contextType%22%3A%22chat%22%7D

それか"チャットまたはチャネルでメッセージを投稿する"アクションで対象のグループチャットを選択して、コードビューで調べるという手もあります。

body/recipient の値が {chat-id} です。

{
  "type": "OpenApiConnection",
  "inputs": {
    "parameters": {
      "poster": "Flow bot",
      "location": "Group chat",
      "body/recipient": "{chat-id}",
      "body/messageBody": ""
    },
    "host": {
      "apiId": "/providers/Microsoft.PowerApps/apis/shared_teams",
      "connection": "shared_teams",
      "operationId": "PostMessageToConversation"
    }
  },
  "runAfter": {}
}

こちらも"チャットの一覧表示"アクションなどで取得した動的なコンテンツを利用するのでもOKです。

さて、グループチャットへのメンションも先ほど行ったチャネルへのメンションと同じやり方で行えばよいのですが、1つ問題があります。

"Microsoft Graph HTTP 要求を送信する"アクションで許可されているセグメントは、第一セグメントが " /teams, /me, /users" となっています。

Microsoft Team エンドポイントに対して呼び出す Microsoft Graph REST API リクエストを作成します。次のセグメントがサポートされています: 1st segment: /teams, /me, /users 2nd segment: channels, chats, installedApps, messages, pinnedMessages

learn.microsoft.com

APIリファレンスの通りに以下を設定してしまうとエラーが返ってきます。

https://graph.microsoft.com/v1.0/chats/@{outputs('conversation-id')}/messages

アクション 'Microsoft_Graph_HTTP_要求を送信する' に失敗しました: URI path is not a valid Graph endpoint, path is neither absolute nor relative or resource/object is not supported for this connector. Resources: teams,me,users Objects: channels,chats,installedApps,messages,pinnedMessages

有効なエンドポイントではないと怒られていますね。

これを回避するためには以下のように設定する必要があります。

https://graph.microsoft.com/v1.0/me/chats/@{outputs('conversation-id')}/messages

{
  "body": {
    "contentType": "html",
    "content": "<at id=\"0\">皆様</at> <br/>Message"
  },
  "mentions": [
    {
      "id": 0,
      "mentionText": "皆様",
      "mentioned": {
        "conversation": {
          "id": "@{outputs('conversation-id')}",
          "conversationIdentityType": "chat"
        }
      }
    }
  ]
}