Set up administrative search answers for users in an organization (preview)
Article
Microsoft Search lets administrators associate search terms with meanings or web pages that are specific to their organizations and include these associations as search answers. For example, users in an organization may run into an unfamiliar acronym that represents an internal project name, or a team name that is associated with a team web page. Administrators can set up acronyms, bookmarks, or QnA in the Microsoft 365 admin center, under Search & intelligence. This enables users to use search to navigate and get familiarized with their work.
Administrators can also use the Microsoft Search API in Microsoft Graph to programmatically manage administrative search answers in the organization. These answers are displayed in Microsoft Search results when triggered by an acronym or keyword defined in the available search answer resource types: acronym, bookmark, and QnA resources.
When triggered by a defined acronym or keyword, these search answers appear at the top of the search results page in your organization.
Example 1: Create a new acronym
The following request creates a new acronym that will display on the search results page when a user searches for it.
POST https://graph.microsoft.com/beta/search/acronyms
Content-Type: application/json
{
"displayName": "GDPR",
"standsFor": "General Data Protection Regulation",
"description": "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",
"webUrl": "http://contoso.com/GDPR",
"state": "published"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models.Search;
var requestBody = new Acronym
{
DisplayName = "GDPR",
StandsFor = "General Data Protection Regulation",
Description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",
WebUrl = "http://contoso.com/GDPR",
State = AnswerState.Published,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Search.Acronyms.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta search acronyms create --body '{\
"displayName": "GDPR",\
"standsFor": "General Data Protection Regulation",\
"description": "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",\
"webUrl": "http://contoso.com/GDPR",\
"state": "published"\
}\
'
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodelssearch "github.com/microsoftgraph/msgraph-beta-sdk-go/models/search"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestBody := graphmodelssearch.NewAcronym()
displayName := "GDPR"
requestBody.SetDisplayName(&displayName)
standsFor := "General Data Protection Regulation"
requestBody.SetStandsFor(&standsFor)
description := "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas."
requestBody.SetDescription(&description)
webUrl := "http://contoso.com/GDPR"
requestBody.SetWebUrl(&webUrl)
state := graphmodels.PUBLISHED_ANSWERSTATE
requestBody.SetState(&state)
acronyms, err := graphClient.Search().Acronyms().Post(context.Background(), requestBody, nil)
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
Acronym acronym = new Acronym();
acronym.displayName = "GDPR";
acronym.standsFor = "General Data Protection Regulation";
acronym.description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.";
acronym.webUrl = "http://contoso.com/GDPR";
acronym.state = AnswerState.PUBLISHED;
graphClient.search().acronyms()
.buildRequest()
.post(acronym);
const options = {
authProvider,
};
const client = Client.init(options);
const acronym = {
displayName: 'GDPR',
standsFor: 'General Data Protection Regulation',
description: 'A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals\' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.',
webUrl: 'http://contoso.com/GDPR',
state: 'published'
};
await client.api('/search/acronyms')
.version('beta')
.post(acronym);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Acronym();
$requestBody->setDisplayName('GDPR');
$requestBody->setStandsFor('General Data Protection Regulation');
$requestBody->setDescription('A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals\' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.');
$requestBody->setWebUrl('http://contoso.com/GDPR');
$requestBody->setState(new AnswerState('published'));
$result = $graphServiceClient->search()->acronyms()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Search
$params = @{
displayName = "GDPR"
standsFor = "General Data Protection Regulation"
description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas."
webUrl = "http://contoso.com/GDPR"
state = "published"
}
New-MgBetaSearchAcronym -BodyParameter $params
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = Acronym(
display_name = "GDPR",
stands_for = "General Data Protection Regulation",
description = "A European Union (EU) regulation on data protection and privacy in the EU and the European Economic Area (EEA) that enhances individuals' control and rights over their personal data, simplifies the regulatory environment for international business, and addresses the transfer of personal data outside the EU and EEA areas.",
web_url = "http://contoso.com/GDPR",
state = AnswerState.Published,
)
result = await graph_client.search.acronyms.post(request_body)
POST https://graph.microsoft.com/beta/search/bookmarks
Content-Type: application/json
{
"displayName": "Contoso Install Site",
"webUrl": "http://www.contoso.com/",
"description": "Try or buy Contoso for Home or Business and view product information",
"keywords": {
"keywords": ["Contoso", "install"],
"reservedKeywords": ["Contoso"],
"matchSimilarKeywords": true
},
"state": "published"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models.Search;
var requestBody = new Bookmark
{
DisplayName = "Contoso Install Site",
WebUrl = "http://www.contoso.com/",
Description = "Try or buy Contoso for Home or Business and view product information",
Keywords = new AnswerKeyword
{
Keywords = new List<string>
{
"Contoso",
"install",
},
ReservedKeywords = new List<string>
{
"Contoso",
},
MatchSimilarKeywords = true,
},
State = AnswerState.Published,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Search.Bookmarks.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta search bookmarks create --body '{\
"displayName": "Contoso Install Site",\
"webUrl": "http://www.contoso.com/",\
"description": "Try or buy Contoso for Home or Business and view product information",\
"keywords": {\
"keywords": ["Contoso", "install"],\
"reservedKeywords": ["Contoso"],\
"matchSimilarKeywords": true\
},\
"state": "published"\
}\
'
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Bookmark();
$requestBody->setDisplayName('Contoso Install Site');
$requestBody->setWebUrl('http://www.contoso.com/');
$requestBody->setDescription('Try or buy Contoso for Home or Business and view product information');
$keywords = new AnswerKeyword();
$keywords->setKeywords(['Contoso', 'install', ]);
$keywords->setReservedKeywords(['Contoso', ]);
$keywords->setMatchSimilarKeywords(true);
$requestBody->setKeywords($keywords);
$requestBody->setState(new AnswerState('published'));
$result = $graphServiceClient->search()->bookmarks()->post($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = Bookmark(
display_name = "Contoso Install Site",
web_url = "http://www.contoso.com/",
description = "Try or buy Contoso for Home or Business and view product information",
keywords = AnswerKeyword(
keywords = [
"Contoso",
"install",
],
reserved_keywords = [
"Contoso",
],
match_similar_keywords = True,
),
state = AnswerState.Published,
)
result = await graph_client.search.bookmarks.post(request_body)