編輯

共用方式為

People and workplace intelligence in Microsoft Graph

  • 發行項

The hundreds of millions of users of Microsoft 365 cloud services form part of the core of Microsoft Graph. The users' data is carefully managed, protected, and with proper authorization, made available by Microsoft Graph services to drive productivity and creativity in businesses.

The profile API lets you, as app developers, model and represent people in Microsoft 365 services, and the profile card API lets administrators control the information showing on users' profile cards in the organization.

As ubiquitous the user's data is in Microsoft Graph, data derived from the user's interactions is particularly interesting. It provides intelligent insights that can answer questions such as the following:

  • "Search for People who’s name starts with ‘J’"
  • "Which documents are most interesting to this person?"

You can use the people API and insights API in Microsoft Graph to build smarter apps that can, respectively, access the relevant people and documents for a user.

The people API returns people ordered by relevance to a user, based on that user's contacts, organization directory, and recent communications on email. This is particularly useful for people-picking scenarios.

The insights API uses advanced analytics and machine learning to provide the most relevant files users need throughout their work day. The API powers familiar Microsoft 365 experiences, including Office Delve, SharePoint Home, the Discover view in OneDrive for Business, and Outlook on the web.

People and insights API return relevant people and documents for a user

Why integrate with people data?

The people API returns data of a single entity, person, which includes typical data of an individual in today's business world. What makes this person data especially useful is its relevance with respect to a Microsoft Graph user. Relevance is noted in the results returned which are ordered from most relevant to least relevant. You can use the following Microsoft Graph APIs to search for people inside an organization.

Use the /search endpoint

We encourage developers to use the /search endpoint when building their products; the /people endpoint is in maintenance mode. The following are reasons to consider using the /search endpoint:

  • All future investments in people search will be made available via /search; for example, natural language search like "John the accountant in Nairobi".
  • Attribute search matching on attributes other than name and email is available.
  • Better relevance results from /search give better results due to the use of artificial intelligence, better data models, and sophisticated spell correction.
  • Lower cost of goods when using /search, but specifically lower latency.

Browse people by relevance

You can browse people who are related to the signed-in user or to some other user in the signed-in user's organization, provided you have got the appropriate authorization. You get a collection of person objects that are ordered by relevance. You can further customize the collection of person objects that is returned in the response by specifying the query parameters top, skip, orderby, select, and filter.

Fuzzy searches based on people criteria

The people API lets you search for people relevant to the signed-in user, provided that your app has got permissions by that user. (Read more on people permissions.)

Fuzzy searches return results based on an exact match and also on inferences about the intent of the search. To illustrate this, the following example returns person objects relevant to the signed-in user whose name, or email address, contains a word that starts with 'j'.

GET /me/people/?$search=j

Why integrate with the profile API (preview)?

The profile API represents the next generation in modeling and representing people in Microsoft 365 services. Profile data can be used together with people data to build customized experiences based on Microsoft Graph.

Why configure profile cards in your organization?

Profile cards let users in an organization see information about one another, such as their names and contact information. Administrators can use the profile card API to customize how information about their organization surfaces within Microsoft 365 people experiences.

Why configure pronouns in your organization?

Pronouns serve as substitutes for a person's name in sentences, with gender-neutral versions available in multiple languages, for example in English, "she", "her, "he", "him" and the gender-neutral "they", "them". Accurate pronoun usage shows inclusivity and respect, avoiding assumptions based on names or initial observations of the person. In a hybrid, multicultural work or school environment, the simple act of using the right pronouns can help build trust and improve communication among one another. Administrators can use the pronounsSettings API to configure pronouns settings in your organization.

Why integrate with document-based insights?

Use intelligence to improve collaboration

During a typical work day, users often interact with large amounts of information stored across many documents and collaborate with other users in many different ways. It's important that they can always find what they need, when they need it.

You can use the insights API, which includes the trending, shared, and used APIs, to surface files from across Microsoft 365 based on your users' current context and needs, making users more productive and improving collaboration in your organization. Organizations can customize privacy settings for these document-based insights, and control the availability of these insights in specific Microsoft 365 experiences.

It is easy to render the results from the insights API in your app. Every result comes with a set of common visualization properties, like a preview image URL or preview text.

Make relevant content visible

In Microsoft 365, Delve uses the trending insight to help users discover the documents that are most interesting to them right now. See figure 1.

Programmatically, you can use the trending entity in the insights API to provide your app customers a similar experience. Use the trending entity to connect to documents that are trending around and relevant to the user. Listing trending documents returns those files stored on OneDrive or SharePoint team sites, sorted by relevance with the most important ones first.

Figure 1. Delve in Microsoft 365 showing popular documents for a user

Screenshot of Delve in Microsoft 365 showing popular documents for a user

Allow users to collaborate and get back to work

The new Microsoft 365 people cards tap into the used and shared insights to connect the dots between people and units of knowledge. The people card identifies and displays relevant documents about a person. Users can see people cards across the suite, for example, in Outlook on the web. See figure 2.

The insights API provides a similar functionality with the used and shared entities. They return what a user has been viewing or working on most recently, or what colleagues have shared with the user most recently in Microsoft 365.

Figure 2. Outlook on the web showing a people card for a user

Screenshot of a people card for a user in Outlook on the web, showing recent files

Why integrate with Microsoft Viva Insights (preview)?

Microsoft Viva Insights provides insight into how people spend their time and who they spend it with. This data can help people plan their day, gain insights into their different work patterns, and help them balance work and life.

The analytics API enables you to synchronize or integrate user analytics data with a custom, third-party app to support a wide range of scenarios that can help improve user productivity and collaboration. For example, you could integrate Viva Insights data with mobile device activities to help users keep track of all their work and social activities and plan their day all within one app.

API reference

Looking for the API reference for these services?

Next steps