Add support for SYNO.Core.Share.Snapshot

[Gestas]

Would you accept a pull request that implements list, create, and delete @ SYNO.Core.Share.Snapshot?

If yes, does it belong at synology_dsm/api/core/share/snapshot or synology_dsm/api/core/snapshot? A trace of a request points at api=SYNO.Core.Share.Snapshot.

[Quentame]

I will accept a PR of course !
You are very welcome to contribute 😊
Take the exemple of SurveillanceStation #57

synology_dsm/api/core/snapshot is nice I think.

I don't see SYNO.Core.Share.Snapshot in https://github.com/kwent/syno/tree/master/definitions/DSM/6.2.2/24922 but I do in my own NAS, is it something we activate ?
How can we access that via the DSM UI ?

Thanks.

[Quentame]

Also take care of #59

[Gestas]

@Quentame snapshots are enabled with the Snapshot Replication package. Because snapshots are taken at the Shared Folder level I'll need to implement support for shares first. See #60. These will be two different pull requests.

[Quentame]

#61 is not solving this right ?

Let me know when you are doing the snapshot work 😉

[Gestas]

@Quentame I can work on it this week. I want to support creating, updating, and deleting snapshots, how do you want to name these functions? Proposed -

def create_snapshot()
# EDIT - 8/10/2020
# WON'T DO -- def update_snapshot() --> Snapshots don't have an update option.
def delete_snapshot()

Keep in mind I'd eventually like to extend this functionality to other resources (like shares!) Do you want to merge #62 before I start or should I work against that pull request?

[Quentame]

I may merge it before yes.
Now testing all functions before merging, so should be soon.

Proposed name functions are nice 😉

[Gestas]

@Quentame should I start working against #62 or master?

[Quentame]

#62 should be merge already but has an bug.

So master, maybe your PR will go first. Or we will rebase later 😊.

[Gestas]

@Quentame after creating or deleting a snapshot we need to run api.snapshot.update() to access it. I propose that any mutating API calls (looking past just snapshots) call the appropriate api.*.update() as a final step.

Alternatively we could leave that to the user. Thoughts?

[Gestas]

@Quentame -
I've starting looking at the create snapshot work. Here's the relevant parts of a HAR from the browser -

...
  "request": {
    ...
    "headers": [....]
     ...
    "postData": {
      "mimeType": "application/x-www-form-urlencoded",
      "params": [
        {
          "name": "mode",
          "value": "\"parallel\""
        },
        {
          "name": "compound",
          "value": "[{\"api\":\"SYNO.Core.Share.Snapshot\",\"version\":1,\"snapinfo\":{\"desc\":\"create_for_har_snapshot\",\"lock\":true},\"name\":\"create_for_har\",\"method\":\"create\"}]"
        },
        {
          "name": "api",
          "value": "SYNO.Entry.Request"
        },
        {
          "name": "method",
          "value": "request"
        },
        {
          "name": "version",
          "value": "2"
        }
      ],
      "text": "mode=%22parallel%22&compound=%5B%7B%22api%22%3A%22SYNO.Core.Share.Snapshot%22%2C%22version%22%3A1%2C%22snapinfo%22%3A%7B%22desc%22%3A%22create_for_har_snapshot%22%2C%22lock%22%3Atrue%7D%2C%22name%22%3A%22create_for_har%22%2C%22method%22%3A%22create%22%7D%5D&api=SYNO.Entry.Request&method=request&version=2"
    }
  },
  "response": {
    "status": 200,
    "statusText": "OK",
    "httpVersion": "HTTP/1.1",
...
}

As you can see they are using "SYNO.Entry.Request" for mutating API calls. Do you want to add ./synology_dsm/api/entry.py for these? Creating a snapshot would look like -

api.entry.create_snapshot(<params>)

Alternatively we could make it a little more RESTful by implementing this in /synology_dsm/api/core/snapshot.py as

api.snapshot.create(<params>)

and hide the weird implementation. Also, Syno's API is weird, right? I've never seen anything else like it.

[Quentame]

@Quentame after creating or deleting a snapshot we need to run api.snapshot.update() to access it. I propose that any mutating API calls (looking past just snapshots) call the appropriate api.*.update() as a final step.

Alternatively we could leave that to the user. Thoughts?

I think you are right, call update after create 👍

[Quentame]

As you can see they are using "SYNO.Entry.Request" for mutating API calls. Do you want to add ./synology_dsm/api/entry.py for these? Creating a snapshot would look like -

api.entry.create_snapshot(<params>)

Alternatively we could make it a little more RESTful by implementing this in /synology_dsm/api/core/snapshot.py as

api.snapshot.create(<params>)

and hide the weird implementation.

Emmmm, I prefer the second approach.

Or maybe the SYNO.Entry.Request API is useful for something else too ?

Also, Syno's API is weird, right? I've never seen anything else like it.

Sure, there is ugly and weird things going on this API 😅

python-synology/synology_dsm/synology_dsm.py

Lines 96 to 103 in 27379e7

	def _is_weird_api_url(self, api):
	"""Returns True if the API URL is not common (nas_base_url/webapi/path?params) [Only handles DSM 5 for now]."""
	return (
	api in self.DSM_5_WEIRD_URL_API
	and self._information
	and self._information.version
	and int(self._information.version) < 7321 # < DSM 6
	)

[Gestas]

I think SYNO.Entry.Request is being used for most mutating API calls. I'm going to implement ./synology_dsm/api/entry.py as an internal utility and import it into /synology_dsm/api/core/snapshot.py.

I've got snapshot lists working -

print("=== Snapshots ===")
   ...: api.polling.update()
   ...: if "SnapshotReplication" in api.polling.enabled_packages:
   ...:     api.snapshot.update()
   ...:     for s in api.snapshot.snapshots:
   ...:         print("Snapshot name:      " + s.get("desc"))
   ...:         print("Snapshot on share:  " + s.get("share"))
   ...:         print("Snapshot created:   " + s.get("time"))
   ...:         print("--")
   ...:         
=== Snapshots ===
Snapshot name:      create_for_har_snapshot
Snapshot on share:  create_for_har
Snapshot created:   GMT-07-2020.08.08-08.47.26
--
Snapshot name:      create_for_har_snapshot2
Snapshot on share:  create_for_har
Snapshot created:   GMT-07-2020.08.08-12.25.56
--
Snapshot name:      snapshot_on_docker
Snapshot on share:  docker
Snapshot created:   GMT-07-2020.08.08-12.44.28
--