Uso de api de búsqueda en el modelo de complemento de SharePoint

  • Artículo

El enfoque que se usa para ejecutar búsquedas con el servicio de búsqueda de SharePoint es diferente en el nuevo modelo de complemento de SharePoint que con código de plena confianza. En un escenario típico de solución de granja o código de plena confianza (FTC), el modelo de objetos del lado servidor de SharePoint (invalidaciones del elemento web Content By Query) o los servicios web de búsqueda se usaron para ejecutar búsquedas con el servicio de búsqueda de SharePoint.

En un escenario de modelo de complemento de SharePoint, se ejecutan búsquedas con el servicio de búsqueda de SharePoint a través de las API de REST o CSOM.

Directrices avanzadas

Como regla general, nos gustaría proporcionar las siguientes directrices de alto nivel para crear y configurar colecciones de sitios y subsitios y, a continuación, implementar artefactos, configuraciones y recursos de personalización de marca en ellos.

  • El uso de la autenticación de AppOnly no se admite para ninguna operación del servicio de búsqueda.
    • Esto se debe al hecho de que el servicio de búsqueda accede al servicio de perfil de usuario para buscar información de perfil de usuario y ups no admite la autenticación de AppOnly.
    • Por lo tanto, dado que la relevancia de la búsqueda y otras facetas de búsqueda dependen de un usuario determinado y sus atributos de perfil, el patrón de autenticación AppOnly no funcionará.

Opciones para ejecutar búsquedas con el servicio de búsqueda de SharePoint

Tiene un coupe de opciones para ejecutar búsquedas con el servicio de búsqueda de SharePoint.

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

API de CSOM de .NET

En esta opción se usa la API de CSOM de .Net para ejecutar búsquedas con el servicio de búsqueda de SharePoint.

  • Esta API solo está disponible en código .Net administrado.

¿Cuándo es una buena opción?

  • Esta API es una excelente opción para complementos hospedados por el proveedor, operaciones de larga duración u otros escenarios del lado servidor que se ejecutan en la plataforma .Net.
  • Algunos ejemplos de estos escenarios son ASP.NET sitios web de MVC, servicios de ASP.NET Web API, aplicaciones de Windows o consola de .Net y trabajos web de Azure.

Introducción

En el ejemplo siguiente se muestra cómo ejecutar búsquedas con el servicio de búsqueda de SharePoint con la API de CSOM de .Net. En este ejemplo también se muestra cómo acceder al perfil de un usuario para personalizar los resultados de la búsqueda.

La página Search API and personalization (Api de búsqueda y personalización). Texto en la imagen: realice la búsqueda de Search API. Proporcionar filtro de búsqueda para la consulta de búsqueda de todo el inquilino: el cuadro de texto contiene la palabra, Prueba. Texto del botón: Realizar búsqueda simple. Realice una búsqueda personalizada de todas las plantillas de sitio mediante datos de perfil. Si Acerca de mí NO contiene texto AppTest, solo buscaremos sitios que sean sitios de equipo (WebTemplate = STS). Si AppTest está presente, buscaremos en todos los sitios. Escenario: mostrar sitios o datos agregados de ubicaciones específicas basadas en el perfil de usuario. Por ejemplo, agregar páginas de noticias que solo se etiquetan con un identificador que coincida con la ubicación del usuario actual o la ciudad. Texto del botón: Realizar búsqueda personalizada.

El tutorial How to perform personalized search queries with CSOM (O365 PnP Video) (Cómo realizar consultas de búsqueda personalizadas con CSOM (vídeo PnP de O365) le guiará por el ejemplo Search.PersonalizedResults (ejemplo PnP de O365).

El método btnPerformSearch_Click de la clase Default.aspx.cs ejecuta una búsqueda del valor de texto que el usuario escribe en el cuadro de búsqueda y limita la búsqueda a todo el contenido almacenado en una colección de sitios. El parámetro contentclass:"STS_Site" limita el ámbito de búsqueda a las colecciones de sitios.

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

El método btnPersonalizedSearch_Click de la clase Default.aspx.cs ejecuta la misma búsqueda que el método btnPerformSearch_Click y también agrega un parámetro adicional basado en el perfil del usuario actual. La clase PeopleManager se usa para acceder a las propiedades de perfil del usuario actual.

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

El método ResolveAdditionalFilter de la clase Default.aspx.cs evalúa las propiedades de perfil del usuario actual y devuelve un parámetro de búsqueda aplicable. En este ejemplo, si la propiedad de perfil de usuario aboutMeValue contiene AppTest, se devuelve el parámetro de búsqueda WebTemplate=STS. Este parámetro limita el ámbito de búsqueda a los sitios creados con la plantilla STS (Sitio de equipo).

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

    return "";
}

En ambos casos, el método ProcessQuery de la clase Default.aspx.cs usa la clase SearchExecutor para ejecutar la consulta de búsqueda y devolver los 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

En esta opción se usa la API de CSOM de JavaScript (JSOM) para ejecutar búsquedas con el servicio de búsqueda de SharePoint.

  • Esta API solo está disponible en código JavaScript del lado cliente.

¿Cuándo es una buena opción?

  • Esta API es una excelente opción para complementos hospedados en SharePoint y complementos hospedados por el proveedor que se ejecutan en cualquier plataforma web.
  • Algunos ejemplos de estos escenarios son ASP.NET sitios web de MVC, sitios web php, sitios web de Python, etc.

Introducción

En el ejemplo de código siguiente se muestra cómo ejecutar búsquedas con el servicio de búsqueda de SharePoint con la API de CSOM (JSOM) de JavaScript. En este ejemplo se ejecuta una búsqueda de todos los elementos que contienen el término "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 de REST

En esta opción, usará la API REST para ejecutar búsquedas con el servicio de búsqueda de SharePoint.

  • Esta API es la más flexible porque está disponible tanto en el lado servidor como en el código del lado cliente.
  • El punto de conexión raíz de la API rest de SharePoint Search Service es:
    • <https:// tenant>/site/_api/search/query
  • Estos son algunos ejemplos sencillos:

    • Búsqueda de palabras clave

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

    • Selección de propiedades específicas

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

    • Ordenación

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

¿Cuándo es una buena opción?

Esta API es una excelente opción para complementos hospedados en SharePoint y complementos hospedados por el proveedor que se ejecutan en cualquier plataforma web.

  • Algunos ejemplos de estos escenarios son ASP.NET sitios web de MVC, sitios web de PHP, sitios web de Python, servicios de ASP.NET Web API, aplicaciones de windows o consola de .Net, trabajos web de Azure, etc.

Introducción

Opción del lado servidor

En el ejemplo siguiente se muestra cómo ejecutar búsquedas con el servicio de búsqueda de SharePoint con la API REST desde código .Net administrado.

  • EmployeeDirectory (Contenido de entrenamiento de OfficeDev)

    El método Index de la clase HomeController.cs ejecuta una búsqueda de todos los usuarios cuyo apellido comienza con el valor de texto en el que hace clic el usuario.

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

El tutorial How to build SharePoint add-ins that leverage search (O365 PnP Video) le guiará por EmployeeDirectory (Contenido de entrenamiento de OfficeDev).

Opción del lado cliente

En el ejemplo de código siguiente se muestra cómo ejecutar búsquedas con el servicio de búsqueda de SharePoint con la API REST desde JavaScript. En este ejemplo se ejecuta una búsqueda de todos los elementos que contienen el término "Lacrosse".

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

Ejemplos de PnP

Se aplica a

  • Office 365 multiempresa (MT)
  • Office 365 dedicado (D)
  • SharePoint 2013 local