Microsoft Search API を使用してユーザーを検索する

[アーティクル]
10/07/2023

Microsoft Graph アプリケーションでは、Microsoft Search API を使用して、ユーザーに最も関連性の高いユーザーを取得できます。関連性は、ユーザーのコミュニケーションとコラボレーションパターン、およびビジネスのリレーションシップによって決定されます。 Peopleは、ローカルの連絡先、organizationのディレクトリ、または最近の通信からのユーザーにすることができます。

この分析情報の生成に加えて、検索ではあいまい一致検索のサポートと、サインインしているユーザーのorganization内の別のユーザーに関連するユーザーの一覧を取得する機能も提供されます。

PEOPLE API

次の API を使用して、organization内のユーザーを検索できます。

/検索
/人々

注:

ユーザーがエンドポイントではなく/peopleエンドポイントを/search呼び出すようにお勧めします。今後、将来のすべての投資はエンドポイント/peopleでのみ使用できます/search。エンドポイントはメンテナンスモードです。

返された people プロパティ

people API は、次の一連のプロパティを返します。

プロパティ	型
additionalOfficeLocation	String
CompanyName	String
department	String
displayName	String
emailAddress	String
givenName	String
hitId	String
imAddress	String
jobTitle	String
officeLocation	String
personType	String
phones	String
rank	整数
概要	String
surname	String
userPrincipalName	String

ユーザーの種類

次の表は、people API でサポートされているユーザーの種類とサブタイプを示しています。

サポートされているユーザー、グループ、部屋のバリエーション	受信者の種類の詳細	Mailbox	ディレクトリ	People型	People サブタイプ	Notes
組織ユーザー	UserMailbox、MailUser	Y	Y	人物	OrganizationUser	organizationに属するユーザー。
メールアドレスのない組織ユーザー	User	Y (既定ではオフ)	Y (既定ではオフ)	人物	OrganizationUser	organizationに属するユーザー。
組織の連絡先	MailContact、Contact	N	Y	人物	OrganizationContact	テナント管理者によってグローバルアドレス一覧 (GAL) に明示的に追加された連絡先が、organizationの一部ではありません。
プライベート連絡先	Contact	Y	該当なし	人物	PersonalContact	organizationに属していないユーザーによって明示的に作成された連絡先。ユーザーが連絡先にorganizationの一部を手動で追加した場合、その連絡先は引き続きとして`OrganizationUser`分類されます。
電子メールアドレスのないプライベート連絡先	Contact	Y (既定ではオフ)	該当なし	人物	PersonalContact	organizationに属していないユーザーによって明示的に作成された連絡先。ユーザーが連絡先にorganizationの一部を手動で追加した場合、その連絡先は引き続きとして`OrganizationUser`分類されます。
通信履歴からの暗黙的な連絡先	Contact	Y	該当なし	人物	ImplicitContact	コミュニケーション履歴 (電子メールとチャット) から推測される連絡先。その連絡先が人、グループなどであるかどうかを判断するための十分な情報がありません。ビジネスアカウントでは、これは常に外部organization連絡先になります。通信履歴で見つかったorganization連絡先は常にとして`OrganizationUser`分類されます。コンシューマーアカウントの場合、ではない `PersonalContact` ものはとして `ImplicitContact`分類されます。
チャット履歴からの暗黙的な連絡先	Contact	Y	該当なし	人物	ChatImplicitContact	と `ImplicitContact`同じですが、通信履歴がチャットからのみである場合。
Room	Rooms	Y	Y	その他	Room
Guest	GuestUser	Y	Y	その他	Guest
非表示のゲスト	GuestUser	Y (既定ではオフ)	Y (既定ではオフ)	その他	Guest
モダングループ	グループ	Y	Y	グループ	UnifiedGroup	"Exchange 365 グループ、モダングループ、Microsoft 365 グループ" と呼ばれるグループ。 Microsoft 365 グループについての詳細については、「Microsoft 365 グループの詳細」を参照してください。
Teams グループ	グループ	Y	Y	グループ	UnifiedGroup	Microsoft 365 グループと同じですが、Microsoft Teams の内部的なチームを表します。
非表示の Teams グループ	グループ	Y (既定ではオフ)	Y	グループ	UnifiedGroup	非表示の Teams グループ。
配布リスト	グループ	Y	Y	グループ	PublicDistributionList	従来の Exchange 配布リストまたはメールが有効なセキュリティグループ。
個人用配布リスト	Contact	Y (既定ではオフ)	該当なし	グループ	PersonalDistributionList	簡単な方法で複数の連絡先にメールを送信するためのヘルパーとしてユーザーによって作成された仮想配布グループ。作成Outlook on the web UX 機能としてのみ使用され、他の呼び出し元には返されません。
Guest および Teams グループを除く任意の型の非表示オブジェクト		N	N

リクエストの詳細

要求を行うときに詳細を指定して、people API の結果をより具体的にします。要求をより具体的にする方法を次に示します。

例 1: メールボックスの結果のみ

"Provenances": ["Mailbox"]

例 2: 両方のソースからの結果

"Provenances": ["Mailbox", "Directory"]

結果のソース

People結果は、メールボックスまたはディレクトリの 2 つのソースから取得されます。既定では、結果は両方のソースから取得され、競合が削除されるため、同じ値が返されなくなります。

注: 競合が発生した場合は、ディレクトリソースを使用することをお勧めします。

メールボックスの結果は、次で構成されます。

電子メールを送信したユーザーをPeopleする
電子メールを送信したユーザーをPeopleする
会議を行ったPeople
Teams とチャットしたPeople
マネージャーの組織図のPeople
上記の人の一般の連絡先

ディレクトリソースがMicrosoft Entra IDのグローバルアドレス一覧で検索する場合のユースケースに関連する側面:

コンシューマーユーザーには適用されません
呼び出し元のグローバルアドレス一覧に含まれていないPeopleは返されません
IBP (情報バリアプロトコル) によって非表示になっているPeopleは返されません
アドレス一覧に非表示になっているPeopleは返されません

その他の結果を取得する

より多くの結果を得るには、サイズを指定します。既定では、検索クエリの一致に基づいて 25 件以下の結果が返されます。

"Size": 25

ページングの最小インデックスを指定する

ページングの最小インデックスを設定して、結果の初期ページを指定します。既定では、ページングの最小インデックスはであり 0 、最初の結果が最も関連性が高くなります。

"From": 0

返されるフィールドの選択

API は一連の既定のプロパティを返しますが、特定の数のプロパティを返すように要求をカスタマイズできます。次の例では、 DisplayName、 EmailAddresses、 および phone プロパティへの応答を制限します。

"Fields": ["DisplayName", "EmailAddresses", "phones"]

フィルターを使用した応答の制限

Filter オブジェクトを使用して、応答を特定の値に制限します。使用可能なフィルター値は、 PeopleType、 PeopleSubType です。

次の例では、 Filter オブジェクトを使用して、指定した条件を含むレコードのユーザーを返す要求を示します。

例 1: ユーザーの提案にフィルターを適用する

次の例では、応答を人の提案のみに制限します。応答には、プライベート連絡先とorganization連絡先の両方が含まれます。

"Filter": {
  "And": [
    {
      "Term": {
        "PeopleType": "Person"
      }
    }
  ]
},

例 2: organization内のユーザー候補にフィルター処理する

次の例では、応答をビジネスユーザーのみに制限します。

"Filter": {
  "And": [
    {
      "Term": {
        "PeopleType": "Person"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    }
  ]
},

例 3: organizationのすべてのユーザー、配布リスト、または最新の配布リストにフィルター処理する

次の例では、応答を PeopleSubtype のさまざまなカテゴリに制限します。

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "PublicDistributionList"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "UnifiedGroup"
      }
    }
  ]
},

例 4: ユーザーと会議室をorganizationするようにフィルター処理する

次の例では、応答をユーザーと会議室organization制限します。

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "Rooms"
      }
    }
  ]
},

例 5: ユーザーとゲストをorganizationするようにフィルター処理する

次の例では、応答をユーザーとゲストorganization制限します。

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "Guest"
      }
    }
  ]
},

例 6: 複数のフィルターを結合する

次の例では、複数のフィルターを組み合わせて、応答を指定された条件に制限します。

"Filter": {
  "And": [
    {
      "Or": [
        {
          "Term": {
            "PeopleType": "Person"
          }
        },
        {
          "Term": {
            "PeopleType": "Other"
          }
        }
      ]
    },
    {
      "Or": [
        {
          "Term": {
            "PeopleSubtype": "OrganizationUser"
          }
        },
        {
          "Term": {
            "PeopleSubtype": "Guest"
          }
        }
      ]
    }
  ]
},

完全な要求

例: ユーザーを名前でSearchする

次の要求は、コミュニケーションとコラボレーションパターンとビジネス関係に基づいて、サインインしているユーザーに最も関連性の高いユーザーを取得します。

要求

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "person"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 25
    }
  ]
}

応答

検索基準に一致する 1 つのメッセージを含む応答の例を次に示します。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.searchResponse",
    "value": [
        {
            "hitsContainers": [
                {
                    "total": 1,
                    "moreResultsAvailable": false,
                    "hits": [
                        {
                            "hitId": "fc138b85-18ac-48e0-80a4-633ae4b594e0@41f988bf-86f1-53af-91ab-2d7cd034db47",
                            "rank": 1,
                            "summary": "",
                            "resource": {
                                "@odata.type": "#microsoft.graph.person",
                                "displayName": "Example User",
                                "givenName": "User",
                                "surname": "User",
                                "department": "Finance",
                                "officeLocation": "London",
                                "userPrincipalName": "example.user@contoso.com",
                                "emailAddresses": [
                                    {
                                        "address": "example.user@contoso.com",
                                        "rank": 1
                                    }
                                ],
                                "phones": [
                                    {
                                        "type": "business",
                                        "number": "+44 (20) 12345678"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

次の手順

Microsoft Search API を使用してデータをクエリする