Subscribe to file events
This method subscribes through HTTP streaming on events of specific type for a given space.
Until the connection is kept alive, the events will be streamed to subscribers as soon as they are occur. The optional timeout parameter can be used to automatically disconnect when no events occur in a given time window.
This operation requires space_view_changes_stream privilege.
Example cURL requests
Listen to space change events
curl -N -H "X-Auth-Token: $TOKEN" \
-X POST "https://$PROVIDER_HOST/api/v3/oneprovider/changes/metadata/$SPACE_ID" \
-H "Content-Type: application/json" -d "@./changes_req.json"
Path parameters
| Parameter | Type & Description |
|---|---|
| sid required | string Space Id. |
Query parameters
| Parameter | Type & Description |
|---|---|
| timeout | integer Optional timeout in milliseconds, which allows to automatically break connection when no event occured in specified time. By default the timeout is unlimited. |
| last_seq | integer Last known file metadata sequence number |
Request body
Specification of metadata changes to observe.
List of documents which modifications should trigger sending changes.
fileMeta Specification of fileMeta fields to observe.
Specification of fileMeta fields to observe.
Indicates whether specified fileMeta fields should be sent on other metadata changes.
fileLocation Specification of fileLocation fields to observe.
Specification of fileLocation fields to observe.
Indicates whether specified fileLocation fields should be sent on other metadata changes.
times Specification of times fields to observe.
Specification of times fields to observe.
Indicates whether specified times fields should be sent on other metadata changes.
customMetadata Specification of customMetadata fields to observe.
Specification of customMetadata fields to observe.
Indicates whether specified customMetadata fields should be sent on other metadata changes.
Extended attribute names to retrieve. In case of missing fields null values are returned. In order to fetch special attributes additional keys can be specified, namely onedata_json, onedata_rdf or onedata_keyvalue (fetches all fields beside special ones).
Extended attribute names to check for existence. Existence of special attributes can also be checked by specifying onedata_json, onedata_rdf or onedata_keyvalue (checks if any normal attribute exists).
Request Examples
cat changes_req.json | oneprovider-rest-cli streamSpaceChanges sid=$SPACE_ID timeout=10000 last_seq=124721 -Responses
Subscription to events has been successful.
Unique Id of the file.
Absolute path to the file (starting with the Space name).
Sequence number (version) of the metadata document.
fileMeta Requested fileMeta fields and additional information.
Requested fileMeta fields and additional information.
Last revision of fileMeta.
Indicates whether this metadata was deleted or not.
Indicates whether changes occured to this metadata or not.
fields
File name.
The type of the file:
REG- regular file,DIR- directory,SYMLNK- symbolic link.
POSIX file permissions.
File owner.
Id of provider which created this file.
Array of this file shares Ids.
Set to 'true' when file itself was deleted but file metadata must remain for some time. Otherwise false.
fileLocation Requested fileLocation fields and additional information.
Requested fileLocation fields and additional information.
Last revision of fileLocation.
Indicates whether this metadata was deleted or not.
Indicates whether changes occured to this metadata or not.
fields
Provider Id in which change occured.
Storage Id in which file exists.
File size.
Space Id in which space exists.
Indicates whether file was created on storage or only metadata exists.
times Requested times fields and additional information.
Requested times fields and additional information.
Last revision of times.
Indicates whether this metadata was deleted or not.
Indicates whether changes occured to this metadata or not.
fields
POSIX atime.
POSIX mtime.
POSIX ctime.
customMetadata Requested customMetadata fields and additional information.
Requested customMetadata fields and additional information.
Last revision of customMetadata.
Indicates whether this metadata was deleted or not.
Indicates whether changes occurred to this metadata or not.
Retrieved extended attribute values. In case of missing fields null values are returned.
Map indicating whether given extended attributes exists or not.
Example
{
"fileId": "4efc4a0c-0a61-4766-8fe9-c3d7fb414da8",
"filePath": "/Space1/dir2/file1.txt",
"seq": 123,
"fileMeta": {
"rev": "2-c500a5eb026d9474429903d47841f9c5",
"mutators": [
"<<\"p1.1542789098.test\">>"
],
"changed": true,
"deleted": false,
"fields": {
"owner": "john"
}
},
"customMetadata": {
"rev": "1-09f941b4e8452ef6a244c5181d894814",
"mutators": [
"<<\"p1.1542789098.test\">>"
],
"changed": false,
"deleted": false,
"exists": {
"onedata_json": true
},
"fields": {
"key1": "value1"
}
}
}Invalid request.
error Object describing an error.
Object describing an error.
String identifying the error type. Does not change between error instances.
Human readable error description. May contain information specific to given error instance.
Details about the error instance. The object schema is specific to each error type.
ctx required Technical information about error.
Technical information about error.
Timestamp in milliseconds.
Release version of a product, for example "25.1".
Identifier of a service instance — either Oneprovider Id or "onezone".
Domain of the service.
Build version of the service.
Short name of service.
Revision of onedata-errors repo, where the error is defined.
Module where the error occurred.
Line number in the module where the error occurred.
Example
{
"error": {
"id": "example",
"description": "This is an example error.",
"ctx": {
"timestamp": 1750762637248,
"serviceReleaseVersion": "25.1",
"serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
"serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
"serviceBuildVersion": "231-g8d26f953c3",
"service": "opw",
"onedataErrorsRevision": "ca3af8cb",
"module": "metadata_req",
"line": 45
}
}
}Forbidden request.
error Object describing an error.
Object describing an error.
String identifying the error type. Does not change between error instances.
Human readable error description. May contain information specific to given error instance.
Details about the error instance. The object schema is specific to each error type.
ctx required Technical information about error.
Technical information about error.
Timestamp in milliseconds.
Release version of a product, for example "25.1".
Identifier of a service instance — either Oneprovider Id or "onezone".
Domain of the service.
Build version of the service.
Short name of service.
Revision of onedata-errors repo, where the error is defined.
Module where the error occurred.
Line number in the module where the error occurred.
Example
{
"error": {
"id": "example",
"description": "This is an example error.",
"ctx": {
"timestamp": 1750762637248,
"serviceReleaseVersion": "25.1",
"serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
"serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
"serviceBuildVersion": "231-g8d26f953c3",
"service": "opw",
"onedataErrorsRevision": "ca3af8cb",
"module": "metadata_req",
"line": 45
}
}
}Oneprovider REST API not available.
error Object describing an error.
Object describing an error.
String identifying the error type. Does not change between error instances.
Human readable error description. May contain information specific to given error instance.
Details about the error instance. The object schema is specific to each error type.
ctx required Technical information about error.
Technical information about error.
Timestamp in milliseconds.
Release version of a product, for example "25.1".
Identifier of a service instance — either Oneprovider Id or "onezone".
Domain of the service.
Build version of the service.
Short name of service.
Revision of onedata-errors repo, where the error is defined.
Module where the error occurred.
Line number in the module where the error occurred.
Example
{
"error": {
"id": "example",
"description": "This is an example error.",
"ctx": {
"timestamp": 1750762637248,
"serviceReleaseVersion": "25.1",
"serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
"serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
"serviceBuildVersion": "231-g8d26f953c3",
"service": "opw",
"onedataErrorsRevision": "ca3af8cb",
"module": "metadata_req",
"line": 45
}
}
}Internal server error.
error Object describing an error.
Object describing an error.
String identifying the error type. Does not change between error instances.
Human readable error description. May contain information specific to given error instance.
Details about the error instance. The object schema is specific to each error type.
ctx required Technical information about error.
Technical information about error.
Timestamp in milliseconds.
Release version of a product, for example "25.1".
Identifier of a service instance — either Oneprovider Id or "onezone".
Domain of the service.
Build version of the service.
Short name of service.
Revision of onedata-errors repo, where the error is defined.
Module where the error occurred.
Line number in the module where the error occurred.
Example
{
"error": {
"id": "example",
"description": "This is an example error.",
"ctx": {
"timestamp": 1750762637248,
"serviceReleaseVersion": "25.1",
"serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
"serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
"serviceBuildVersion": "231-g8d26f953c3",
"service": "opw",
"onedataErrorsRevision": "ca3af8cb",
"module": "metadata_req",
"line": 45
}
}
}