Partilhar via

Pesquisar o uso da API no modelo de suplemento do SharePoint

  • Artigo

A abordagem que você adota para executar pesquisas com o Serviço de Pesquisa do SharePoint é diferente no novo modelo de suplemento do SharePoint do que com o Código de Confiança Total. Em um cenário típico de FTC (Código de Confiança Total) /Farm Solution, o modelo de objeto do lado do servidor do SharePoint (substituições de web part content by query) 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 diretrizes de alto nível a seguir para criar e configurar coleções de sites e sub-sites e, em seguida, implantar artefatos, configurações e ativos de branding para eles.

  • Não há suporte para o uso da autenticação AppOnly para operações do 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 dá suporte à autenticação AppOnly.
    • Portanto, como a relevância da pesquisa e outras facetas de pesquisa dependem de um determinado usuário e 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 um cupê de opções para executar pesquisas com o Serviço de Pesquisa do SharePoint.

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

API CSOM do .NET

Nesta opção, você usa a API do CSOM do .Net 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 é um ótimo ajuste para suplementos hospedados pelo provedor, operações de execução longa ou outros cenários do lado do servidor que são executados na plataforma .Net.
  • Alguns exemplos desses cenários são ASP.NET sites de MVC, serviços de ASP.NET Web API, console .Net ou aplicativos Windows e Trabalhos Web do Azure.

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.

A página API de Pesquisa e personalização. Texto na imagem: executar pesquisa de API de Pesquisa. Fornecer filtro de pesquisa para consulta de pesquisa em todo o locatário: a caixa de texto contém a palavra, Teste. Texto do botão: Executar Pesquisa Simples. Execute uma pesquisa personalizada de todos os modelos de site usando dados de perfil. Se About me NÃO contiver texto AppTest, pesquisamos apenas sites que são sites de equipe (WebTemplate = STS). Se AppTest estiver presente, pesquisaremos todos os sites. Cenário: mostrar sites ou dados agregados de locais específicos com base no perfil do usuário. O exemplo seria agregar páginas de notícias que são marcadas apenas com o local ou a cidade do usuário atual correspondente ao identificador. Texto do botão: executar pesquisa personalizada.

O Vídeo O365 PnP (Como executar consultas de pesquisa personalizadas com O365 PnP Video) orienta você através do Search.PersonalizedResults (Exemplo de PnP 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 escopos da pesquisa para todo o conteúdo armazenado em uma coleção de sites. O parâmetro contentclass:"STS_Site" limita o escopo de pesquisa às coleções 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 do 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 de pesquisa a sites criados com o modelo STS (Site da 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;
}

API do JSOM (JavaScript CSOM)

Nesta opção, você usa a API JSOM (JavaScript CSOM) 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 é um ótimo ajuste para suplementos hospedados pelo SharePoint e suplementos hospedados pelo provedor em execução em qualquer plataforma Web.
  • Alguns exemplos desses cenários são ASP.NET sites de MVC, sites PHP, sites do Python etc.

Introdução

O exemplo de código a seguir demonstra como executar pesquisas com o Serviço de Pesquisa do SharePoint com a API do JSOM (JavaScript CSOM). Este exemplo executa uma pesquisa para 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 REST

Nesta 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 no código do lado do servidor e do lado do cliente.
  • O ponto de extremidade da API REST do Serviço de Pesquisa do SharePoint é:
    • <https:// tenant>/site/_api/search/query
  • Aqui estão alguns exemplos simples:

    • Pesquisa de 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 é um ótimo ajuste para suplementos hospedados pelo SharePoint e suplementos hospedados pelo provedor em execução em qualquer plataforma Web.

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

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

Os suplementos How to build SharePoint que aproveitam a pesquisa (O365 PnP Video) orienta você pelo EmployeeDirectory (Conteúdo de Treinamento do 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
});

Exemplos de PnP

Aplicável a

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