Filtering and Selecting
When you query for data it’s important
to ask for only the data you really need. This keeps payload sizes down
and speeds up delivery of the data. _Api
uses OData semantics to let you do this by filtering records and
selecting properties you want. The common operators you can use for
manipulating the result set include the following:
- $filter, for filtering results
- $select, for selecting properties to return
- $expand, for expanding properties to return
- $orderby, for ordering results
- $top, for taking the top X results
The simplest way to learn about these operations is to try them out for yourself, as shown in the following exercise.
TRY IT OUT: OData Operations on Data
In this exercise you try out querying and filtering for data using the REST/OData _Api in SharePoint 2013.
1. Create a new list in your SharePoint 2013 site by clicking Site Contents from the Quick Launch navigation.
2. Click Add an App.
3. Choose Custom List and call it Movies.
4. After the list is created, add some list items to it of your favorite movie titles.
5. Modify the URL to navigate to the following URI. Review the payload XML that is returned:
https://servername/sitename/_api/Web/Lists/MoviesList/Items
6. Modify the URL by adding
(1) on the end (shown in the following code). This returns the first item in the list:
https://servername/sitename/_api/Web/Lists/MoviesList/Items(1)
7. Modify the URL and add a
$filter parameter like the following, specifying the title of one of the movies you added earlier:
?$filter=Title eq 'Aliens'
8. Add a
$select parameter to just select the
Title property of the list item:
https://servername/sitename/_api/Web/Lists/_api/Lists/ /Items?
$filter=Title eq 'Aliens'&$select=Title
You should see a payload similar to the following:
<?xml version="1.0" encoding="utf-8" ?>
<feed xml:base="https://servername/sitename/_api/"
xmlns="http://www.w3.org/2005/Atom"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml">
<id>0d01b697-f8f4-496a-bc66-81e4ab7d8208</id>
<title />
<updated>2012-11-03T07:07:21Z</updated>
<entry m:etag=""2"">
<id>f6126125-fddb-4651-bedd-d797c6ef06f4</id>
<category term="SP.Data.MoviesListItem"
scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<link rel="edit"
href="Web/Lists(guid'f57d3ddc-4522-4145-a0fe-72abbd6ea8fc')/Items(1)" />
<title />
<updated>2012-11-03T07:07:21Z</updated>
<author>
<name />
</author>
<content type="application/xml">
<m:properties>
<d:Title>Aliens</d:Title>
</m:properties>
</content>
</entry>
</feed>
Notice that only the Title property is returned.
9. Modify the
querystring as follows to order your movie titles alphabetically:
?$select=Title&$orderby=Title
10. Modify the
querystring as follows to just retrieve the first movie:
?$select=Title&$orderby=Title&$top=1
How It Works
In this exercise you queried
SharePoint list data using the REST/OData API. When a request is made
to SharePoint via this API, SharePoint uses WCF Data Services support
for OData to parse and interpret the query on the URL. It then uses
that information to translate the query into an internal SharePoint
list query (called a CAML query)
and executes the query. By adding OData support parameters to the URL
you are able to refine the query you make to SharePoint and just return
the data you specifically need.
