Open Data Protocol (OData)

Modified on 2010/03/10 01:33 by Shayne Burgess — Categorized as: Uncategorized

You can interact with an Open Data Protocol (OData) feed from any application that can send an HTTP request to an OData endpoint and that can process the response in the format that is returned from the service. The Microsoft Ajax library provides the Sys.Data.OpenDataServiceProxy client script class for simplifying the interaction between an Microsoft Ajax application and an OData endpoint. By using this class, you can create Web applications that interact with data through an OData service on the Web, and that can update the Web page without a full postback to the Web server.

You can also use an OpenDataDataContext instance with a DataView object. You can enable read and write capabilities and change tracking by setting the dataProvider property of the DataView to an OpenDataDataContext instance.

This topic contains information about how to create an instance of the OpenDataServiceProxy script class in an Microsoft Ajax Web site, and how to use the script class to query or modify data through the data service.

Prerequisites

In order to use the OpenDataServiceProxy class or the OpenDataDataContext class, you must add a reference to the start.debug.js script which will automatically load the necessary script files.

To use these classes in an ASP.NET Web page the following script reference must be referenced:

<script type="text/javascript" src="scripts/start.debug.js"></script>

The following Sys.require statement referencing the required object must be also included:

Sys.require([Sys.components.dataView,
                Sys.components.openDataContext, Sys.components.openDataServiceProxy]);

To use Microsoft Ajax templates for OData in an HTML page or in an MVC view, you must obtain the static script files for the Microsoft Ajax Library for OData. For more information see the odata.org website.

Note:

Alternatively, you can use release versions of these script libraries, such as start.js.

OData

The Open Data Protocol (OData) is a web protocol for querying and updating data. OData applies web technologies such as HTTP, Atom Publishing Protocol (AtomPub) and JSON to provide access to information from a variety of applications, services, and stores. This protocol emerged organically based on the experiences implementing AtomPub clients and servers in a variety of products over the past several years. OData is being used to expose and access information from a variety of sources, including but not limited to relational databases, file systems, content management systems, and traditional web sites. Microsoft has released OData under the Open Specification Promise (OSP) to allow anyone to freely interoperate with OData implementations. We intend on working with the community to move the features of OData into future version of AtomPub or other appropriate standards.

OData is consistent with the way the web works. OData makes a deep commitment to URIs as a means to identify resources (just like the web). OData commits to an HTTP-centric protocol with a uniform interface for interacting with those resources (again, just like the web). OData builds on the conventions over HTTP popularized by AtomPub, which have simplified the process of sharing data, content and information across independently developed systems. OData defines additional conventions that implementations may optionally implement to support basic query and schema information to be exchanged. To simplify integration with HTML and JavaScript clients, OData defines an optional JSON representation of the protocol that complements the XML-based AtomPub format.

Connecting to an OData Feed Using AJAX

You use the OpenDataServiceProxy script class to execute data operations of a data service. When you create an instance of the OpenDataServiceProxy class, you provide the relative URI of the data service that contains the data that you want to retrieve, as shown in the following example:

var exampleService = 
    new Sys.Data.OpenDataServiceProxy("/northwind.svc");

Querying Data

After you create an instance of the OpenDataServiceProxy class, you can call the query method to retrieve data from the data service. The following example shows how to return all the records in the Customers table. See HOW TO Query an OData Service Using Ajax for more information on implementing the cbSuccess and cbFailure callbacks.

exampleService.query("/Customers", cbSuccess, cbFailure, userContext);

The OpenDataServiceProxy class creates a URI for querying the data service by combining the value that you set in the class constructor with the value for the query parameter in the query method. The previous example combined with the class constructor example creates the URI with the following value:

/northwind.svc/Customers

The call to the query method references cbSuccess as the succeeded callback function, and cbFailure as the failed callback function. You add these callback functions to evaluate the results of the query.

You can also use the query method to specify conditions. The following example shows how to request sales orders with the shipped date of 1998 or later for the customer who is represented by the key "ALFKI":

exampleService.query("/Customers('ALFKI')/Orders?$filter=ShippedDate ge '1998-01-01'", cbSuccess, cbFailure, userContext);

Deferred Property Values

When a property in the returned data contains a large amount of data, the property value might be excluded from the results in order to avoid problems with bandwidth or CPU processing. The process of getting the data for the property is deferred until you explicitly request it by calling the fetchDeferredProperty method. A property that has been deferred will contain a property with the following name:

__deferred

This name indicates whether the property value was deferred.

The following example shows you how to use the fetchDeferredProperty method to request the data for a property that was excluded from the original results:

if (selectedItem.ProductSubcategory.__deferred) {
  exampleService.fetchDeferredProperty(
    selectedItem, 
    "ProductSubcategory",
    succeededFetchDeferredCallback,
    failedFetchDeferredCallback,
    userContext
  );
}

Modifying Data

The OpenDataServiceProxy class provides the following methods that you can call in order to modify data through a data service:

insert
update
remove
createActionSequence

You call the insert, update, or remove methods to perform a single data operation in the request. When you call these methods, the operation request is sent immediately to the data service.

The following example shows an insert operation that adds a new record in the Categories table with the value of "Decorations" for the CategoryName field.

 
var newCategory = {"CategoryName":"Decorations"};
exampleService.insert(newCategory,"/Categories");

The newCategory variable represents the data as a JavaScript object.

You use the createActionSequence method when you want to execute multiple data modification actions as a batch. The createActionSequence method returns an instance of the Sys.Data.OpenDataActionSequence class. You add data modification steps to the OpenDataActionSequence object and execute those steps by calling the execute method of the OpenDataActionSequence object.

For an example of how to execute a sequence of actions, see How to: Execute a Sequence of Actions Through an OData Service Using AJAX.

More Information

External Links

Open Data Protocol Website
MSDN Article: ASP.NET Ajax Library and WCF Data Services

Data Classes for OData

The OData classes let you add code and UI in a data source to a Web page that interacts with an OData service. For instance, you can set the OpenDataContext instance as the data source for the Microsoft Ajax DataView client control. This lets you provide data-driven UI that shows data from the service and enables updates to be submitted to the service.

The following table lists the OData classes for Microsoft Ajax.

Name	Description
Sys.Data.OpenDataActionResult Class	Represents the result of one operation from a sequence of actions executed using OData.
Sys.Data.OpenDataActionSequence Class	Exposes methods and properties for performing a batched sequence of data operations using a OData.
Sys.Data.OpenDataContext Class	Provides facilities for managing data from an OData service and for submitting changes to the service
Sys.Data.OpenDataInvokeParametersBuilder Class	Creates a dictionary of parameters to pass to the service method.
Sys.Data.OpenDataQueryBuilder Class	Provides methods and properties for manually creating an OData query.
Sys.Data.OpenDataServiceError Class	Represents an error from an OData Service.
Sys.Data.OpenDataServiceProxy Class	Provides methods and properties for interacting with an OData feed.