英語で読む

次の方法で共有


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

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 は一連の既定のプロパティを返しますが、特定の数のプロパティを返すように要求をカスタマイズできます。 次の例では、 DisplayNameEmailAddressesおよび phone プロパティへの応答を制限します。

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

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

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

次の例では、 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"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

次の手順