Muy buenas a todos,
Recientemente he publicado algunos artículos sobre Search Driven Development para SharePoint Online y SharePoint 2013. Además hace poco tiempo tuve la oportunidad de participar en una mesa redonda con la gente de MadPoint en la que se hablaba de técnicas de desarrollo tanto para SharePoint OnLine como 2013 y Office 365. En esta mesa redonda salió la posibilidad de usar en los desarrollos la API REST del servicio de búsquedas de SharePoint y los nuevos frameworks de Javascript para crear nuestra propia solución basada en búsquedas.
Hasta entonces no había tenido la oportunidad de probar esta API REST, pero hoy os traigo una entrada en la que os quiero enseñar como usar las búsquedas a través de la API REST que nos proporciona esta versión de SharePoint.
En una primera parte de la entrada os enseñaré que consultas REST podemos hacer al servicio y lo que nos devuelve y a continuación veremos ejemplos de cómo utilizar el mismo en una app for SharePoint (o SharePoint Add-ins??).
Llamadas REST para el servicio de búsqueda
Uno de los aspectos importantes que tenemos que tener en cuenta cuando trabajamos con la API REST del servicio de búsqueda es que las consultas al mismo podemos hacerlas a través de peticiones GET y a través de peticiones POST. Esto es así, porque como es sabido por todos, las peticiones GET tienen limitaciones en cuanto al número de caracteres y puede ocurrir que una consulta que queramos hacer sobrepase ese límite, por lo que tendremos la oportunidad de usar las peticiones POST para superar dicha restricción.
A continuación voy a enseñar algunos ejemplos básicos de cómo utilizar ambos tipos de peticiones, aunque las posibilidades que tenemos a la hora de hacer las peticiones son muy extensas. Para esto os dejo el enlace a la referencia de la MSDN, donde podréis analizar al completo las opciones de la API.
https://msdn.microsoft.com/es-es/library/office/jj163876.aspx
Usando peticiones GET
Las peticiones GET se hacen a través de la siguiente URL:
http://servidor/_api/search/query
| Consulta con un texto a buscar |
| /_api/search/query?querytext=’textoAconsultar’ |
| Consulta usando una query |
| /_api/search/query?querytemplate='{searchterms} FileExtension: doc’ |
| Usando la ordenación |
| /_api/search/query?querytext=’textAconsultar’&sortlist=’created:ascending,rank:descending,’ |
| Indicando los refinadores a utilizar |
| /_api/search/query?querytext=’textAconsultar’&refiners=’author,size,fileExtension’ |
| Filtrando la consulta usando el refinamiento |
| /_api/search/query?querytext=’textAconsultar’&refinementfilters=’fileExtension:equals(«docx»)’ |
Usando peticiones POST
Las peticiones POST se hacen a través de la siguiente URL:
http://servidor/_api/search/postquery
| Consulta con un texto a buscar |
{'request':
{
'__metadata' : {'type' :
'Microsoft.Office.Server.Search.REST.SearchRequest'},
'Querytext' : 'ejemploAconsultar'
}
}
|
Son muy importantes las mayúsculas y minúsculas en las consultas usando el método POST. Por ejemplo, en la consulta anterior, tenemos que usar ‘Querytext’ y no ‘QueryText’ o ‘querytext’ como hacemos en la consulta GET.
Estas consultas devuelven un JSON con toda la información necesaria de la búsqueda. Al igual que el resto de servicios REST, este de búsquedas es compatible con JSON Light, por lo que si lo deseeamos podemos obtener respuestas más ligeras y rápidas. Los resultados se encuentran en el objeto devuelto en:
data.body.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results (para GET)
data.body.d.postquery.PrimaryQueryResult.RelevantResult.Table.Rows.results (para POST)
Este elemento «results» json es un array que contiene una fila para cada uno de los resultados, en cada columna o celda de esta fila tenemos una de las propiedades del objeto devuelto. Para simplificar un poco la tarea, os voy a indicar en qué posición se encuentra la información que habitualmente es más importante de los objetos devueltos.
- Posición 3: Title
- Posición 4: Author
- Posición 5: Size
- Posición 6: Path
- Posición 7: Description
- Posición 8: Write
- Posición 11: HitHighlightedSummary
- Posición 18: FileExtension
- Posición 31: FileType
El mismo servicio, si le hemos indicado para qué propiedades queremos obtener refinadores, nos devuelve los refinadores para esa búsqueda en:
data.body.d.query.PrimaryQueryResult.RefinementResults.Refiners.results
Esto nos devuelve, para cada refinador, un objeto de la siguiente forma:
{'Entries':
{'results'
{
RefinementCount: count,
RefinementToken: token,
RefinementName: name,
RefinementValue: value
},
{
RefinementCount: count,
RefinementToken: token,
RefinementName: name,
RefinementValue: value
}
},
'Name':Refiner
}
Cada uno de los elementos contenidos en el objeto Entries, nos indica una opción de refinamiento para el refinado correspondiente. A continuación vamos a ver cómo he usado este servicio en una aplicación para SharePoint a modo de prueba.
Usando la API REST para búsquedas en una App for SharePoint
El ejemplo lo he realizado usando JQuery para manipular el DOM de la página del mismo. En primer lugar vamos a ver una captura de la aplicación para explicar que hace cada sección de la misma:
En la aplicación que os quiero enseñar he hecho 5 ejemplos de como usar la API REST del servicio de búsqueda:
- El primero ejemplo es una consulta usando GET a partir de una cadena de texto.
- El segundo ejemplo es una consulta por POST a partir de una cadena de texto.
- El tercer ejemplo usar una query para hacer la llamada al servicio de búsqueda por GET.
- En el cuarto ejemplo se usa la ordenación.
- El quinto ejemplo utiliza los refinadores.
Código del primer ejemplo
$("#searchbutton1").click(function () {
var searchText = $("#searchbox1").val();
executor.executeAsync({
method: "GET",
url: appweburl + "/_api/search/query?querytext='" + searchText + "'",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList1");
$('#resultsList1 > li').remove();
var jsonObject = JSON.parse(data.body);
console.log(jsonObject);
var results = jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for(var i = 0; i < results.length; i++)
{
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value + "
" + results[i].Cells.results[5].Value + " " + results[i].Cells.results[4].Value + "
" + results[i].Cells.results[11].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
return false;
});
Código del segundo ejemplo
$("#searchbutton2").click(function () {
var searchText = $("#searchbox2").val();
executor.executeAsync({
method: "POST",
url: appweburl + "/_api/search/postquery",
body: "{'request': { '__metadata' : {'type' : 'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext' : '" + searchText + "' }}",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList2");
$('#resultsList2 > li').remove();
var jsonObject = JSON.parse(data.body);
var results = jsonObject.d.postquery.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for (var i = 0; i < results.length; i++) {
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
return false;
});
Código del tercer ejemplo
executor.executeAsync({
method: "GET",
url: appweburl + "/_api/search/query?querytemplate='{searchterms} FileExtension: doc'",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList3");
$('#resultsList3 > li').remove();
var jsonObject = JSON.parse(data.body);
var results = jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for (var i = 0; i < results.length; i++) {
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
Los tres primeros ejemplos son muy similares. Entre el primero y el segundo la única diferencia es que una petición se hace por GET y otra petición se hace por POST. En el tercero, se vuelve a usar una consulta por GET pero en este caso en lugar de un texto lo que se pasa es una consulta como tal. Todos los ejemplos usan una lista para representar los resultados devueltos.
Código del cuarto ejemplo
$("#searchbutton4").click(function () {
var searchText = $("#searchbox4").val();
executor.executeAsync({
method: "POST",
url: appweburl + "/_api/search/postquery",
body: "{'request': { '__metadata' : {'type' : 'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext' : '" + searchText + "' }}",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList4");
$('#resultsList4 > li').remove();
var jsonObject = JSON.parse(data.body);
var results = jsonObject.d.postquery.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for (var i = 0; i < results.length; i++) {
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
return false;
});
$("#orderbutton4").change(function () {
var searchText = $("#searchbox4").val();
var value = $("#orderbutton4").val();
var order = "";
if(value == "asc")
{
order = "created:ascending";
}
else
{
order = "created:descending";
}
executor.executeAsync({
method: "GET",
url: appweburl + "/_api/search/query?querytext='" + searchText + "'&sortlist='" + order + "'",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList4");
$('#resultsList4 > li').remove();
var jsonObject = JSON.parse(data.body);
var results = jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for (var i = 0; i < results.length; i++) {
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value + " " + results[i].Cells.results[8].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
return false;
});
Básicamente este ejemplo funciona de la misma forma que los anteriores. Lo único extraordinario, tiene que ver con que queremos usar la ordenación por la propiedad «size» de los resultados. Hemos creado un combo donde podemos seleccionar, si queremos, orden ascendente y descendente para el tamaño. Lo que se ha hecho es crear otro evento que se dispara cuando cambia el valor seleccionado del combo para que se haga la ordenación. Para ello se añade a la consulta la parte correspondiente (sortlist) en función de si hemos seleccionado ascendente o descendente.
Código del último ejemplo
$("#searchbutton5").click(function () {
var searchText = $("#searchbox5").val();
executor.executeAsync({
method: "GET",
url: appweburl + "/_api/search/query?querytext='" + searchText + "'&refiners='author,size'",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList5");
$('#resultsList5 > li').remove();
var jsonObject = JSON.parse(data.body);
console.log(jsonObject);
var refiners = jsonObject.d.query.PrimaryQueryResult.RefinementResults.Refiners.results;
$("#titlerefiner").text(refiners[0].Name);
$.each(refiners[0].Entries.results, function (i, item) {
$('#valuerefiners').append($('<option>', {
value: refiners[0].Name + ":" + item.RefinementToken,
text: item.RefinementName
}));
});
var results = jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for (var i = 0; i < results.length; i++) {
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
return false;
});
$("#valuerefiners").change(function () {
var searchText = $("#searchbox5").val();
var value = $("#valuerefiners").val();
executor.executeAsync({
method: "GET",
url: appweburl + "/_api/search/query?querytext='" + searchText + "'&refinementfilters='" + value + "'",
headers: {
"accept": "application/json;odata=verbose",
"content-type": "application/json;odata=verbose"
},
success: function (data) {
var element = document.getElementById("resultsList5");
$('#resultsList5 > li').remove();
var jsonObject = JSON.parse(data.body);
var results = jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
for (var i = 0; i < results.length; i++) {
var li = document.createElement("li");
li.innerText = results[i].Cells.results[3].Value;
element.appendChild(li);
}
},
error: function (data) {
}
});
return false;
});
Este ejemplo igualmente es similar en cuanto a la forma en la que se representan los datos a los anteriores. La diferencia aquí es que a la petición le estamos indicando las propiedades de los resultados obtenidos por las que queremos poder refinar (Línea 7). Una vez que se obtienen los resultados, se carga uno de los refinadores en un combo preparado para tal efecto (Líneas 22 a 31), este combo se carga automáticamente con los valores de refinamiento obtenidos.
Además se añade otro evento para cuando ese combo cambia, con la selección de un refinamiento, de manera que se haga el filtrado correspondiente. Para ello, solo se añade a la petición el refinementfilters con el contenido a filtrar (Línea 58).
Conclusiones
Trabajar con las búsquedas de SharePoint OnLine y 2013 nos ofrece una gran cantidad de oportunidades a la hora de desarrollar de una forma sencilla, la API REST del servicio de búsqueda es muy potente y merece la pena tenerla en cuenta. En la entrada de hoy, os he introducido al uso de la misma y os he mostrado un ejemplo de cómo usarla en una ejemplo de una aplicación para SharePoint.
Y esto es todo por hoy, espero que os resulte interesante. ¿Cuál es el siguiente paso?, bueno, como sabéis me gusta mucho Polymer, y creo que podría ser interesante crear un componente Polymer que use este servicio de búsqueda de forma completa. Espero en breve compartirlo con vosotros y ponerlo disponible para que lo podáis utilizar.
Un saludo y hasta la próxima
El Blog del Programador 