OData Protocol

Article
06/27/2017

Applies To: System Center 2016 - Service Provider Foundation, System Center Technical Preview

Service Provider Foundation exposes Virtual Machine Manager (VMM) as an Open Data Protocol (OData) service. The OData service is accessed through a specific Uniform Resource Identifier (URI). The general format of the Service Provider Foundation web service URI is “https://server:port/SC2012/component/Microsoft.Management.Odata.svc/”. The following table describes the parts of the URI.

URI Part	Description
server	The server that hosts Service Provider Foundation.
port	The port on which Service Provider Foundation is hosted.
component	The System Center component you will access. For Virtual Machine Manager, use `VMM`.

Service Provider Foundation currently exposes three component services: the Administration service, the Provider service, and the Virtual Machine Manager service. For more information about the services that Service Provider Foundation provides, see Service Provider Foundation Services.

Component service protocols

The components that Service Provider Foundation provides implement the OData and generate an Atom Publishing Protocol (AtomPub) XML-based result set.

The Open Data Protocol

Service Provider Foundation uses the Open Data Protocol (OData). OData uses URIs for resource identification and commits to an HTTP-based interface for interaction with these resources. OData uses the standard HTML operations POST, GET, PUT, MERGE, and DELETE. The server translates these HTML operations into standard CRUD (create, read, update, delete) operations. For more information, seeOpen Data Protocol.

The Atom Publishing Protocol

The results from the web service query comply with the Atom Publishing Protocol (AtomPub). AtomPub provides an XML-based feed that contains zero or more entities. An entity can include metadata to describe the related resource. Service Provider Foundation supplies the metadata that is attached to an entity.

Collections and entities

When you navigate to a valid service URI, a list of collections is returned. When you access a specific collection, a list of entities is returned. Collections represent types of objects. Entities represent objects in a collection.

This URI example returns the list of collections by using the service root:
https://contoso:8090/SC2012/VMM/Microsoft.Management.Odata.svc

This URI example returns the entities of a collection:
https://contoso:8090/SC2012/VMM/Microsoft.Management.Odata.svc/VirtualMachines

This URI example returns a specific entity of a collection:
https://contoso:8090/SC2012/VMM/Microsoft.Management.Odata.svc/VirtualMachines(ID=guid'D2F1232E-3D68-478E-BC95-0518465EDC3D',StampId=guid'9CF31C95-728C-4B15-A790-6DBC2974AEF1')

How to query and filter OData entities

You can specify a query by building a query string for the current collection. OData provides several options for querying the entities in the current collection, and you can sort, format, filter, and limit the results. For more information, see the "Query String Options" section in Open Data Protocol.

Note

Depending on the service component that you are accessing through Service Provider Foundation, different restrictions or requirements might be in effect when you query collections or access entities. These restrictions and requirements are described in the service component overview topics.

You can use the OData $filter system query option to specify that you will perform a filter on the collection entities. The format of the filter query is service uri/collection?$filter=property_name operator property_value. The $filter syntax supports a variety of options. For more information about all of the options that are available to you when you perform a filter, see Filter System Query Option ($filter).

This URI example returns all the virtual machines that belong to a specific stamp from the VMM service component:
https://contoso:8090/SC2012/VMM/Microsoft.Management.Odata.svc/VirtualMachines?$filter=StampId eq guid'C20C94CA-6B16-43FF-8CE0-B49873B54F5A'

This URI example returns all the virtual machines that belong to a specific stamp and that are named Test Machine 1 from the VMM service component:
https://contoso:8090/SC2012/VMM/Microsoft.Management.Odata.svc/VirtualMachines?$filter=StampId eq guid'C20C94CA-6B16-43FF-8CE0-B49873B54F5A' and Name eq 'Test Machine 1'

Generally, when you perform the GET operation and there are more than ten entities, only the first ten entities are returned to you. To see the next set of entities, use the $skip system query option. For more information, seeSkip System Query Option ($skip).

RunAsynchronously query option

Some collection operations can use a special RunAsynchronously query option. When this option is set, the server will immediately return an HTTP response while the operation completes on the server. The following table describes which collection operations are supported:

Collection	Operation
VirtualMachines	PUT
VirtualNetworkAdapters	PUT
Services	PUT

The RunAsynchronously query option can be specified on the URL or through code.

This URI example would be used with a PUT operation and uses the RunAsynchronously query option:
https://contoso:8090/SC2012/VMM/Microsoft.Management.Odata.svc/VirtualMachines(ID=guid'D2F1232E-3D68-478E-BC95-0518465EDC3D',StampId=guid'9CF31C95-728C-4B15-A790-6DBC2974AEF1')?RunAsynchronously=0

Partager via