Programmatically Upload a File to SystemLink Using HTTP Requests in Python

This article demonstrates how to programmatically upload files to the SystemLink File Service from a Python script. The Python script leverages the [External] requests module to send HTTP requests. The built-in SystemLink Swagger UI is used to determine the HTTP request type, parameters and  headers.

Files uploaded using this method will be visible from the Utilities >> Files page of the SystemLink Web UI.

To programmatically upload a file to SystemLink using HTTP requests in Python, refer to the sections below. If you are not familiar with the Swagger UI, it is recommended to start with Identify the HTTP Request Requirements. If you have already identified the HTTP request, jump straight to Using the File Service HTTP Request in Python.

1. Identify the HTTP Request Requirements

Before you are able to write a Python script, it is first necessary to identify what HTTP request can be used to upload files to SystemLink:

1. From the SystemLink Web UI, select Utilities >> Files.

2. From the top right-hand corner, click the ? icon and select HTTP API.
   • This opens the Swagger UI in a new tab. The Swagger UI is the HTTP API manual that installs with SystemLink and allows you to test HTTP requests live inside a browser.

3. In the Swagger UI, notice that the File Service is already selected.
   • This service is responsible for uploading, downloading, deleting and querying files in the SystemLink web UI.

4. Scroll through the list of API to find /vi/service-groups/Default/upload-files underneath the files category.
   • This POST HTTP request allows you to programmatically upload files to SystemLink.

5. Click the API to expand its details.
   • Notice that the HTTP request requires Parameters and a Request body.
6. Click Try it out to test the API live in a browser.

7. To identify the Workspace, refer to Finding a SystemLink Workspace ID. Paste the resulting ID in the Workspace field under Parameters.
8. Click Schema above the Request body string to understand the formatting requirements.

9. The Schema defines several key points:
   • The only required key is file. The metadata and id keys can be omitted entirely if preferrable.
   • The file key expects a binary string value. This indicates that to programmatically upload the file, it is not enough to point to a file path. Instead, it expects a file object stored as a binary string.
   • The metadata key expects a JSON dictionary of key/value pairs.
   • The id key expects a 24-digit hex string. Each file must have a unique ID. If an ID is not specified here, SystemLink will assign one automatically.

10. Select the Edit Value tab to exit the Schema view. Click Edit to modify the request body values.
11. As an initial test, remove the metadata and id keys. Although file currently has an invalid value, this can be left as it is for the time being.
12. Click Execute to send this HTTP request to SystemLink.

13. Scroll down to see the cURL, Request URL and Response Body. The -H (header) and -F (form) flags from the cURL will be especially helpful for building the HTTP request in Python.
    • If successful, the Code should be 201.

14. In the Files page of the SystemLink Web UI, you should see a newly uploaded file with no name and no properties in your specified Workspace.

2. Using the File Service HTTP Request in Python

Once the HTTP request has been identified and understood, you can write a Python script that leverages the header and form data seen in the cURL from the previous section:

1. In your chosen Python IDE, create a new .py file.
   • For the purposes of this demonstration, [External] IDLE is used.
2. Copy the lines below to import the [External] requests module. This module is used to send HTTP requests.

import requests

3. Define the following constants:
   • serverUrl which should be the base URL of your SystemLink Server as a string.
   • workspaceId which should be the same value as step 7 from the previous section.
   • fullUrl which should be the full URL of the HTTP request (combining the serverUrl and workspaceId). This value can be taken from the cURL in step 13 of the previous section.
   • filename which should be a string containing the full name of the file to upload.

serverUrl = 'http://<YOUR SERVER NAME>:<PORT>/'
workspaceId = '<YOUR WORKSPACE ID>'
fullUrl = serverUrl+'nifile/v1/service-groups/Default/upload-files?workspace='+workspaceId
filename = '<YOUR FILE NAME>.txt'

4. As a final constant, define apiKey. This is a string that the SystemLink Server will use to authenticate the HTTP request.
   • Refer to Using API Key in SystemLink HTTP API for instructions on how to generate an API key.

apiKey = '<YOUR API KEY>'

5. Define a headers dictionary to store the headers used for the HTTP request. The headers should be:
   • accept set to application/json
   • x-ni-api-key set to the apiKey defined in step 4.

headers = {
    'accept': 'application/json',
    'x-ni-api-key': apiKey
    }

6. Define a files dictionary to store the form data to attach to the HTTP request. This should consist of:
   • A file key set to a Python file object.
   • Ensure that the file object is configured in read mode and handled as binary data (using the rb parameter shown below).

files = {
    'file': open(filename, 'rb')
    }

7. Define a data dictionary to hold the metadata and id keys for the Response Body. For more information about the schema for these keys, refer to step 9 in the previous section.
   • For demonstration purposes, only a metadata key is used here.
   • Since SystemLink expects a JSON dictionary for metadata, it is necessary to escape any special characters.

data = {
    'metadata': '{\'property1\':\'value1\',\'property2\':\'value2\'}'
    }

8. Use the requests.post method to send the HTTP request, making sure to include the headers, files and data dictionaries defined previously.
   • Note: if you do not wish to add metadata to the file, you can exclude the data dictionary entirely.

response = requests.post(fullUrl, headers=headers, files=files, data=data)

9. For debugging purposes, print the Response Code and Response Body.

print(response.text)
print(response.reason)

10. Lastly, close any open HTTP session.

response.close()

After following the sections above, your Python script should resemble the following:

import requests

# Define connection constants
serverUrl = 'http://<YOUR SERVER NAME>:<PORT>/'
workspaceId = '<WORKSPACE ID>'
fullUrl = serverUrl+'nifile/v1/service-groups/Default/upload-files?workspace='+workspaceId
apiKey = '<API KEY>'
filename = '<YOUR FILE NAME>.txt'

# Define headers for HTTP request
headers ={
    'accept': 'application/json',
    'x-ni-api-key': apiKey
    }

# Build file dictionary to include in the POST HTTP request
files = {
    'file': open(filename, 'rb')
    }

# Add metadata as part of the data flag
data = {
    'metadata': '{\'property1\':\'value1\',\'property2\':\'value2\'}'
    }


response = requests.post(fullUrl, headers=headers, files=files, data=data)

# Print result of HTTP request
print(response.text)
print(response.reason)

# Close HTTP session
response.close()

After executing the script, an output similar below should appear to indicate that the file has been successfully uploaded:

Upon refreshing the Files page in SystemLink, you should observe that your file has been uploaded. If this file is downloaded, it should be populated with the correct contents: