Uso de la API de búsqueda en el modelo de complementos de SharePoint

Importante

Los complementos de SharePoint alcanzaron la finalización de su vida útil en SharePoint Online el 2 de abril de 2026. Tanto los complementos hospedados por SharePoint como los hospedados por el proveedor se retiran y ya no funcionan en SharePoint Online, incluidas las nubes de administración pública. Las instrucciones de uso, implementación y desarrollo de complementos se conservan como referencia histórica y para escenarios de SharePoint Server aplicables, no para nuevas soluciones de SharePoint Online.

Los complementos de SharePoint Server implementados a través de un catálogo de aplicaciones local no se retiran por este cambio. La adquisición de complementos de SharePoint en el marketplace público finalizó el 2 de abril de 2026 para SharePoint Server.

Esta retirada no retira las API de REST DE SHAREPOINT, CSOM, JSOM o SharePoint Framework (SPFx). Para SharePoint Online, use SPFx para las extensiones de la interfaz de usuario y Microsoft Entra ID para la autenticación en aplicaciones externas. Consulte el anuncio de retirada y las instrucciones de migración de complementos.

El enfoque que adopte para ejecutar búsquedas con el servicio de búsqueda de SharePoint es diferente en el nuevo modelo de complemento de SharePoint que con el código de plena confianza. En un escenario típico de código de plena confianza (FTC)/solución de granja de servidores, el modelo de objetos del servidor de SharePoint (invalidaciones de elementos web Contenido por consulta) 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 CSOM o REST.

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 activos de marca en ellos.

  • El uso de la autenticación AppOnly no se admite para ninguna operación de servicio de búsqueda.
    • Esto se debe al hecho de que el servicio de búsqueda tiene acceso al servicio de perfil de usuario para buscar información de perfil de usuario y el UPS no admite la autenticación AppOnly.
    • Por lo tanto, como la relevancia de la búsqueda y otras facetas de la búsqueda dependen de un usuario determinado y de 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 cupe de opciones para ejecutar búsquedas con el servicio de búsqueda de SharePoint.

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

.NET CSOM API

En esta opción, usa la API 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 ideal para complementos hospedados por el proveedor, operaciones de larga ejecución u otros escenarios del lado servidor que se ejecutan en la plataforma .Net.
  • Algunos ejemplos de estos escenarios son los sitios web de ASP.NET MVC, los servicios ASP.NET Web API, la consola .Net o las aplicaciones de Windows, y Azure Web Jobs.

Introducción

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

La API de búsqueda y la página de personalización. Texto en imagen: Realizar la búsqueda en la API. Proporcione un filtro de búsqueda para la consulta de búsqueda de todo el inquilino: El cuadro de texto contiene la palabra Probar. Texto del botón: realizar una búsqueda simple. Realice una búsqueda personalizada de todas las plantillas del sitio con datos de perfil. Si Acerca de mí NO contiene texto AppTest solo buscamos sitios que son sitios de grupo (WebTemplate = STS). Si AppTest está presente, buscamos en todos los sitios. Escenario: mostrar sitios o datos agregados de ubicaciones específicas en función del perfil del usuario. Un ejemplo sería agregar páginas de noticias que solo están etiquetadas con un identificador que coincida con la ubicación o ciudad del usuario actual. Texto del botón: realizar una búsqueda personalizada.

El Cómo realizar consultas de búsqueda personalizadas con CSOM (vídeo PnP de O365) le guiará a través de Search.PersonalizedResults (ejemplo de 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 utiliza para tener acceso a las propiedades del 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 del 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 grupo).

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, usa la API 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 perfecta para los complementos hospedados en SharePoint y los complementos hospedados por el proveedor que se ejecutan en cualquier plataforma web.
  • Algunos ejemplos de estos escenarios son sitios web de ASP.NET MVC, sitios web de PHP, sitios web de Python, etc.

Introducción

El ejemplo de código siguiente muestra cómo ejecutar búsquedas con el servicio de búsqueda de SharePoint con la API CSOM de JavaScript (JSOM). 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, se usa la API de 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 código del lado del servidor como del lado del cliente.
  • El punto de conexión raíz de la API de REST del servicio de búsqueda de SharePoint es:
    • https://< tenant>/site/_api/search/query
  • Aquí hay algunos ejemplos simples:
    • Búsqueda de palabras clave

      https://tenant/site/_api/search/query?querytext='{Apples}'
      
    • Seleccionar 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 perfecta para los complementos hospedados en SharePoint y los complementos hospedados por el proveedor que se ejecutan en cualquier plataforma web.

  • Algunos ejemplos de estos escenarios son sitios web de ASP.NET MVC, sitios web de PHP, sitios web de Python, servicios de ASP.NET Web API, la consola .Net o aplicaciones de Windows, 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 de código .Net administrado.

  • EmployeeDirectory (contenido de aprendizaje 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 el usuario hace clic.

    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 Cómo crear complementos de SharePoint que aprovechan la búsqueda (vídeo PnP de O365) le guiará por el EmployeeDirectory (contenido de aprendizaje de OfficeDev).

Opción del lado cliente

El ejemplo de código siguiente muestra cómo ejecutar búsquedas con el servicio de búsqueda de SharePoint con la API REST de 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