MENU

【Microsoft Graph API】Outlook メール REST API 制約・注意事項をまとめ

未分類
  1. ホーム
  2. 未分類
  3. 【Microsoft Graph API】Outlook メール REST API 制約・注意事項をまとめ

Microsoft Graph REST API v1.0 エンドポイント リファレンス
https://learn.microsoft.com/ja-jp/graph/api/overview?view=graph-rest-1.0

リファレンスを参照して動作確認を行ったところ、想定と異なる点がありましたので共有いたします。お手数ですが、最終的なご確認はご自身でもお願いいたします。

目次

Microsoft Graph API クエリ パラメーター

Microsoft Graph API レスポンスに条件を指定する場合に使用します

列フィルター（$select）や行フィルター（$filter）などがあります

クエリ パラメーターを使用して Microsoft Graph 応答をカスタマイズする
https://learn.microsoft.com/ja-jp/graph/query-parameters?view=graph-rest-1.0&tabs=http

スクロールできます
名前説明例
$count一致するリソースの合計数を返します。/me/messages?$top=2&$count=true
$expand関連リソースを返します。/groups?$expand=members
$filter結果 (行) をフィルターします。/users?$filter=startswith(givenName,'J')
$format指定したメディア形式で結果を返します。/users?$format=json
$orderby結果を並べます。/users?$orderby=displayName desc
$search検索条件に基づいて結果を返します。/me/messages?$search=pizza
$selectプロパティ (列) をフィルターします。/users?$select=givenName,surname
$skip結果セット内の項目をスキップします。 また、ページングを実装するために一部の API で使用され、 $top で使用して結果を手動でページできます。/me/messages?$skip=11
$top結果のページ サイズを設定します。/users?$top=2


$search クエリ パラメーター 概要

$filter が「プロパティに対する条件指定」に近いのに対して、$search は「検索語で対象リソースを探す」用途です。

  • クエリ パラメーター
    • $filter — プロパティに対する条件指定
    • $search —検索語で対象リソースを探す

対象として指定できるリソースは以下（リファレンスに記載があります、他のリソースについて未確認）

  • メール メッセージ
  • ユーザー
  • Microsoft Entra ID オブジェクト (ディレクトリ オブジェクト)

検索対象のプロパティ、構文、挙動はリソースごとに違います

Microsoft Graph REST API v1.0 エンドポイント リファレンス/API の使用/クエリ パラメーターの使用/検索を使用する
https://learn.microsoft.com/ja-jp/graph/search-query-parameter?view=graph-rest-1.0&tabs=http

メール メッセージで$searchを使用する場合の仕様

メッセージ コレクションで$searchを使用する
https://learn.microsoft.com/ja-jp/graph/search-query-parameter?view=graph-rest-1.0&tabs=http#use-search-on-message-collections

「$search で検索パラメータにキーワードを入れた場合、どういう条件で結果に含まれるのか」

実際Graph API で動作確認した結果、
前方一致も指定できるようなので合わせて確認してみました

  • 検索キーワード「テスト」でプロパティを「subject」を指定した場合
  • 検索キーワード「*テスト」でプロパティを「subject」を指定した場合
  • 検索キーワード「テスト*」でプロパティを「subject」を指定した場合

結果として前方一致〇〇*の効果が確認できませんでした、また日本語と英語で結果が異なりました

スクロールできます
検索対象件名テスト*テストテスト*
テス❌❌❌
テス ト❌❌❌
テスト⭕️❌⭕️
検索テスト⭕️❌⭕️
テスト検索⭕️❌⭕️
スクロールできます
検索対象件名test*testtest*
tes❌❌❌
tes t❌❌❌
test⭕️❌⭕️
searchtest❌❌❌
search test⭕️❌⭕️
testsearch⭕️❌⭕️

メッセージのうち、既定の 3 つの検索プロパティのいずれかに “pizza” が含まれるメッセージをすべて返します。
https://learn.microsoft.com/ja-jp/graph/search-query-parameter?view=graph-rest-1.0&tabs=http#use-search-on-message-collections

メッセージリソースに対して、プロパティを指定して検索することが可能

検索可能プロパティは次のリファレンスのメッセージリソースと名称が一致しないものや存在しないものもあります

  • プロパティ名称が検索プロパティはbccだけとメッセージリソースではbccRecipientsで異なる
  • participants は検索プロパティには存在するが、メッセージリソースには存在しない

検索可能なプロパティ
https://learn.microsoft.com/ja-jp/graph/search-query-parameter?view=graph-rest-1.0&tabs=http#use-search-on-message-collections

スクロールできます
検索可能な電子メール プロパティ説明例
attachment電子メール メッセージに添付されたファイルの名前。GET../me/messages?$search="attachment:api-catalog.md"
bccSMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの bcc フィールド。GET../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
body電子メール メッセージの本文。GET../me/messages?$search="body:excitement"
ccSMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの cc フィールド。GET../me/messages?$search="cc:danas"&$select=subject,ccRecipients
fromSMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの送信者。GET../me/messages?$search="from:randiw"&$select=subject,from

GET../me/messages?$search="from:adelev OR from:alexw OR from: allanD"&$select=subject, from
hasAttachmenttrue 電子メール メッセージにインライン添付ファイルではない添付ファイルが含まれている場合。それ以外の場合 false 。GET../me/messages?$search="hasAttachments:true"
importance送信者がメッセージを送信するときに指定できる電子メール メッセージの重要性。 使用可能な値は、 low、 medium、または highです。GET../me/messages?$search="importance:high"&$select=subject,importance
kindメッセージの種類。 使用できる値は、 contacts、 docs、 email、 faxes、 im、 journals、 meetings、 notes、 posts、 rssfeeds、 tasks、または voicemailです。GET../me/messages?$search="kind:voicemail"
participantsSMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの from、to、cc、bcc フィールド。GET../me/messages?$search="participants:danas"
received受信者が電子メール メッセージを受信した日付。GET../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipientsSMTP アドレス、表示名、またはエイリアスとして指定された電子メール メッセージの宛先、 cc、 および bcc フィールド。GET../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sent送信者から電子メール メッセージが送信された日付。GET../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
sizeアイテムのサイズ (バイト数)。GET../me/messages?$search="size:1..500000"
subject電子メール メッセージの件名行に含まれるテキスト。GET../me/messages?$search="subject:has"&$select=subject
toSMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの to フィールド。GET.../me/messages?$search="to:randiw"&$select=subject,toRecipients

「プロパティ未指定時のデフォルトは from / subject / body」という公式ドキュメントの記述が、実際の挙動と違う

プロパティを指定しなければ from、 subject、 body がデフォルトで対象になります

https://learn.microsoft.com/ja-jp/graph/search-query-parameter?view=graph-rest-1.0&tabs=http#use-search-on-message-collections

以下のように解釈

  • （A）プロパティ指定なし（デフォルトなので from、 subject、 body が対象）
$search="keyword1 OR keyword2"
  • （B）プロパティ指定あり（participantsは from、to、cc、bcc が対象）
$search="participants:keyword1 OR participants:keyword2"

動作確認結果

上記でccにのみkeywordを含めた場合想定では（B）のみ含まれると考えてましたが、（A）（B）ともに含めれました、デフォルトでもccにキーワードを対象としているような挙動でした

まとめ

スクロールできます
プロパティなし（デフォルト）toccparticipants
リファレンスの内容from、 subject、 body がデフォルトで対象になりますto フィールドcc フィールドfrom、to、cc、bcc フィールド
toにキーワード⭕️
リファレンスに記述なし		⭕️❌⭕️
ccにキーワード⭕️
リファレンスに記述なし		❌⭕️⭕️
件名にキーワード⭕️❌❌❌
本文にキーワード⭕️❌❌❌


$searchでparticipantsを使用する際はメールアドレスとして解釈される文字列は使用しないことでエラーを回避できた

事象
Microsoft Graph API の messages 取得で、$search に participants: を指定した際、
検索値に “.” を含めると 500 エラーになる。（example@test.com）

OK 例
$search=”participants:example“

NG 例
$search=”participants:example@test.com“

実際に送信された検索条件の例
&$search=%22participants%3A**.%22

発生エラー
[HH:MM:SS] ERROR: Graph API エラー status=500
エラー詳細
{
"code": "ErrorInternalServerError",
"message": "An internal server error occurred. The operation failed., Unrecognized filter of type Microsoft.Exchange.Data.OrFilter"
}

補足
“.” を含まない値では問題なく検索できる。
“.” を含む値はドメイン/SMTP系の recipient 検索として解釈され、
participants が内部的に from / to / cc / bcc 相当へ展開される過程で
Exchange 側の OrFilter エラーになっている可能性が高い。

キーワード照会言語 (KeyQL) 構文リファレンス

キーワード照会言語 (KeyQL) 構文リファレンス
https://learn.microsoft.com/ja-jp/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference
– AND OR NOTなど
– 式の間に演算子が指定されていない自由形式の式が複数ある場合、クエリ動作は AND 演算子を使用した場合と同じになります。

注意事項リスト

$searchと$orderbyは併用できない 結果は送信日時順で返るが、明示的なソート指定は不可。 https://learn.microsoft.com/en-us/graph/search-query-parameter
https://learn.microsoft.com/en-us/answers/questions/656200/graph-api-to-filter-results-on-from-and-subject-an

$searchの結果は最大1,000件 https://learn.microsoft.com/en-us/graph/search-query-parameter

$filterと$searchは併用できない https://learn.microsoft.com/en-us/graph/query-parameters

$filterと$orderbyの併用にはプロパティ順序の制約がある $orderbyのプロパティは$filterにも同じ順序で先に含める必要がある。違反すると"The restriction or sort order is too complex for this operation."エラー。 https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0

toRecipients / ccRecipients / bccRecipientsは$filterできない fromは可。to/cc/bccで絞りたい場合は$searchを使うしかない。https://learn.microsoft.com/en-us/answers/questions/1665637/how-to-query-emails-by-recipients-email-address

$filterでドメイン部分一致（endsWith）はメッセージのemailAddressで使えない containsは使えるがNOTとの組み合わせ不可。ドメイン除外は$filterでは実現困難。 https://learn.microsoft.com/en-us/answers/questions/1168280/office-365-mail-graph-api-)-is-there-a-way-to-filt

from/emailAddress/address eqが一部の送信者で正しく動かないケースがある startsWithなら動く場合がある。 https://learn.microsoft.com/en-us/answers/questions/2153305/when-filtering-messages-on-ms-graph-rest-api-using

未分類

関連記事

目次