SharePoint 加载项模型中的搜索 API 用法

项目
04/08/2023

在新 SharePoint 外接程序模型中使用 SharePoint 搜索服务执行搜索的方法与使用完全信任代码不同。在典型的完全信任代码 (FTC) /场解决方案方案中，SharePoint 服务器端对象模型 (内容查询 Web 部件替代) 或搜索 Web 服务用于使用 SharePoint 搜索服务执行搜索。

在 SharePoint 外接程序模型场景中，通过 CSOM 或 REST API 使用 SharePoint 搜索服务执行搜索。

高级别准则

作为经验法则，我们希望提供以下高级别准则，以创建并配置网站集和子网站，然后向其部署项目、配置和品牌资产。

任何搜索服务操作均不支持使用 AppOnly 身份验证。
- 这是由于搜索服务访问 User Profile Service 以搜索用户配置文件信息且 UPS 不支持 AppOnly 身份验证。
- 因此，由于搜索相关性和其他搜索方面取决于给定用户及其配置文件的属性，AppOnly 身份验证模式将不起作用。

使用 SharePoint 搜索服务执行搜索的选项

有多个使用 SharePoint 搜索服务执行搜索的选项

.NET CSOM API
JavaScript CSOM (JSOM) API
REST API

.NET CSOM API

在此选项中，借助 .Net CSOM API 使用 SharePoint 搜索服务来执行搜索。

此 API 仅适用于托管的 .Net 代码。

何时适合？

此 API 非常适用于提供商托管的外接程序、长时间运行的操作或在 .Net 平台上运行的其他服务器端场景。
这些场景的一些示例包括 ASP.NET MVC 网站、ASP.NET Web API 服务、.Net 控制台或 Windows 应用程序以及 Azure Web 作业。

开始使用

以下示例演示如何通过 .Net CSOM API 使用 SharePoint 搜索服务执行搜索。此示例还演示如何访问用户的配置文件来对搜索结果进行个性化设置。

Search.PersonalizedResults（O365 PnP 示例）

如何使用 CSOM 执行个性化的搜索查询（O365 PnP 视频）指导你完成 Search.PersonalizedResults（O365 PnP 示例）。

Default.aspx.cs 类中的 btnPerformSearch_Click 方法对用户在搜索框中输入的文本值执行搜索并将该搜索范围延伸到网站集中存储的所有内容。 Contentclass:"STS_Site" 参数将搜索范围限制为网站集。

protected void btnPerformSearch_Click(object sender, EventArgs e)
{
    var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        // Since in this case we want only site collections, let's filter based on result type
        string query = searchtext.Text + " contentclass:\"STS_Site\"";
        ClientResult<ResultTableCollection> results = ProcessQuery(clientContext, query);
        lblStatus1.Text = FormatResults(results);
    }
}

Default.aspx.cs 类中的 btnPersonalizedSearch_Click 方法执行的搜索与 btnPerformSearch_Click 方法的相同，并基于当前用户的配置文件添加其他的参数。 PeopleManager 类用于访问当前用户配置文件的属性。

protected void btnPersonalizedSearch_Click(object sender, EventArgs e)
{
    var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        // Load user profile properties
        PeopleManager peopleManager = new PeopleManager(clientContext);
        PersonProperties personProperties = peopleManager.GetMyProperties();
        clientContext.Load(personProperties);
        clientContext.ExecuteQuery();
        // Check teh value for About Me to investigate current values
        string aboutMeValue = personProperties.UserProfileProperties["AboutMe"];
        string templateFilter = ResolveAdditionalFilter(aboutMeValue);
        // Let's build the query
        string query = "contentclass:\"STS_Site\" " + templateFilter;
        ClientResult<ResultTableCollection> results = ProcessQuery(clientContext, query);
        lblStatus2.Text = FormatResults(results);
    }
}

Default.aspx.cs 类中的 ResolveAdditionalFilter 方法评估当前用户配置文件的属性并返回适用的搜索参数。在此示例中，如果 aboutMeValue 用户配置文件属性包含 AppTest，则会返回搜索参数 WebTemplate = STS。此参数将搜索范围限制为使用 STS（团队网站）模板构建的网站。

private string ResolveAdditionalFilter(string aboutMeValue)
{
    if (!aboutMeValue.Contains("AppTest"))
    {
        return "WebTemplate=STS";
    }

    return "";
}

在上述两种情况中，Default.aspx.cs 类中的 ProcessQuery 方法使用 SearchExecutor 类来执行搜索查询并返回相应结果。

private ClientResult<ResultTableCollection> ProcessQuery(ClientContext ctx, string keywordQueryValue)
{
    KeywordQuery keywordQuery = new KeywordQuery(ctx);
    keywordQuery.QueryText = keywordQueryValue;
    keywordQuery.RowLimit = 500;
    keywordQuery.StartRow = 0;
    keywordQuery.SelectProperties.Add("Title");
    keywordQuery.SelectProperties.Add("SPSiteUrl");
    keywordQuery.SelectProperties.Add("Description");
    keywordQuery.SelectProperties.Add("WebTemplate");
    keywordQuery.SortList.Add("SPSiteUrl", Microsoft.SharePoint.Client.Search.Query.SortDirection.Ascending);
    SearchExecutor searchExec = new SearchExecutor(ctx);
    ClientResult<ResultTableCollection> results = searchExec.ExecuteQuery(keywordQuery);
    ctx.ExecuteQuery();
    return results;
}

JavaScript CSOM (JSOM) API

在此选项中，借助 JavaScript CSOM (JSOM) API 使用 SharePoint 搜索服务来执行搜索。

此 API 仅适用于客户端 JavaScript 代码。

何时适合？

此 API 非常适用于在任何 Web 平台上运行的 SharePoint 托管的外接程序和提供商托管的外接程序。
这些场景的一些示例包括 ASP.NET MVC 网站、PHP 网站、Python 网站等。

开始使用

以下代码示例演示如何通过 JavaScript CSOM (JSOM) API 使用 SharePoint 搜索服务执行搜索。本示例执行对包含词语“Blizzard”的所有项的搜索。

var context = SP.ClientContext.get_current();

var keywordQuery =
new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(context);

keywordQuery.set_queryText("Blizzard");

var searchExecutor =
new Microsoft.SharePoint.Client.Search.Query.SearchExecutor(context);

results = searchExecutor.executeQuery(keywordQuery);

context.executeQueryAsync(onGetEventsSuccess, onGetEventsFail);

REST API

在此选项中，借助 REST API 使用 SharePoint 搜索服务来执行搜索。

此 API 最为灵活，因为其同时适用于服务器端和客户端代码。
SharePoint 搜索服务 REST API 根终端为：
- <https:// tenant>/site/_api/search/query

以下是一些简单的示例：

关键字搜索

https://tenant/site/_api/search/query?querytext='{Apples}'

选择特定的属性

https://tenant/site/_api/search/query?querytext='test'&selectproperties='Rank, Title'

排序

https://tenant/site/_api/search/query?querytext='Oranges'&sortlist='LastModifiedTime:ascending'

何时适合？

此 API 非常适用于在任何 Web 平台上运行的 SharePoint 托管的外接程序和提供商托管的外接程序。

这些场景中的一些示例包括 ASP.NET MVC Web 网站、PHP Web 网站、Python Web 网站、ASP.NET Web API 服务、.Net 控制台或 Windows 应用程序、Azure Web 作业等。

开始使用

服务器端选项

以下示例演示如何通过托管的 .Net code 的 REST API 使用 SharePoint 搜索服务执行搜索。

EmployeeDirectory（OfficeDev 培训内容）

HomeController.cs 类中的 Index 方法对姓氏以用户单击的文本值开头的所有用户执行搜索。

var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext);

string accessToken = spContext.UserAccessTokenForSPHost;

//Build the REST API request
StringBuilder requestUri = new StringBuilder()
.Append(spContext.SPHostUrl)
.Append("/_api/search/query?querytext='LastName:")
.Append(startLetter)
.Append("*'&selectproperties='LastName,FirstName,WorkEmail,WorkPhone'&sourceid='B09A7990-05EA-4AF9-81EF-EDFAB16C4E31'&sortlist='FirstName:ascending'");

//Create HTTP Client
HttpClient client = new HttpClient();
//Add the REST API request
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, requestUri.ToString());
//Set accept header
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/xml"));
//Set Bearer header equal to access token
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

//Send the REST API request
HttpResponseMessage response = await client.SendAsync(request);
//Set the response
string responseString = await response.Content.ReadAsStringAsync();

如何生成可以使用搜索的 SharePoint 外接程序（O365 PnP 视频）指导你完成 EmployeeDirectory（OfficeDev 培训内容）。

客户端选项

以下代码示例演示如何通过 JavaScript 的 REST API 使用 SharePoint 搜索服务执行搜索。本示例执行对包含词语“Lacrosse”的所有项的搜索。

$.ajax({
    url: "http://site/_api/search/" +
          "query?querytext='{Lacrosse}‘",
    method: "GET",
    headers: {
        "accept": "application/json;odata=verbose",
    },
    success: onSuccess,
    error: onError
});

如何使用 CSOM 执行个性化的搜索查询（O365 PnP 视频）
EmployeeDirectory（OfficeDev 培训内容）
如何构建可以使用搜索的 SharePoint 外接程序（O365 PnP 视频）
指南文章中 https://aka.ms/OfficeDevPnPGuidance
MSDN 中的引用位于 https://aka.ms/OfficeDevPnPMSDN
视频中的 https://aka.ms/OfficeDevPnPVideos

PnP 示例

适用于

Office 365 多租户 (MT)
Office 365 专用 (D)
SharePoint 2013 本地

通过

SharePoint 加载项模型中的搜索 API 用法

高级别准则

使用 SharePoint 搜索服务执行搜索的选项

.NET CSOM API

何时适合？

开始使用

JavaScript CSOM (JSOM) API

何时适合？

开始使用

REST API

何时适合？

开始使用

服务器端选项

客户端选项

相关链接

PnP 示例

适用于

其他资源