odata-v4.0-os-part1-protocol 24 February 2014
Standards Track Work Product Copyright © OASIS Open 2014. All Rights Reserved. Page 13 of 69
4 Service Model
OData services are defined using a common data model. The service advertises its concrete data model
in a machine-readable form, allowing generic clients to interact with the service in a well-defined way.
An OData service exposes two well-defined resources that describe its data model; a service document
and a metadata document.
The service document lists entity sets, functions, and singletons that can be retrieved. Clients can use the
service document to navigate the model in a hypermedia-driven fashion.
The metadata document describes the types, sets, functions and actions understood by the OData
service. Clients can use the metadata document to understand how to query and interact with entities in
the service.
In addition to these two “fixed” resources an OData service consists of dynamic resources. The URLs for
many of these resources can be computed from the information in the metadata document.
See Requesting Data and Data Modification for details.
4.1 Entity-Ids and Entity References
Whereas entities in the Data Model are uniquely identified by their key values within an entity set, entities
within a payload are identified by a durable, opaque, globally unique entity-id. The entity-id MUST be an
IRI as defined in [RFC3987] and MAY be expressed in payloads and URLs as a relative reference as
appropriate. While the client MUST be prepared to accept any IRI, services MUST use valid URIs in this
version of the specification since there is currently no lossless representation of an IRI in the OData-
EntityId header.
Services are strongly encouraged to use the canonical URL for an entity as defined in [OData-URL] as its
entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the
Core.DereferenceableIDs term is applied to the entity container, nor can the client assume any
semantics from the structure of the entity-id. The canonical resource $entity provides a general
mechanism for resolving an entity-id into an entity representation.
Services that use the standard URL conventions for entity-ids annotate their entity container with the term
Core.ConventionalIDs, see [OData-VocCore].
Entity references refer to an entity using the entity's entity-id.
4.2 Read URLs and Edit URLs
The read URL of an entity is the URL that can be used to read the entity.
The edit URL of an entity is the URL that can be used to update or delete the entity.
Services are strongly encouraged to use the canonical URL for an entity as defined in [OData-URL] for
both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to
the canonical URL if the type of the entity is derived from the declared type of the entity set. However,
clients cannot assume this convention and must use the links specified in the payload according to the
appropriate format as the two URLs may be different from one another, or one or both of them may differ
from convention.
4.3 Transient Entities
Transient entities are instances of an entity type that are “calculated on the fly” and only exist within a
single payload. They cannot be reread or updated and consequently possess neither a stable entity-id nor
a read URL or an update URL.
我的内容管理
展开
