Microsoft 365 Community Community Demos, 18 Oct 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Introduction to Microsoft Graph Search API

Description

In this 19-minute developer focused demo – Njeri Grievous delivers an overview, including anatomy of the search request and response syntax, along with an update on latest capabilities for Graph search APIs. Follow along and open Graph Explorer or Graph Postman Collection and go deep on 3 new search queries - Teams Message Search, XRANK, and Answers (type bookmarks and acronyms). Microsoft Graph Search APIs sit on Microsoft Graph and deliver a single search end-point for searching all Microsoft 365 workloads. This PnP Community demo is taken from the weekly Microsoft 365 Platform Community call recorded on October 18, 2022.

Demo Presenter
• Njeri Grievous (Microsoft)

Supporting materials
• Documentation - Overview of the Microsoft Search API in Microsoft Graph | aka.ms/GraphSearchQuery
• Documentation - 2.1.10 XRANK Operator | https://learn.microsoft.com/en-us/openspecs/sharepoint_protocols/ms-kql/36b3c22e-2f24-4096-99df-919f40d16864
• Documentation - Use the Microsoft Search API to search Teams messages | https://learn.microsoft.com/graph/search-concept-chat-messages
• Documentation – Use the Microsoft Search API to xrank search results | https://learn.microsoft.com/graph/search-concept-xrank
• Documentation – bookmark resource type | https://learn.microsoft.com/graph/api/resources/search-bookmark?view=graph-rest-beta
• Documentation - acronym resource type | https://learn.microsoft.com/graph/api/resources/search-acronym?view=graph-rest-beta
• Tool – Graph Explorer | https://developer.microsoft.com/graph/graph-explorer
• Documentation – Use Postman with the Microsoft Graph API | https://learn.microsoft.com/graph/use-postman

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

A

Foreign hi everyone, today's call will be an introduction to the Microsoft search API, but a focus on what's new in the search. Api um I'm really excited to come to you today. My name is and Jerry grievius I am a senior product manager working on Microsoft, search, apis and programmability. If you are familiar with search apis in general, no worries if you are not familiar, it's okay, we're going to cover a lot of introductory and contextual material, and just to give you a lay of the land. My team really does think about supporting.

A

um You know: back-end, search experiences that power Outlook team, SharePoint and other M365 client experiences. However, if you don't want to leverage some of these experiences out of the box and you're looking for more customized flexibility via apis, that's where the Microsoft search API comes into play and where we try to bring some of the same one-piece search experiences to your fingertips and 3p. So um you know we particularly are during this presentation towards developers, so you can learn how to support different applications and experiences, and so that's what I'll be covering today.

A

I've included my contact information here and I'll kind of go over all this information at the end. Just so, you know where to find more resources, so as for an agenda, I want to kick off with you know. What is the search API? How does it work? I then want to go into what's new, so some of the features that we recently released and that's where I'll walk into really a deep dive into the API structure and a feature demo and then we'll close out with some resources that you can take with you.

A

So that way you can explore more and we're always available if you want to reach out and kind of grab time with us. So that way you can learn a little bit more alright. So let's go ahead and get started so the big question: what is the Microsoft search, API um I, feel like before we even really dive into the search API itself, I think it's helpful to Anchor ourselves on the search mission, so pretty much Microsoft search connects you to the knowledge and expertise across your organization and Beyond to help you be more productive.

A

Take action and save time. We know that this is important because we spend so much of our working days just searching for important information, and that being said, there are actually many different options that you have today at Microsoft in order to leverage search for your scenario, those particularly if you want to leverage search apis for building custom use cases, so I wanted to kind of give you a lay of the land in terms of what maybe some of the search apis you might be familiar with today.

A

So we can make this a little bit interactive but feel free to use the raise hand or the reaction features and teams to kind of show if you recognize any of the apis that I am showing here on my screen. These are different types of search apis that you might be familiar with today, and so really the kind of question that we come to is why another search API API, and why this Microsoft search API.

A

So what really differentiates the search API from some of the apis I just showed you is that it is a single search endpoint that allows you to search across all M365 workloads, and so you can see in the little diagram here. There are all these different workloads, clients and experiences that you have access to in M365, and this endpoint is designed to be a centralized place for you to access data across as many of those campuses as possible.

A

We also are working on exposing Microsoft search intelligence and that's a really important part of what differentiates this API as well, so I see having this little green box here. What the endpoint looks like and we'll kind of dive into how to understand this endpoint and what the API structure is a little bit later, um but before we go into that, I did want to kind of talk a little bit about. How does this search API work?

A

So this Microsoft search API sits on Microsoft graph and if you are unfamiliar with the graph today, um pretty much uh you know the graph allows you to access a lot of different intelligence and data.

A

um So these are intelligence across different m3c5 experiences and clients, as well as data sources that can either come from your first party experiences, either exchange or um kind of OneDrive or SharePoint resources, as well as any connected content that you bring in um via you know, uh Microsoft graph connectors. So with that being said, the search API itself, it sits on Microsoft graph and pretty much. The graph Universe contains the search index that is populated with all that data from M365 and the search API allows you to Plum.

A

You know make sure that it's supporting your application using all of the information that's available in the graph, so I'll walk you through some of the experiences that we have enabled recently in the search API that can help power. Your application, your use case, your experience, variance. So that way, it's a customized search capability.

A

So a couple things to note before I talk a little bit more about some of the new features that we have available are the fact that the search API it really is workload agnostic um and so we'll walk through some of the different workloads that you have access to using the search API and, as you can see here, it is compatible with connectors, which is really great, because it sits on Microsoft graph and exposes the intelligence that it's a bit that's available in a lot of these M365 client experiences.

A

So this is kind of something that is really really powerful. Given that you can use this API to make sure that you have really well-rounded experiences and are able to Leverage The Power of graft and we'll go through how this API is scoped by entity and produces and returns graph entities itself and make sure that you have graph consistency through authorization and Authentication.

A

So what's really new in this Microsoft search API that we're going to talk about today? Well, as I mentioned, it is workload agnostic and we're working on growing the API to support more workloads as well as more capabilities. So here I have a list of some of the different workloads that we support right now. um So, for example, you I have access to um Outlook.

A

There are the messages entity, type and Outlook the events in calendar external items and connected content through connectors, as well as your classic OneDrive in SharePoint entity types, which are your file types that I've listed here. But what I'll be walking you through today are some of the new features that we've recently enabled allowing you to search teams content.

A

So this is specifically one-on-one chat, messages and channel messages and we'll talk a little bit more about what that looks like soon, and then we also have new capabilities that allow you to search through certain answers, types and we're excited to show you what that looks like.

A

So, as we can see, we are really thinking about um growing this API to support as much as it can, and we definitely look forward to showing you what that power really looks like, um and so the features that we are going to show you we've recently shipped, and so these features include the ability to search teams messages. We also have shift and ability to use powerful, ranking to be able to rank your search results and then also we support certain answers. Types and all this documentation is live.

A

What I've noted here in yellow is that there are some capabilities that we're exposing in this search API that are really unique to this API and that's what differentiates it so now that we have a little bit of context on what's new I do want to walk through how the API is structured. So that way, you have an understanding if you are not already familiar with the search, API and kind of what the lay of the land is.

A

So for the most basic search, query requests you do need to provide an entity type, which is why I listed all those different entity types along with their corresponding workloads, so pretty much what you need in a request. The search, API endpoint is the entity type, a query string and any additional information like fields that you might want to get back in response Etc, and so this is kind of the syntax and the structure of how this works.

A

You can see that there's an entity type, that's specified here and there's also a query string, that's specified and then I'll show you examples of how you can leverage fields too. So that is what goes into a request and then now for response.

A

So once you kind of take that request and submit it, what are some of the things that you can expect to get back in a response where you're going to get your classic Search terms which are broken down and we'll take the query: string break it down to two Search terms: you're going to get hit, containers which will turn mostly a single hit container, which will um uh which is a container of results, and these results are the hits, um and so in this hit container, you can see that a part of that talks to you about and sorry just gives back to you, the total and also uh some more information on the results and what results beyond what you might see in a response are also available for you to search through and so as part of the hit container.

A

There's several different hits that you get as I mentioned, and so in each hit. There are unique aspects such as the hit ID, the rank. That tells you the the actual score of the search result. It represents the position in the set um and then a summary which is a fragment of text before and after the search term, and then uh the resource itself, which can contain a lot of different information and contains the graph entity that we can kind of specify based on how we structure our search request body.

A

So now that we have an understanding about the basic anatomy and syntax of a request and response, I do invite you to you know code alongside me if you'd like to and open up graph, Explorer or Postman in to kind of walk through some of the new features. No obligation to do this, but I did want to flash here that in graph Explorer, you can see the exact samples of what I'm demoing today. So that way you can go ahead and check them out yourself.

A

We also have a postman collection that we continuously work to keep up to date. So that way, you can go ahead and try and Postman as well. This search, API endpoint is available in beta in B1 and the Futures that I'm going to be showing you today are available in beta. So let's go ahead and Dive Right In I'm, going to walk you through just conceptually some of the just a few features first and then we're going to go over to graph Explorer. So I can walk you through what this means.

A

So here we're going to go through feature by feature and use very simplified examples, and so, uh if you need to go back to any of these examples, graph Explorer does have links to the documentation and I'll also give you resources at the end, so you can walk through it as well. So the first feature that I've mentioned is teams message search. This allows search of one-on-one chat messages as well as Channel messages and also supports um basic kql, and so I will show you briefly in graph Explorer.

A

What this looks like in a second and then after that we'll also look through. um You know what this uh also here is a little demo actually. So that way, you can see basically what it looks like and we'll kind of see what that looks like in graph Explorer and then there's another feature, X rank which will allows for powerful, boosting of the dynamic rank of items without changing the terms in that query, and there's a bunch of different information about this, that you can look up and we'll walk through an example of this live.

A

So let me transition out of the deck into graph Explorer. So we can dive into these examples together. So pretty much.

A

What I'm going to walk through you today is in graph Explorer, if you're not already familiar with it, shows you a bunch of different sample queries and we're going to scroll down to search, because this is a search, API endpoint and we're going to go ahead and click here for um beta now I'm going to go ahead and provide my, you know: desired query string as we know, based on what we looked at in the structure of an API request body and we're going to go ahead and submit this, and so we are able to search one-on-one chat messages and channel messages.

A

So what you get back in the response is what you'd expect um and each hit the resource actually contains information about who sent that message. um Any information about the channel ID, the team ID um and the chat ID. So that way, um it's easily easily retrievable, based on what you're able to kind of get in this response result, and so this is also kind of compatible with kql.

A

So if I wanted to see results that correspond to being delivered from a certain sender, I can also see that there are certain senders that might give me certain Channel and chat messages and I can see that in the response body here. Additionally, we have another feature which you could see a sample for here, which is X rank in this particular example.

A

We're going to understand how the X-Wing feature works, it can get pretty complicated, there's a whole bunch of documentation that exists on how the x-rank operator actually works and all the different parameters that you're going to need. But for the purposes of this example, we're actually going to look at pretty much what a basic X rank structure might look like and we're going to use one of the parameters which is called constant boost, which allows you to boost certain information that is relevant.

A

So here I just want to kind of show you a lay of the land, if I, only search for I I'm, a big fan of cats and dogs. So you're going to see a lot of animal related examples here and you'll notice that, as I run, this query I included Fields here, and this is what I was mentioning earlier- that in your request body, you can include certain fields that you want to get back. So I get my cat related documents, which is great because I love, cats and I can see.

A

I get my title and my author here and this is without X rank, but what if I, was to go ahead and include x rank here by default? This constant boost factor is set to zero and so anything I put after X rank to boost certain strings. It's not going to have an effect because we have set that default, so I'm going to get the same order of my different cat documents here.

A

However, if I set this boost to an integer above zero I'm able to see that certain results might be boosted more than others, because I have specified that so give it a second to run. As we know, demos can be interesting. Okay, great so I was able to boost the information. So I can get another document, that's related to just general information. Instead of all my cat results at first. So this is just a very simplified example of what you can expect with the X rank feature.

A

There's extensive documentation available on how this works in depth, as well as more complex examples. So moving on I do want to return to our slide. We have more features that are related to answers that we've rolled out as well. So, as you know, in the admin portal, you can configure your answers, and today we allow search of answer types that are bookmarks and acronyms.

A

So I want to walk you through the syntax of this. So that way you understand so, as we know, bookmarks can help, pin certain results and allow you to pretty much find important sites and tools, and so, in this request, body you're able to use the entity type bookmark and then specify your query string.

A

So I have a sample query string here and in the response you're going to get a bunch of information, but the key things that you're going to get back is the display name of the bookmark, the description of the bookmark, a URL that points to the bookmark, as well as a set of user-friendly categories that can be configured in the admin portal and so I'll walk through what this looks like in a second and then additionally, we allow you to search, acronyms and acronyms.

A

Can our abbreviations- um and we have a bunch of different ways that you can actually specify your query string how to actually get back the definition of an acronym so to speak. So there are I'll kind of show you some of the really interesting words that you can leverage in order to figure out what uh abbreviation means, and so in the response you're going to get back some similar information, the display name, the description, but you're also going to get back a stands for Value.

A

That shows you what the abbreviation actually stands for as well as the URL. So with that being said, let's go ahead and try. This out together so here in graph Explorer, we're able to see that we can look at the sample for bookmark, which is great amazing. We're going to go, look at what a bookmark looks like, and so some of the same information I showed you in that sample response body is what you're going to get over here as soon as it loads.

A

This is a classic demo experience here, but you can see it's going to return some of the same information that we saw earlier. So we're going to wait for that to come back to us. Okay, perfect, wonderful, just in the nick of time. So we see the display name. We see the description, and so this is really really helpful because you can actually configure certain categories.

A

So maybe I wanted to call this category social which I can configure in the admin portal and then I can go ahead and see that category shown up here if I was to change that separately, there's acronyms and so what's really interesting about acronyms is that you can actually use a bunch of different types of query string terms to help Define.

A

It so I said define MVP the acronym MVP for me, and so it goes aheads and defines it, but I can also say: expand, MVP and I'm able to see the same information here or I could use, MVP stands for or whatever, and so there's actually some documentation that can show you like what keywords you, what not what keywords, but what specific words within the query string you can use here to help make it easier for users to actually go ahead and find information about a particular abbreviation.

A

So those are the features I wanted to demo for you today, I'm going to go back to my slide deck here. So that way we can close out so I wanted to. Thank you all for this opportunity to walk you through a little bit about what the search API does, what it means and what differentiates it from other apis as well. I invite you to go to our short link, AKA dot, Ms, slash graph search, query to be able to try um all of this out.

A

This points you to the documentation as well as where to get started with graph Explorer, as well as our Postman collection, so you can try it out in Postman and feel free to reach out with any questions or, if you'd, like additional information with more complex examples, or you just want to learn more I really appreciate the time today. Thank you all.

B

Awesome, thank you and Jerry, absolutely brilliant stuff and it's super excited on those features and great presentation. It's great great uh work on the presentation as well. So thank you for joining on the on the call.