Pesquisar o uso da API no modelo de suplemento do SharePoint

A abordagem adotada para executar pesquisas com o Serviço de Pesquisa do SharePoint é diferente no novo modelo de Suplemento do SharePoint do que era com o Código de Confiança Total. Em um cenário típico de FTC (Código de Confiança Total)/Solução de Farm, o modelo de objeto do lado do servidor do SharePoint (substituições de Web Part de Conteúdo por Consulta) ou os Serviços Web de Pesquisa foram usados para executar pesquisas com o Serviço de Pesquisa do SharePoint.

Em um cenário de modelo de suplemento do SharePoint, você executa pesquisas com o Serviço de Pesquisa do SharePoint por meio das APIs CSOM ou REST.

Diretrizes de Alto Nível

Como regra geral, gostaríamos de fornecer as seguintes diretrizes de alto nível para criar e configurar conjuntos de sites e subsites e, em seguida, implantar artefatos, configurações e ativos de marca neles.

• Não há suporte para o uso da autenticação AppOnly em nenhuma operação de Serviço de Pesquisa.
  • Isso se deve ao fato de que o Serviço de Pesquisa acessa o serviço de perfil de usuário para pesquisar informações de perfil de usuário e o UPS não oferece suporte à autenticação AppOnly.
  • Portanto, como a relevância da pesquisa e outras facetas da pesquisa dependem de um determinado usuário e de seus atributos de perfil, o padrão de autenticação AppOnly não funcionará.

Opções para executar pesquisas com o Serviço de Pesquisa do SharePoint

Você tem várias opções para executar pesquisas com o Serviço de Pesquisa do SharePoint.

• API DO .NET CSOM
• JavaScript CSOM (JSOM) API
• API do REST

API DO .NET CSOM

Nessa opção, você usa a API .Net CSOM para executar pesquisas com o Serviço de Pesquisa do SharePoint.

• Essa API só está disponível no código .Net gerenciado.

Quando isso é apropriado?

• Essa API é uma ótima opção para suplementos hospedados pelo provedor, operações de execução prolongada ou outros cenários do lado do servidor executados na plataforma .NET.
• Alguns exemplos desses cenários são sites do ASP.NET MVC, serviços de ASP.NET Web API, console .Net ou aplicativos do Windows e Azure Trabalhos na Web.

Guia de Introdução

O exemplo a seguir demonstra como executar pesquisas com o Serviço de Pesquisa do SharePoint com a API CSOM do .Net. Este exemplo também demonstra como acessar o perfil de um usuário para personalizar os resultados da pesquisa.

• Search.PersonalizedResults (Exemplo de PnP do O365)

O artigo Como realizar consultas de pesquisa personalizadas com o CSOM (Vídeo PnP do O365) orienta você pelo Search.PersonalizedResults (Exemplo PnP do O365).

O método btnPerformSearch_Click na classe Default.aspx.cs executa uma pesquisa pelo valor de texto que o usuário insere na caixa de pesquisa e define o escopo da pesquisa para todo o conteúdo armazenado em um conjunto de sites. O parâmetro contentclass:"STS_Site" limita o escopo da pesquisa aos conjuntos de sites.

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);
    }
}

O método btnPersonalizedSearch_Click na classe Default.aspx.cs executa a mesma pesquisa que o método btnPerformSearch_Click e também adiciona um parâmetro adicional com base no perfil do usuário atual. A classe PeopleManager é usada para acessar as propriedades de perfil do usuário atual.

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);
    }
}

O método ResolveAdditionalFilter na classe Default.aspx.cs avalia as propriedades de perfil do usuário atual e retorna um parâmetro de pesquisa aplicável. Neste exemplo, se a propriedade de perfil de usuário aboutMeValue contiver AppTest, o parâmetro de pesquisa WebTemplate=STS será retornado. Esse parâmetro limita o escopo da pesquisa a sites criados com o modelo STS (Site de Equipe).

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

    return "";
}

Em ambos os casos, o método ProcessQuery na classe Default.aspx.cs usa a classe SearchExecutor para executar a consulta de pesquisa e retornar os resultados.

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

Nessa opção, use a API JavaScript CSOM (JSOM) para executar pesquisas com o Serviço de Pesquisa do SharePoint.

• Essa API só está disponível no código JavaScript do lado do cliente.

Quando isso é apropriado?

• Essa API é uma ótima opção para Suplementos hospedados no SharePoint e Suplementos hospedados pelo Provedor em execução em qualquer plataforma Web.
• Alguns exemplos desses cenários são ASP.NET sites MVC, sites PHP, sites Python etc.

Guia de Introdução

O exemplo de código a seguir demonstra como executar pesquisas com o Serviço de Pesquisa do SharePoint com a API JavaScript CSOM (JSOM). Este exemplo executa uma pesquisa por todos os itens que contêm o termo '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);

API do REST

Nessa opção, você usa a API REST para executar pesquisas com o Serviço de Pesquisa do SharePoint.

• Essa API é a mais flexível porque está disponível em código do lado do servidor e do lado do cliente.
• O ponto de extremidade raiz da API REST do Serviço de Pesquisa do SharePoint é:
  • https://< tenant>/site/_api/search/query
• Aqui estão alguns exemplos simples:

  • Pesquisa por palavra-chave

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

  • Selecionando propriedades específicas

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

  • Classificação

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

Quando isso é apropriado?

Essa API é uma ótima opção para Suplementos hospedados no SharePoint e Suplementos hospedados pelo Provedor em execução em qualquer plataforma Web.

• Alguns exemplos desses cenários são ASP.NET sites MVC, sites PHP, sites Python, serviços ASP.NET Web API, console .Net ou aplicativos Windows, Azure Trabalhos na Web etc.

Guia de Introdução

Opção do lado do servidor

O exemplo a seguir demonstra como executar pesquisas com o Serviço de Pesquisa do SharePoint com a API REST do código .Net gerenciado.

• EmployeeDirectory (conteúdo de treinamento OfficeDev)

  O método Index na classe HomeController.cs executa uma pesquisa para todos os usuários cujo sobrenome começa com o valor de texto em que o usuário clica.

  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();
  

O artigo Como criar suplementos do SharePoint que aproveitam a pesquisa (Vídeo PnP do O365) orienta você pelo EmployeeDirectory (Conteúdo de Treinamento OfficeDev).

Opção do lado do cliente

O exemplo de código a seguir demonstra como executar pesquisas com o Serviço de Pesquisa do SharePoint com a API REST do JavaScript. Este exemplo executa uma pesquisa para todos os itens que contêm o termo 'Lacrosse'.

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

Links relacionados

• Como realizar consultas de pesquisa personalizadas com o CSOM (Vídeo PnP do O365)
• EmployeeDirectory (conteúdo de treinamento OfficeDev)
• Como criar suplementos do SharePoint que aproveitam a pesquisa (Vídeo PnP do O365)
• Artigos de orientação em https://aka.ms/OfficeDevPnPGuidance
• Referências no MSDN em https://aka.ms/OfficeDevPnPMSDN
• Vídeos em https://aka.ms/OfficeDevPnPVideos

Exemplos de PnP

• Search.PersonalizedResults (Exemplo de PnP do O365)
• Exemplos e conteúdo no Microsoft 365 Padrões e Práticas (PnP)

Aplicável a

• Office 365 Multilocatário (MT)
• Office 365 dedicado (D)
• SharePoint 2013 local