Microsoft Search API を使用してユーザーを検索する
Microsoft Graph アプリケーションでは、Microsoft Search API を使用して、ユーザーに最も関連性の高いユーザーを取得できます。 関連性は、ユーザーのコミュニケーションとコラボレーション パターン、およびビジネスのリレーションシップによって決定されます。 Peopleは、ローカルの連絡先、organizationのディレクトリ、または最近の通信からのユーザーにすることができます。
この分析情報の生成に加えて、検索ではあいまい一致検索のサポートと、サインインしているユーザーのorganization内の別のユーザーに関連するユーザーの一覧を取得する機能も提供されます。
次の API を使用して、organization内のユーザーを検索できます。
- /検索
- /人々
注意
ユーザーがエンドポイントではなく/people
エンドポイントを/search
呼び出すようにお勧めします。 今後、将来のすべての投資はエンドポイント/people
でのみ使用できます/search
。エンドポイントはメンテナンス モードです。
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 の結果をより具体的にします。 要求をより具体的にする方法を次に示します。
"Provenances": ["Mailbox"]
"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 オブジェクトを使用して、指定した条件を含むレコードのユーザーを返す要求を示します。
次の例では、応答を人の提案のみに制限します。 応答には、プライベート連絡先とorganization連絡先の両方が含まれます。
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
}
]
},
次の例では、応答をビジネス ユーザーのみに制限します。
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
}
]
},
次の例では、応答を PeopleSubtype のさまざまなカテゴリに制限します。
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "PublicDistributionList"
}
},
{
"Term": {
"PeopleSubtype": "UnifiedGroup"
}
}
]
},
次の例では、応答をユーザーと会議室organization制限します。
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Rooms"
}
}
]
},
次の例では、応答をユーザーとゲストorganization制限します。
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
},
次の例では、複数のフィルターを組み合わせて、応答を指定された条件に制限します。
"Filter": {
"And": [
{
"Or": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleType": "Other"
}
}
]
},
{
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
}
]
},
次の要求は、コミュニケーションとコラボレーションパターンとビジネス関係に基づいて、サインインしているユーザーに最も関連性の高いユーザーを取得します。
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"
}
]
}
}
]
}
]
}
]
}