Viva Engage Praiseの受け手（宛先）はAPIで取得できる？Network Data Exportとshared_message_idの実務対応

Viva Engage（旧 Yammer）のPraise（称賛）メッセージをエクスポートして分析したいのに、「誰に向けたPraiseなのか」が取得できず手が止まるケースは少なくありません。さらに、他ユーザーのPraiseを共有（シェア）した投稿では、見た目はカードで表示されるのに、エクスポート結果には共有側の本文だけが残ることがあります。ここでは現行APIの仕様を整理し、運用とデータ設計で“実務として回る”落としどころをまとめます。

Network Data Export APIで取れる情報／取れない情報を整理する
Praiseの「受け手（宛先）」がAPIで取得できない理由を、公式仕様ベースで説明する
@メンション運用やレポート設計の見直しなど、現実的な代替策を具体例つきで提示する
共有（シェア）されたPraiseを shared_message_id で紐付けて分析する手順を示す

Viva EngageのPraiseメッセージで「対象ユーザー（宛先）」はAPIから取得できるのか

結論から言うと、現状の公式仕様では、Praiseの「受け手（対象ユーザー）」をAPIから直接取得する手段は提供されていません。Network Data Export APIであっても、Core APIやMicrosoft Graphであっても、Praiseの宛先を返すフィールドやエンドポイントは用意されていない、という扱いになります。

まず押さえる：Network Data Export APIで取得できる範囲

Network Data Export APIは、Viva Engageネットワーク内のデータをZIP（CSV群＋必要に応じて添付ファイル）としてエクスポートする仕組みです。期間指定の一括出力に向いており、日次で小さく回す運用が推奨されています。

必要な権限と前提

Data Export系のAPIは、誰でも実行できるものではなく、Viva Engageの管理権限（Verified Administrator など）を前提にしています。運用開始前に「誰が、どの端末から、どの頻度でエクスポートを回すか」を決め、ログ管理や監査対応もセットで設計しておくと後が楽です。

API	主用途	実行主体（イメージ）	注意点
Network Data Export API	ネットワーク全体のメッセージ/ユーザー/グループ等をまとめて出力	Verified Administrator	ZIPが大きくなりやすいので期間を絞る／日次運用が安全
Core API（Yammer REST）	アプリが必要な範囲でメッセージを読み書き	一般ユーザー/アプリ	大量エクスポート向けではない（キャッシュ前提）

エクスポート実行のイメージ（パラメータの考え方）

Network Data Export APIは since / until（期間）や model（出力対象）を指定できます。現場では「Messages.csvだけ欲しい」「添付ファイルは不要（CSVだけでよい）」といった要件が多いので、最初から小さく始めるのがコツです。

# 期間指定（例）：since〜until
https://www.yammer.com/api/v1/export?since=2025-01-01T00:00:00+00:00&until=2025-01-02T00:00:00+00:00

# Messageモデルのみ（例）：Messages.csvなどメッセージ関連を中心に
https://www.yammer.com/api/v1/export?since=2025-01-01T00:00:00+00:00&model=Message&include=csv

上記はあくまで考え方の例ですが、ポイントは「モデルを絞る」「添付をいったん除外する」「期間を短くする」の3点です。処理が安定してから、必要に応じて添付込みや期間拡大に広げます。

Messages.csvで分かること／分からないこと（Praiseの観点）

Messages.csv（および編集履歴のMessageVersions.csv）には、本文（body / html_body）、送信者（sender_id / sender_name / sender_email）、添付情報（attachments）、そしてメッセージ種別（message_type）などが含まれます。Praiseの場合は message_type が praise、praise_type が埋まる想定です。

項目	Messages.csvでの扱い（例）	分析での使いどころ	限界
送信者	sender_id / sender_name / sender_email	「誰がPraiseを送ったか」の集計	受け手は分からない
本文	body / html_body	キーワード分析、@メンション解析、ハッシュタグ傾向	本文に受け手を書かない運用だと推定不能
メッセージ種別	message_type（normal / praise / poll / announcement）	Praiseのみ抽出、種別別の投稿数	種別は分かるが、宛先は別問題
Praise種別	praise_type	どのバッジ／称賛タイプが多いか	誰に付与されたかは分からない
添付情報	attachments（OGO情報として id / url / title / description など）	共有カードの参照、添付ファイルの有無	attachmentsだけで受け手が取れる保証はない

Messages.csvのプロパティ一覧には「受け手ユーザーID」「宛先ユーザーID」といった概念が登場しません。つまり、エクスポートだけで「誰を褒めたか」を機械的に確定できる形では出てこない、というのが現実です。

Core APIやMicrosoft Graphで取れないのか

「Data Exportに無いならCore APIで取れるのでは？」と考えるのは自然ですが、Praiseの受け手に関しては同様に難しいです。MicrosoftのQ&Aでも、Core APIやMicrosoft GraphにPraiseの対象ユーザーを返すエンドポイントは存在しない旨が明示されています。

Microsoft Graph側のViva Engage APIは、現時点では主にコミュニティ管理とロール管理にフォーカスしています。Graphで「投稿本文」「Praiseメッセージ内容」「受け手」を横断取得する、といった用途には合致しません。

観点	Network Data Export API	Core API（Yammer REST）	Microsoft Graph（Viva Engage）
用途	ネットワーク全体の大量エクスポート	アプリ向けの読み書き（CRUD）	コミュニティ／ロールなど管理系
メッセージ本文	○（Messages.csv）	○（messages系）	△（メッセージ取得は主用途ではない）
Praise判定	○（message_type: praise）	△（メッセージ種別は取得できるが、受け手は別問題）	×
Praiseの受け手（対象ユーザー）	×	×	×
共有の紐付け（shared_message_id）	△（データに含まれる場合は突合可能）	○（ID指定で取得）	×

なお、Core API自体はメッセージ取得（messages.json など）を含むCRUDを提供しますが、公式にも「大量エクスポート用途ではない」ことが明確にされています。全件分析の母集団を作るなら、まずData Exportで土台を作り、必要箇所だけCore APIで補う方針が安全です。

「受け手が取れない」前提で、実務として成り立たせる方法

Praiseの宛先をAPIで取れない以上、ここからは「完璧に当てる」ではなく「現場が困らない精度で寄せる」ための設計が重要になります。ポイントは、運用ルールとデータ解析をセットで考えることです。

運用ルールで補う：本文に@メンションを必須化する

最も現実的で、導入コストに対して効果が高いのが「Praise本文に必ず対象者を@メンションしてもらう」運用です。例えば「@山田さん、いつもありがとう！」のように書いてもらえば、エクスポート結果から“実質的な受け手”を推定できます。

Core APIの messages.json のレスポンスには、メンションしたユーザーID（notified_user_ids）が含まれるため、@メンション運用と相性が良いです。Data Export側で完結させたい場合でも、html_body や body からメンション表記を抽出し、ユーザー辞書（Users.csv 等）に寄せることで同様のことができます。

ルール案	メリット	注意点
本文の先頭に対象者を@メンション	解析が簡単（先頭のメンション＝受け手）	複数名Praiseを許すかどうかを決める
「#praise_to」など固定タグ＋@メンション	誤メンションや雑談メンションを除外しやすい	投稿体験が少し硬くなる
テンプレ文（例：「To: @○○ / 理由: …」）	人間にも機械にも読みやすい	運用浸透に時間がかかる

@メンション解析を「壊れにくく」する実装のコツ

実装では、単純に文字列から「@」を探すだけだと誤検知が増えます。おすすめは、次のように“確からしさ”を段階的に上げる設計です。

第一候補：本文先頭の@メンション（運用ルールがあるなら最優先）
第二候補：notified_user_ids（Core APIが取れる場合）
第三候補：html_body 内のメンション用タグ（エクスポートのみの場合）
最終手段：本文中の表示名一致（同姓同名があると危険なのでスコア低）

また、分析基盤側では「受け手を1人に固定」するより、候補ユーザーを配列で保持し、ルールに従って代表値を決める方が後から仕様変更に強くなります。例えば、以下のようなデータモデルにすると運用変更（複数称賛を許可する等）にも追従しやすいです。

{
  "message_id": 1234567890,
  "message_type": "praise",
  "sender_id": 111,
  "praise_target_candidates": [222, 333],
  "praise_target_primary": 222,
  "target_inferred_by": "body_head_mention",
  "confidence": 0.9
}

レポート要件を見直す：取れる情報で“価値が出る指標”に寄せる

「誰が誰を褒めたか」を100%正確に出すのが難しい場合でも、組織のコミュニケーション改善に役立つ指標は作れます。特に、Viva EngageのPraiseは“文化の可視化”に向いているため、設計を少し変えるだけで経営／人事／コミュニティ運営に刺さるレポートになります。

指標例	必要データ	示せること
送信者別Praise数（週次／月次）	sender_id, created_at, message_type	称賛を発信する人が増えているか
コミュニティ（グループ）別Praise数	group_id, group_name, message_type	盛り上がっている場／沈黙している場の把握
praise_type別トレンド	praise_type, created_at	称賛の傾向（挑戦／協力／感謝など）の変化
共有回数（どのPraiseが拡散したか）	shared_message_id（後述）	共感を呼ぶ称賛の特徴、好事例の抽出

Messages.csv には message_type（praise含む）や praise_type、送信者、グループ情報が含まれるため、これらの指標はData Export中心で組み立てられます。

機能要望を出す：Ideasでフィードバックする

受け手情報が取れないのは、分析・監査・人材育成など多くの用途で制約になります。MicrosoftのQ&Aでも、改善要望はフィードバックコミュニティ（Ideas）へ投稿することが推奨されています。組織として強い要件があるなら、具体的なユースケース（例：コンプライアンス監査、表彰制度、エンゲージメント施策）とともに要望を出しておく価値があります。

共有（シェア）されたPraiseの内容をリンク／取得する方法

次に、よくある“つまずきポイント”が共有投稿です。Viva Engage上では「自分のコメント＋下に元Praiseカード」という見た目で表示されますが、Network Data Exportで見ると共有側の本文しか取れず、カード部分（共有されたPraise本体）が欠落しているように見えます。

なぜ共有されたPraiseが本文に入らないのか

共有されたPraiseのカードは、UI上はリッチに表示されますが、API上はOpen Graph Object（OGO）などのリッチカードが添付（attachments）として扱われる形になります。つまり、共有側の本文にPraise本文が“埋め込まれている”わけではありません。

Data Export側でも、attachments にはOGO情報（id / url / title / description など）が出力されますが、ここだけを見て共有元メッセージを完全に復元できるとは限りません。共有の本体を確実に辿るには、次の「shared_message_id」を使うのが基本になります。

shared_message_idで共有元メッセージを特定する

あるメッセージが別メッセージ（Praiseを含む）を共有している場合、そのメッセージには shared_message_id が付与されます。また、ケースによっては attachments の配列内にも共有元への参照が含まれることがあります。

レコード	主キー	共有を示すキー	見た目上の内容	データ上の実体
共有側メッセージ	id	shared_message_id	コメント文＋カード	コメント本文＋（カードは参照/添付）
共有元Praise	id（= shared_message_id）	―	Praise本文＋バッジ＋宛先表示	Praiseメッセージ本体（message_type: praise）

紐付け手順：Data Exportだけで完結させる（おすすめ）

Network Data Export APIでMessages.csvを取得し、全メッセージを取り込む
メッセージID（id）でハッシュ／索引を作る（DBなら主キー）
共有側メッセージのshared_message_idを使って、idが一致するレコードを検索する
共有側（コメント）と共有元（Praise）をアプリ側で結合してレポートする

この方法のメリットは、Core APIのレート制限や権限差分に引っ張られにくく、日次で安定して回せることです。Network Data Export APIはZIPでCSVを返し、期間指定で出力できるため、ETL（取り込み→正規化→集計）に向きます。

SQLのイメージは以下です（共有側と共有元を左結合）。

SELECT
  s.id              AS share_message_id,
  s.sender_id       AS share_sender_id,
  s.body            AS share_body,
  s.shared_message_id,
  o.id              AS original_message_id,
  o.sender_id       AS original_sender_id,
  o.message_type    AS original_message_type,
  o.body            AS original_body,
  o.praise_type     AS original_praise_type
FROM messages s
LEFT JOIN messages o
  ON o.id = s.shared_message_id
WHERE s.shared_message_id IS NOT NULL;

Core APIで取りに行く場合の注意点

Data Exportで共有元が見つからない、または“その時点の最新情報”だけ補完したい場合に、shared_message_id をキーにCore APIで単発取得する選択肢があります。Core APIはメッセージ系のGETエンドポイントを提供しますが、そもそも大量エクスポート用途ではないこと、キャッシュ設計が重要になることを踏まえて使うのが安全です。

また、共有元がOpen Graph Objectとして扱われる文脈もあるため、必要に応じて「Open Graph objectに関連するメッセージ」を取得するエンドポイントが役立つ場合があります（ただし、どの情報が返るかはメッセージの状態や投稿形式に依存します）。

分析基盤を作るときの実践ポイント

日次エクスポート＋差分取り込みで安定運用する

Viva Engageの投稿は日々増え続けるため、「半年分を一気に出す」運用は失敗しやすくなります。Network Data Export APIのドキュメントでも、信頼性の観点から日次エクスポートが推奨されています。

設計ポイント	おすすめ	理由
取得頻度	日次（前日分＋α）	失敗時のリカバリが簡単／処理時間が読める
期間指定	since / until を1日〜数日単位	ZIPの肥大化を抑える
再実行	同じ期間を上書き取り込みできる設計	遅延反映や一時エラーに強い

編集・削除をどう扱うか：MessageVersions.csvを活用する

投稿は後から編集されることがあります。Network Data Exportでは、Messages.csvに最新（期間内の最新バージョン）が出て、編集履歴はMessageVersions.csvに出る、という整理がされています。分析で「投稿当時の文章」を追うのか、「最新の文章」で集計するのかを、レポート要件に合わせて決めておくと迷いが減ります。

「受け手推定」は“監査レベル”と“改善レベル”を分ける

Praiseの受け手推定（@メンション解析など）は、どうしても誤判定の余地が残ります。そのため、例えば次のようにレポートを二層に分けると、炎上しにくい運用になります。

改善レベル（OKR/施策のための分析）：推定受け手を使い、傾向を見る（個人評価に直結させない）
監査レベル（人事評価/表彰の根拠）：推定を使わず、送信者数やコミュニティ別など確実な指標だけに限定する

「推定して良い範囲」を先に合意しておくと、後からデータの解釈で揉めにくくなります。

よくある質問

Praiseカード（attachments）を解析すれば受け手が取れませんか？

現行のエクスポート仕様として、attachmentsにはOGO情報（id / url / title / description など）が含まれる旨は示されていますが、それだけで「受け手ユーザーID」を常に取り出せる形ではありません。公式にも「受け手を返すAPIはない」という立て付けなので、attachments解析だけでの完全解決は期待しない方が安全です。

共有側メッセージだけから、共有元Praiseの本文を復元できますか？

共有側の本文に共有元の中身が埋め込まれているわけではないため、共有側だけを見て復元するのは難しいです。shared_message_idで共有元メッセージを特定し、元レコードを別途取りに行く二段階が必要になります。

Data ExportとCore API、どちらを正とすべきですか？

全体集計や長期保存が目的ならData Exportを正（母集団）にし、アプリ表示やピンポイント補完が必要な箇所のみCore APIを併用するのが定石です。Core APIは大量エクスポート向けではない、と公式に整理されています。

Viva EngageのPraiseは、コミュニケーション文化の“体温”が見えるデータです。仕様上できないことを無理にねじ曲げるより、取れるデータで価値が出る指標に設計し、必要なら運用で情報を足す。この二段構えにすると、分析もレポートも継続しやすくなります。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。