Synopsis:
Reads from an existing data object at the specified URI.
• <root URI> is the path to the CDMI cloud.
• <ContainerName> is zero or more intermediate containers.
• <DataObjectName> is the name of the data object to be read from. • <fieldname> is the name of a field from the response message body. • <range> is a byte range within the data object value field.
• <prefix> is a matching prefix that returns all metadata items that start with the prefix value. The object can also be accessed at <root URI>/cdmi_objectid/<objectID>.
Capabilities:
The following capabilities describe the supported operations that can be performed when reading an existing data object:
• Support for the ability to read the metadata of an existing data object is indicated by the presence of the "cdmi_read_metadata" capability in the specified object.
• Support for the ability to read the value of an existing data object is indicated by the presence of the "cdmi_read_value" capability in the specified object. Any read from a specific byte location not previously written to by a create or update operation shall return zero for the byte value.
• Support for the ability to read the value of an existing data object in specific byte ranges is indicated by the presence of the "cdmi_read_value_range" capability in the specified object. Any read from a specific byte location within the value range specified not previously written to by a create or update operation shall return zero for the byte value.
PUT /MyContainer/MyDataObject.txt HTTP/1.1 Host: cloud.example.com
Content-Type: text/plain Content-Length: 37
This is the Value of this Data Object
HTTP/1.1 201 Created
GET <root URI>/<ContainerName>/<DataObjectName>
GET <root URI>/<ContainerName>/<DataObjectName>?<fieldname>;<fieldname>;... GET <root URI>/<ContainerName>/<DataObjectName>?value:<range>;...
Request Headers:
Request Message Body: N/A
Response Headers:
Response Message Body:
Header Type Value Mandatory/Optional
Accept Header String "application/vnd.org.snia.cdmi.dataobject+json" Optional Content-Type Header String "application/vnd.org.snia.cdmi.object+json" Mandatory X-CDMI- Specification- Version Header String
A comma separated list of versions supported by the client, for example, "1.0, 1.5, 2.0".
Mandatory
Header Type Value Mandatory/Optional
Content-Type Header String "application/vnd.org.snia.cdmi.dataobject+json" Mandatory X-CDMI- Specification- Version Header String
The server shall respond with the highest version supported by both the client and the server, for example, "1.0".
Mandatory
Location Header
String
The server shall respond with the URI that the reference points to if the object is a reference.
Mandatory
Name Type Description Mandatory/Optional
objectURI JSON
String
URI of the object as specified in the request. Mandatory
objectID JSON
String
Object ID of the object Mandatory
parentURI JSON
String
URI for the parent object Mandatory
domainURI JSON
String
URI of the owning domain Mandatory
capabilitiesURI JSON String
URI to the capabilities for the object.
The capabilities URI returned is based on the object type and requested data system metadata fields.
Mandatory
completionStatus JSON String
A string indicating if the object is still in the process of being created, and once the operation is complete, if it was created successfully or an error occurred.
The value shall be the string "Processing", the string "Complete", or an error message.
If individual fields are specified in the GET request, only these fields are returned in the result body. Optional fields that are requested but do not exist are omitted from the result body. Requesting fields not defined in the standard result in a 400 Bad Request HTTP status code.
Response Status:
Example Request:
GET to the data object URI to read all fields of the data object percentComplete JSON
String
The value shall be an integer numeric value from 0 through 100.
Optional
mimetype JSON
String
Mime type of the value of the data object Mandatory
metadata JSON
Object
Metadata for the data object.
This field includes any user and data system metadata specified in the request body metadata field, along with storage system metadata generated by the cloud storage system.
See Chapter 16, “Metadata” for a further description of metadata.
Mandatory
valuerange JSON
String
The range of bytes of the value returned in the value field.
Mandatory
value String The data object value encoded in JSON. The
value field is only provided when completionStatus is "Complete".
Mandatory
HTTP Status Description
200 OK Valid response is enclosed
302 Found The URI is a reference to another URI
400 Bad Request Invalid parameter of field names in the request 401 Unauthenticated Incorrect or missing authentication credentials
403 Unauthorized Client lacks the proper authorization to perform this request 404 Not Found A data object was not found at the specified URI.
406 Not Acceptable The server is unable to provide the object in the content-type specified in the Accept header. GET /MyContainer/MyDataObject.txt HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.dataobject+json Content-Type: application/vnd.org.snia.cdmi.object+json X-CDMI-Specification-Version: 1.0
The response looks like:
Example Request:
GET to the data object URI to read the value and mimetype of the data object
The response looks like:
Example Request:
GET to the data object URI to read the first ten bytes of the value of the data object
The response looks like: HTTP/1.1 200 OK Content-Type: application/vnd.org.snia.cdmi.dataobject+json X-CDMI-Specification-Version: 1.0 { "objectURI" : "/MyContainer/MyDataObject.txt", "objectID" : "AAAAFAAo7EFMb3JlbSBpcHN1bSBkb2xvciBzaXQgYW1ldCBhbWV0Lg==", "parentURI" : "/MyContainer/", "domainURI" : "/cdmi_domains/MyDomain", "capabilitiesURI" : "/cdmi_capabilities/DataObject", "completionStatus" : "Complete", "mimetype" : "text/plain", "metadata" : { }, "valuerange" : "0-37",
"value" : "This is the Value of this Data Object" } GET /MyContainer/MyDataObject.txt?value;mimetype HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.dataobject+json Content-Type: application/vnd.org.snia.cdmi.object+json X-CDMI-Specification-Version: 1.0 HTTP/1.1 200 OK Content-Type: application/vnd.org.snia.cdmi.dataobject+json X-CDMI-Specification-Version: 1.0 {
"value" : "This is the Value of this Data Object", "mimetype" : "text/plain" } GET /MyContainer/MyDataObject.txt?valuerange;value:0-10 HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.dataobject+json Content-Type: application/vnd.org.snia.cdmi.object+json X-CDMI-Specification-Version: 1.0 HTTP/1.1 200 OK Content-Type: application/vnd.org.snia.cdmi.dataobject+json X-CDMI-Specification-Version: 1.0 { "valuerange" : "0-10", "value" : "This is th" }