Downloading a file

1. Start the Python shell and configure its session.

   The following variables should be available now:

   >>> base_url  # the base URL of the API
   'https://eu2-cloud.acronis.com/api/notary/v2'
   >>> auth  # the 'Authorization' header value with the access token
   {'Authorization': 'Bearer 8770b34b74f9e4d9424eff50c38182bb4ae7f5596582ae61900b1b6a23e3ec58'}
   

2. Define a variable named file_id, and then assign the ID of the required file to this variable:

   >>> file_id = 'cc3ecc8d-de0e-4809-8bc2-3a6368110824'
   

3. Download the file by sending a GET request to the /stored-files/{file_id}/download endpoint:

   >>> response = requests.get(f'{base_url}/stored-files/{file_id}/download', headers=auth)
   

4. Check the status code of the response:

   >>> response.status_code
   200
   

   Status code 200 means that the notary service has started streaming the file contents to you. If the status code is 404, there is no file with such an ID in the storage. You may have incorrectly specified the ID or the file has been deleted from the storage.

   A different status code means that an error has occurred. For the details, refer to “Status and error codes”.

5. Fetch the file name from the value of the Content-Disposition header of the response:

   1. Define a variable named content_disposition, and then assign the value of the Content-Disposition header fetched from the response to this variable:

      >>> content_disposition = response.headers['Content-Disposition']
      >>> content_disposition
      'attachment;filename=lorem_ipsum.txt'
      

   2. Parse the file name from the header value stored in the content_disposition variable:

      >>> import re  # Provides regular expression matching operations.
      >>> file_name = re.search('filename=(.+)', content_disposition).group(1)
      >>> file_name
      'lorem_ipsum.txt'
      

6. Save the data being streamed by the service to a file:

   >>> with open(file_name, 'wb') as fd:
   ...     for chunk in response.iter_content(chunk_size=1024):
   ...         if chunk:  # filter out keep-alive new chunks
   ...             fd.write(chunk)
   446
   

   The returned value is the number of bytes written to the file.

7. [Optional] Ensure that the value of written bytes is equal to the size of the file in the storage by fetching the information about the file, and then checking the size key in the JSON object of the response.

Full code example

#!/usr/bin/env python3

import requests  # Will be used for sending requests to the API.
import hashlib   # Will be used for calculating hash values.
import os.path   # Will be used for path-related operations.
import pprint    # Will be used for formatting the output of JSON objects received in API responses.
import json      # Will be used for converting dictionaries into JSON text

# Define variables named "LOGIN" and "PASSWORD" and then assign them with your account credentials
LOGIN = '<your login>'        # Change login here
PASSWORD = '<your password>'  # Change password here

# Define a variable named "cloud_url" and then assign it with the URL of the cloud platform
cloud_url = 'https://cloud.acronis.com'

# Fetch the URL of the data center where your account is located by sending a GET request to the "/api/1/accounts" endpoint
response = requests.get(
    f'{cloud_url}/api/1/accounts',
    params={'login': LOGIN}
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and store the data center URL
# in a variable that will be used in further requests
server_url = response.json()['server_url']

# Define a variable named "account_creds", and then assign the username and password to this variable
account_creds = {
    'username': LOGIN,
    'password': PASSWORD
}

# Generate a token by sending a POST request to the "/api/2/idp/token" with your account credentials to the cloud platform
response = requests.post(
    f'{server_url}/api/2/idp/token',
    headers={'Content-Type': 'application/x-www-form-urlencoded'},
    data={'grant_type': 'password', **account_creds}
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and then assign it to a variable named "token_info"
token_info = response.json()

# Define a variable named "auth" and then assign it with a dictionary with "Authorization" key containing
# token string formatted as "Bearer <access_token>"
auth = {
    'Authorization': 'Bearer ' + token_info['access_token']
}

# Define a variable named "base_url", and then assign the API base URL using the data center URL
# to this variable
base_url = f'{server_url}/api/notary/v2'

# Define a variable named "file_id" and then assign it with the ID of the file
file_id = 'cc3ecc8d-de0e-4809-8bc2-3a6368110824'

# Download the file by sending a GET request to the "/stored-files/{file_id}/download" endpoint
response = requests.get(f'{base_url}/stored-files/{file_id}/download', headers=auth)
response.raise_for_status()

# Define a variable named "content_disposition" and store the value of the "Content-Disposition"
# header fetched from the response
content_disposition = response.headers['Content-Disposition']

# Import "re" module that provides regular expression matching operations
import re

# Define a variable named "file_name", parse the file name from the header value stored in
# the "content_disposition" variable and fetch matching group that is the name of the file
file_name = re.search('filename=(.+)', content_disposition).group(1)

# Save the data being streamed by the service to a file
with open(file_name, 'wb') as fd:
    for chunk in response.iter_content(chunk_size=1024):
        if chunk:  # filter out keep-alive new chunks
            fd.write(chunk)