Overview
The Document Backup service allows you to back up and restore your Document service data with maximum performance. You can use the Document Backup service directly, with a REST API, or use the dbr command line tool, which provides an extended user experience and utilizes the Document Backup service internally.
The Document Backup service allows you to import data to your local storage and/or to the cloud. You can choose the option that best suits your needs.
You are an owner of the data, so you are responsible for backup and recovery to avoid data loss. For that purpose, it is recommended that you back up the Document service data on a regular basis. The Document Backup service is designed to simplify and speed up that process.
API Reference
/data/{tenant}/{type}
/data/{tenant}/{type}
Export documents from the Document service.
Security / Access Control:
To access this method, access token must be issued for client-owner.
Imports documents to the Document service.
Security / Access Control:
To access this method, access token must be issued for client-owner.
/backup-jobs
/backup-jobs
Get a list of backup jobs.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_view scope to manage this resource.
Create a backup job.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_backup scope to manage this resource.
/backup-jobs/{id}
Get a particular backup job.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_view scope to manage this resource.
/backups
/backups
Get all backups stored for a client-owner.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_view scope to manage this resource.
/backups/{id}
Get a particular backup.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_view scope to manage this resource.
Delete a particular backup.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_manage scope to manage this resource.
/restore-jobs
/restore-jobs
Get a list of restore jobs.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_view scope to manage this resource.
Create a restore job.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_restore scope to manage this resource.
/restore-jobs/{id}
Get a particular restore job.
Security / Access Control:
To access this method, access token must be issued for client-owner and have hybris.document-backup_view scope to manage this resource.
Considerations
The Document Backup service allows you to operate on big data sets and import data directly into the Document service database. For that reason, the Document Backup service introduces some limits to guarantee safety and avoid any performance issues in both services.
Back up and restore by client
The Document Backup service performs operations only for the client provided in the access token. To back up and/or restore data for all clients that you manage, you need to back up and restore data for each client separately.
Back up is self-contained
The Document Backup service creates a full backup containing all the data for the client provided. Note that the Document Backup service doesn't support incremental backup strategy.
Restore operation does not delete data
Data restored from the backup merely overrides the existing documents. To remove any data that does not exist in the backup copy, delete the entire type using the Document service, before you start the restoration process.
Limit on number of documents per POST request
To avoid operations that could last for a long time and slow down both the Document Backup service and the Document service, you can send at most 1000 documents in a single POST request to the Document Backup service. If you exceed that limit, you receive the 413 Request entity too large response from the service. Instead, split your request accordingly or use the dbr tool, which supports this limit by splitting the payload internally.
Limit on number of documents stored in the Document service
The Document Backup service works in close connection with the Document service. Using the Document Backup service, you can import a lot of documents quickly. That is why, when performing a restore operation, you must not exceed a total of 1 million documents of a given type stored in the Document service. For example:
- You have already a lot of documents of a given type stored in the Document service.
- You trigger the restore operation with new documents of the same type to insert.
- The sum of already-stored documents and those to insert exceeds 1 million for the considered type.
413 Request entity too large.Limit of simultaneously running requests
To ensure consistent stability and performance, the Document Backup service implements an internal limit of simultaneously running requests, for both GET and POST requests. If you reach this limit, the service returns the 429 Too many requests response. In that case, send your request at a later time.
Scopes
The Document Backup service introduces and requires the following scopes:
/data/{tenant}/{type} endpoint is an exception and does not require any scope.- hybris.document-backup_view for all GET requests
- hybris.document-backup_manage for DELETE operation on the
/backups/{id}endpoint - hybris.document-backup_backup for POST request on the
/backup-jobsendpoint - hybris.document-backup_restore for POST request on the
/restore-jobsendpoint
Security
Security considerations
The Document Backup service contains your documents. Only you, as a data controller, knows whether the document contains personal data and which data subject the data relates to. Therefore, to meet the data privacy requirements, you must map documents containing personal data with corresponding data subjects, and implement a logic to serve the data subject's requests related to its personal data, such as requests for information or deletion. To meet these goals, follow the instructions provided in the Developer Guidelines for Data Privacy. Additionally, a backup can possibly recreate the data related to a particular data subject, after the deletion of the data. Only you, as a data controller, know whether the document contains personal data and which data subject the data relates to. Therefore, implement logic to map a particular data subject to a particular document, so if the data subject requests the report with its data or data erasure, you can return or delete that document. You, as a data owner, are responsible to identify and address situations when the data is restored from a backup after the request for deletion has been made.
Identify
While subscribing to the Document Backup service, take into consideration that restoring a data set from a backup can restore personal data of a data subject who opted for the data deletion. As a data controller, you are responsible for data privacy regulations compliance. When documents stored in the Document Backup service may contain personal data, you must map those to the related data subject. Keep track of deletion requests. If you track information about which data you store in documents and who requested deletion, you can identify situations where the system restores data that you are not eligible to keep and process. To keep track of requested deletions, you can use the Audit Ingestion service and the Audit Retrieval service. Both services provide an unified approach to audit logging.
Address
To address identified occurrences of the system restoring personal data after the data subject requested its erasure, you must implement a mechanism to trigger the data deletion again.
Extended JSON format
The Document Backup service uses the MongoDB extended JSON format. The purpose of using the extended JSON format is to preserve information about type when performing a backup operation. When you perform the restore operation, the service inserts the raw data directly into the database. As a result, your documents stay exactly the same after a successful restore operation. You can open and edit the extended JSON file in any text editor.
The following is an example of the extended JSON format that you can expect when using the Document Backup service:
[
{
"_id":{
"$oid":"57d79b17d4c6b4001d419142"
},
"name":"Product",
"metadata":{
"createdAt":{
"$date":1473747735807
},
"modifiedAt":{
"$date":1473747735807
},
"version":{
"$numberLong":"1"
}
}
}
]
Use the dbr tool
The dbr is a command line tool that reads documents and indexes from the Document Backup service and writes them to a local directory as extended JSON files. Use the same directory later for restore operations, as the service inserts all of the documents as raw data, preserving the types and metadata.
First, you need to download the dbr tool:
After downloading, unzip the file. From the console, navigate to the relevant folder to use the tool.
permission denied: bin/dbr, use the chmod +x bin/dbr command.Both the backup and restore operations provide you with an option to choose an environment. The dbr tool supports all available environments, which are us-prod, us-stage, and eu. With this option, it is possible to easily migrate the data from one environment to another. You can also skip both the back up and the restoration of your indexes. For this purpose, use the --skipIndexes parameter, as described in the Parameters section, for each of the operations.
Back up the data
The first step of the backup operation is to export the CLIENT_ID and CLIENT_SECRET variables.
To set the CLIENT_ID and CLIENT_SECRET environment variables with the appropriate authorization credentials for getting an access token, follow this example:
export CLIENT_ID=<setme>
export CLIENT_SECRET=<setme>
Then, manually create a configuration file that contains a list of tenants for which you download data. See the Configuration file section for information about creating the required config file.
Finally, run the backup operation command shown, replacing the parameter values to fit your requirements. See the Parameters section for descriptions of the required parameters.
bin/dbr backup --env <env> --client <client> --config <config_file> --out <destination_dir>
Example:
bin/dbr backup --env us-prod --client hybris.product --config config.json --out tmp/hybris_product_backup
Parameters
Use these parameters in the backup operation command:
- env - The name of the target environment Possible values:
us-produs-stageeu
- client - The name of the client for which you are backing up data
- config - The file that contains the configuration where tenants and types are listed. For more information on the structure of the config file, see the next section
- out The destination folder for storing the backup output files
- skipIndexes - The parameter you can set to back up the data without indexes
Example:
bin/dbr backup --env us-prod --client hybris.product --config config.json --out tmp/hybris_product_backup --skipIndexes
Configuration file
Before running the backup operation, manually create the configuration file for backup, which contains a list of tenants to download the data for. Additionally, you can specify which types you want to download. If you do not provide any types, the backup operation includes all types. Use the example shown to create the config file.
{
"tenants" : [
{
"tenant" : "marketplace", "types" : ["products", "variants"]
},
{
"tenant" : "marketdemo"
}
]
}
Outcome of the backup operation
The outcome of the backup operation is a subfolder created in the specified destination directory. The name of the created folder follows the format convention: backup-{timestamp}. This folder contains the set of files, where each type is stored in a separate file as an extended JSON array. The following example shows the format of the file:
[
{
"_id": {
"$oid": "57ce621e0b8deb001dc138a6"
},
"name": "Product1",
"metadata": {
"createdAt": {
"$date": 1473143377441
},
"modifiedAt": {
"$date": 1473143377441
},
"version": {
"$numberLong": "1"
}
}
},
{
"_id": {
"$oid": "57ce6292e370d7001d3e9043"
},
"name": "Product2",
"metadata": {
"createdAt": {
"$date": 1473143442011
},
"modifiedAt": {
"$date": 1473143442011
},
"version": {
"$numberLong": "1"
}
}
}
]
See the Extended JSON format to learn more.
The file, backup.json, is a backup summary, generated automatically during the backup operation. The file contains the names of created data files along with the corresponding details client, tenant, and type.
Example
[
{
"client" : "hybris.marketplace",
"tenant" : "marketplace",
"type" : "products",
"file" : "a845bed7-250f-45b0-9138-fx8a2b006f1b.json"
"indexes" : [
{
"keys" : {
"sku" : 1
},
"options" : {
"name" : "skuIdx",
"unique" : true
}
}
]
}
]
Restore the data
The dbr tool also allows you to restore the data. This section describes in detail how to perform this operation.
The Document Backup service inserts your documents into the database exactly as you specify it in your request.
To set the CLIENT_ID and CLIENT_SECRET environment variables with the appropriate authorization credentials for getting an access token, follow this example:
export CLIENT_ID=<setme>
export CLIENT_SECRET=<setme>
Configuration
The configuration file for the restoration operation, called backup.json, is automatically generated during the backup operation. The file contains a list of document types to import into the Document service. Each type's configuration holds information about a client, tenant, type name, and file name under which the documents are stored. You can manipulate this file to selectively restore tenants or types.
[
{
"client" : "hybris.product",
"tenant" : "marketplace",
"type" : "products",
"file" : "388027ed-bdb2-43d7-8b21-387eba1dbd1f.json",
"indexes" : [
{
"keys" : {
"sku" : 1
},
"options" : {
"name" : "skuIdx",
"unique" : true
}
}
]
},
{
"client" : "hybris.product",
"tenant" : "marketplace",
"type" : "variants",
"file" : "6ab630cd-0404-476b-bc99-89271c5b0792.json",
"indexes" : [
{
"keys" : {
"sku" : -1
},
"options" : {
"name" : "skuIdx1"
}
}
]
}
]
The backup summary file, backup.json, is located in the backup's destination directory along with all the data files, named according to the convention, UUID.json.
Parameters
Provide these parameters in your request:
- env: The name of the target environment Possible values:
us-produs-stageeu
- dir: The source directory containing the data files and the backup.json file
- skipIndexes - The parameter you can set to restore the data without indexes
The following restore operation imports data from the files directly into the Document service:
bin/dbr restore --env <env> --client <client> --dir <source_dir>
Example:
bin/dbr restore --env us-prod --client hybris.product --dir tmp/hybris_product_backup/backup-1488799638
Information about the progress of the restore operation prints to the console.
Example:
12:29:49 Starting restore of client:
12:29:51 Restoring tenant 'product' type 'products'
12:29:51 Restored tenant 'product' type 'products'. Total 36 documents, (1 inserted, 0 replaced).
The last line displayed indicates the status of the operation, for example Restore done successfully.
Log file
Both during the backup and restore operations, in the /bin directory, the dbr.log file is created, or overwritten if it exists already. The file contains the list of operations performed, statistics such as the number of documents, and any errors that occurred.
The dbr tool performs its operations according to limits applied in the Document Backup service. If you reach any of these limits, the operation the dbr tool triggers fails. The exception here is the limit on the number of documents sent with a single restore operation, as the dbr tool splits the payload accordingly. To learn more about the limits applied, see the Considerations section of the Document Backup service documentation.
Back up and restore to a local storage
You can back up your entire collection with a single API call. The backup operation returns the documents in the form of an Extended JSON file.
You can also restore your data with a single API call. The restore operation is idempotent, which means it is safe to execute it several times. The restore operation does not delete any data. See the Consideratons section for more details.
Perform a backup operation to a local storage
To perform a backup operation, perform a GET request on the /data/{tenant}/{type} endpoint. The response is chunked and returns all documents of a given type for the specified tenant in an extended JSON format. You can store the documents, for example, on a local disk. For big sets of data, this operation might consume a lot of resources. To reduce both response times and bandwidth, set the Accept-Encoding header to gzip. This way, you receive compressed data in the GZIP format. To learn more, see the Perform a backup operation section of the Backup and restore tutorial.
Perform a restore operation to a local storage
To perform a restore operation, perform a POST request on the /data/{tenant}/{type} endpoint, sending all of the documents you want to insert into the database. It is highly recommended that you use the data received in the response from the backup operation. To reduce resource consumption, and therefore payload size and bandwidth usage, set the Content-Encoding header to gzip and send the data in the GZIP compressed format.
To learn more, see the Perform a restore operation section of the Backup and restore tutorial.
Back up to the cloud
The Document Backup service provides you with an option to store your backups in the cloud. The backed-up data is secured by encryption. This way, you do not need to organize space for all of your backups on your local storage system, but you can still explore your backups in a convenient way. The Document Backup service allows you to list all your client's backups and check the details of a particular backup.
Request a backup operation
When performing a POST request on the /backup-jobs endpoint, you create a job for data backup storage in the cloud. You can send the request without a body to back up the data for all your client's tenants. See the Consideratons section for more details about the scope of backup operations. You can also specify, in the body of your request, a list of comma-separated tenants for which to perform the backup. Additionally, you can set the skipIndexes parameter to true to skip the index backup. By default, the system backs up indexes along with the data.
{
"tenants" :
{
"include" : "marketplace, toad",
"exclude" : "marketdemo"
},
"skipIndexes": true
}
Where:
- include indicates all of the tenants to back up. The default value for this field is
*, which backs up data for all tenants. - exclude indicates all tenants you do not want to back up. The default value for this field is
"", an empty string, which excludes no tenants. - skipIndexes allows you to skip the back up of your indexes. The default value for this field is
false,
The exclude field has a higher priority. If you set the same tenant for both the include and exclude fields, the service does not back up the tenant's data.
The successful response returns a 202 Accepted status code. The backup job enters the job queue and processes when resources are available.
Check the status of backup jobs
Perform a GET request on the /backup-jobs endpoint to check the number and status of all jobs you created:
curl -H "Authorization: Bearer {ACCESS_TOKEN}" https://api.us.yaas.io/hybris/document-backup/v1/backup-jobs
The successful response returns a 200 status code with the response body similar to the example below:
[
{
"id": "5o019f9xa71e0d0e0df6193a",
"status": "succeeded",
"createdAt": "2017-05-05T10:51:47.464+0000",
"modifiedAt": "2017-05-05T10:52:47.464+0000",
"tenants": {
"include": "*",
"exclude": ""
},
"skipIndexes": true,
"backupId": "5902e148521f0a556baa4a09"
},
{
...
}
]
The response contains the following fields:
- id - The ID that the service generates for a backup job.
- status - The status of the job. Possible values are:
- created - The backup job is in the queue, waiting for processing.
- in-progress - The backup job is processing.
- succeeded - The backup job succeeded. Your backup is ready and available.
- failed - The backup job failed.
- empty - The backup job succeeded but there were no items to back up. The backup is not created.
- backupId - The ID of the backup. This is available after the job successfully completes.
- createdAt - The date of the job creation.
- modifiedAt - The date of the most recent change to a backup job.
- tenants - The list of tenants for data backup.
- skipIndexes - The field which indicates whether the skipIndexes parameter was set to
trueorfalse - errorMessage - An optional message sent back in the response only if the backup job fails.
Check the details of a backup job
You can check the details of a backup job. To do so, perform a GET request on the /backup-jobs/{id} endpoint. The successful response returns a 200 status code with the details of a given job. The following are example responses that reflect the backup job lifecycle:
| Created | In-progress | Completed |
|---|---|---|
{ "id": "59106c7f560d1a000d1910ab", "status": "created", "createdAt": "2017-05-08T13:02:55.753+0000", "tenants": { "include": "", "exclude": "" }, "skipIndexes": true } | { "id": "59106c7f560d1a000d1910ab", "status": "in-progress", "createdAt": "2017-05-08T13:02:55.753+0000", "modifiedAt": "2017-05-08T13:02:58.615+0000", "tenants": { "include": "", "exclude": "" }, "skipIndexes": true } | With success:{ "id": "59106c7f560d1a000d1910ab", "status": "succeeded", "createdAt": "2017-05-08T13:02:55.753+0000", "modifiedAt": "2017-05-08T13:03:07.627+0000", "tenants": { "include": "", "exclude": "" }, "skipIndexes": true, "backupId": "59106c82560d1a000d1910ac" }With error: { "id": "590c6305f9610f000f9aa6ed", "status": "failed", "createdAt": "2017-05-05T11:33:25.264+0000", "modifiedAt": "2017-05-05T11:33:28.330+0000", "tenants": { "include": "", "exclude": "" }, "skipIndexes": true, "errorMessage": "Can't initiate upload..." }Empty backup: { "id": "59106cad560d1a000d1910ad", "status": "empty", "createdAt": "2017-05-08T13:03:41.993+0000", "modifiedAt": "2017-05-08T13:03:43.616+0000", "tenants": { "include": "", "exclude": "" }, "skipIndexes": true } |
List all available backups
Send a GET request to the /backups endpoint to list all backups for your client:
curl -H "Authorization: Bearer {ACCESS_TOKEN}" https://api.us.yaas.io/hybris/document-backup/v1/backups
The successful response returns a 200 status code with a list of stored backups, along with basic details such as completion date and a list of tenants. An example of JSON content in the response body looks similar to the following:
[
{
"id": "5902e148521f0a556baa4a09",
"backupJobId": "5o019f9xa71e0d0e0df6193a",
"startedAt": "2017-05-05T10:51:47.464+0000",
"completedAt": "2017-05-05T10:55:47.464+0000",
"tenants" : ["marketplace", "marketdemo"],
"indexes" : "false"
},
...
]
Get details of a backup
To get details of a backup, perform a GET request on the /backups/{id} endpoint. The successful response returns a 200 status code. The response body contains the details of that backup, such as the creation date, a list of tenants, and the size of the backup data.
The response contains the following fields:
- id - The ID that the service generates for a backup.
- backupJobId - The ID of the job that triggered the backup operation.
- startedAt - The date of the start of the backup operation.
- completedAt - The date of the end of the backup operation.
- tenants - The list of tenants for data backup.
- indexes - The field that indicates whether indexes are backed up along with the data.
Example:
{
"id": "5902e148521f0a556baa4a09",
"backupJobId": "5o019f9xa71e0d0e0df6193a",
"startedAt": "2017-05-05T10:51:47.464+0000",
"completedAt": "2017-05-05T10:55:47.464+0000",
"tenants" : ["marketplace", "marketdemo"],
"indexes" : "false"
}
Delete a backup
To delete a backup, perform a DELETE request on the '/backups/{id}' endpoint. The successful response returns a 204 status code.
400 bad request status code.Restore from the cloud
In addition to storing your data in the cloud, the Document Backup service also provides you with an option to perform a restore operation from the backups stored in the cloud. A job triggers the restore process. The restore process is similar to the backup operation. The job runs independently from HTTP requests. The Document Backup service allows you to check the status of your restore job.
Request a restore operation
To create a job for data restoration, perform a POST request on the /restore-jobs endpoint with a body similar to the example:
{
"backupId" : "591e953004e824001629cf26",
"tenants" :
{
"include" : "marketplace, toad",
"exclude" : "marketdemo"
},
"skipIndexes" : true
}
Where:
- backupId identifies the backup.
- tenants includes or excludes particular tenants:
- include indicates all of the tenants you want to perform a restore operation for. The default value for this field is
*, which restores data for all tenants. - exclude indicates all tenants you do not want to restore. The default value for this field is
"", an empty string, which excludes no tenants.The exclude field has a higher priority. If you set the same tenant as a value for both the include and exclude fields, the service does not restore the tenant's data.
- include indicates all of the tenants you want to perform a restore operation for. The default value for this field is
- skipIndexes determines if the indexes are restored. The default value for this field is
false.
In the body of your request, you can specify a list of comma-separated tenants for which to perform the restore operation. When you send the request without a body, you create a job to restore data for all your client's tenants. See the Considerations section for more details about the scope of these operations. You can omit the restoration of indexes by setting the skipIndexes parameter to true.
You can specify a particular backup from which to restore the data. When the backupId is not specified, the restore operation is performed from the last available backup.
The successful response returns a 202 Accepted status code. The restore job enters the job queue and processes when resources are available.
404 bad request status code.Check the status of restore jobs
Perform a GET request on the /restore-jobs endpoint to list all your restore jobs along with details, such as job status.
curl -H "Authorization: Bearer {ACCESS_TOKEN}" https://api.us.yaas.io/hybris/document-backup/v1/restore-jobs
The successful response returns a 200 status code with a response body similar to the the example:
[
{
"id": "5o019f9xa71e0d0e0df6193a",
"status": "succeeded",
"createdAt": "2017-05-05T10:51:47.464+0000",
"modifiedAt": "2017-05-05T10:55:47.464+0000",
"tenants": {
"include": "*",
"exclude": ""
},
"backupId" : "594af32f9bf4fe000e9f93bc",
"skipIndexes": true,
"result" : {
"tenants" : [
{
"tenant" : "tenant1",
"total" : 100,
"inserted" : 20,
"replaced" : 15,
"indexes" : 2
},
{
...
}
]
},
},
{
...
}
]
The response contains the following fields:
- id - The ID that the service generates for a restore job.
- status - The status of the job. Possible values are:
- created - The restore job is in the queue, waiting for processing.
- in-progress - The restore job is processing.
- succeeded - The restore job succeeded. Your data is in the Document service.
- failed - The restore job failed.
- createdAt - The date of the start of the restore operation.
- modifiedAt - The date of the most recent change to a restore job status.
- tenants - The list of tenants specified in the request for data restoration.
- skipIndexes - Indicates whether indexes are restored or not.
- result - Stores all the details of the operation per tenant, using the following fields:
- tenant - The name of the tenant for which the data is restored.
- total - The total number of documents stored for the tenant.
- inserted - The number of documents inserted by the restore operation.
- replaced - The number of documents replaced by the restore operation.
- indexes - The number of restored indexes.
- backupId - The ID of the backup used for restoration.
- errorMessage - An optional message sent in response if the restore job fails.
Check the details of a restore job
The Document Backup service also allows you to check the details of a particular restore job. To see the details of a restore job, perform a GET request on the restore-jobs/{id} endpoint. The successful response returns a 200 status code with the details of a job.
The following are example responses that reflect the restore job lifecycle:
| Created | In-progress | Completed |
|---|---|---|
{ "id": "59106da8560d1a000d1910af", "status": "created", "createdAt": "2017-05-08T13:07:52.391+0000", "tenants": { "include": "", "exclude": "" }, "backupId": "434af32f9bf458d00e9f9c56", "skipIndexes": true, "backupId": "59106c82560d1a000d1910ac" } | { "id": "59106db4560d1a000d1910b0", "status": "in-progress", "createdAt": "2017-05-08T13:08:04.663+0000", "modifiedAt": "2017-05-08T13:08:08.624+0000", "tenants": { "include": "", "exclude": "" }, "backupId": "594af32f9bf4fe000e9f93bc", "skipIndexes": true, "backupId": "59106c82560d1a000d1910ac" } | With success:{ "id": "59106db4560d1a000d1910b0", "status": "succeeded", "createdAt": "2017-05-08T13:08:04.663+0000", "modifiedAt": "2017-05-08T13:08:11.577+0000", "tenants": { "include": "", "exclude": "" }, "backupId": "59106c82560d1a000d1910ac", "skipIndexes": true, "result": { "tenants": [ { "tenant": "eustore", "total": 10006, "inserted": 0, "replaced": 0, "indexes": 0 }, { "tenant": "usstore", "total": 10006, "inserted": 0, "replaced": 0, "indexes": 0 } ] } }With error: { "id": "59106db4560d1a000d1910b0", "status": "failed", "createdAt": "2017-05-08T13:08:04.663+0000", "modifiedAt": "2017-05-08T13:08:08.624+0000", "tenants": { "include": "", "exclude": "" }, "backupId": "a524f5d8f7f4fe000e9f435a", "skipIndexes": true, "backupId": "59106c82560d1a000d1910ac", "errorMessage": "Detailed error message.." } |
Back up and restore data
Perform a backup operation
- Method:
GET - Request URL:
https://api.us.yaas.io/hybris/document-backup/v1/data/{tenant}/{type} - URI parameters:
- Required:
- tenant: The project that requests this resource, which must match the project that is associated with the access token in the Authorization header and must be a client-owner
- type: The type attribute of the document
- Required:
- Headers:
- Accept-Encoding:
gzip
- Accept-Encoding:
- Response:
- Status code:
200
- Status code:
curl -H "Authorization: Bearer {AccessToken}" -X GET https://api.us.yaas.io/hybris/document-backup/v1/data/{tenant}/{type}
- It is highly recommended that you set the Accept-Encoding header to
gzipwhen working with big data sets. - The payload that the Document Backup service supports is different from the payload that the Document service supports.
The following is an example response body for the preceding request:
[
{
"_id": {
"$oid": "57d79b37d4c6b4001d419142"
},
"name": "Product1",
"metadata": {
"createdAt": {
"$date": 1473747735807
},
"modifiedAt": {
"$date": 1473747735807
},
"version": {
"$numberLong": "1"
}
}
},
{
"_id": {
"$oid": "57d79b184aab41001daded88"
},
"name": "Product2",
"metadata": {
"createdAt": {
"$date": 1473747736206
},
"modifiedAt": {
"$date": 1473747736206
},
"version": {
"$numberLong": "1"
}
}
}
]
Perform a restore operation
- Method:
POST - Request URL:
https://api.us.yaas.io/hybris/document-backup/v1/data/{tenant}/{type} - URI parameters:
- Required:
- tenant: The project that requests this resource, which must match the project that is associated with the access token in the Authorization header and must be a client-owner
- type: The type attribute of the document
- Required:
- Headers:
- Content-Encoding:
gzip
- Content-Encoding:
- Response:
- Status code:
200
- Status code:
gzip when working with big data sets.curl -H "Authorization: Bearer {AccessToken}" -X POST https://api.us.yaas.io/hybris/document-backup/v1/data/{tenant}/{type} -d {'RequestBody'}
Example
curl -H "Authorization: Bearer 521-20f287ce-6a5f-4418-af90-f54634c01gg3 -H "Content-type: application/json" -X POST https://api.us.yaas.io/hybris/document-backup/v1/data/{hybris.product}/{Products} -d '[
{
"_id": {
"$oid": "57ce621e0b8deb001dc138a6"
},
"name": "Product1",
"metadata": {
"createdAt": {
"$date": 1473143377441
},
"modifiedAt": {
"$date": 1473143377441
},
"version": {
"$numberLong": "1"
}
}
}
]'
The response contains information about the number of inserted and replaced documents, along with the total number of documents sent with the request:
{
"totalDocuments": 36,
"inserted": 0,
"replaced": 2
}
429 Too many requests status code, resend your request later .Security
Security considerations
The Document Backup service contains your documents. Only you, as a data controller, knows whether the document contains personal data and which data subject the data relates to. Therefore, to meet the data privacy requirements, you must map documents containing personal data with corresponding data subjects, and implement a logic to serve the data subject's requests related to its personal data, such as requests for information or deletion. To meet these goals, follow the instructions provided in the Developer Guidelines for Data Privacy. Additionally, a backup can possibly recreate the data related to a particular data subject, after the deletion of the data. Only you, as a data controller, know whether the document contains personal data and which data subject the data relates to. Therefore, implement logic to map a particular data subject to a particular document, so if the data subject requests the report with its data or data erasure, you can return or delete that document. You, as a data owner, are responsible to identify and address situations when the data is restored from a backup after the request for deletion has been made.
Identify
While subscribing to the Document Backup service, take into consideration that restoring a data set from a backup can restore personal data of a data subject who opted for the data deletion. As a data controller, you are responsible for data privacy regulations compliance. When documents stored in the Document Backup service may contain personal data, you must map those to the related data subject. Keep track of deletion requests. If you track information about which data you store in documents and who requested deletion, you can identify situations where the system restores data that you are not eligible to keep and process. To keep track of requested deletions, you can use the Audit Ingestion service and the Audit Retrieval service. Both services provide an unified approach to audit logging.
Address
To address identified occurrences of the system restoring personal data after the data subject requested its erasure, you must implement a mechanism to trigger the data deletion again.
Glossary
| Term | Description |
|---|---|
| backup | The process of reading documents from the Document service and storing them, for example in files on your |
| restore | The process of inserting documents from a backup copy to the Document service database. |
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.