Upload Virtual File System

Description

This API allows users to update the contents of a File System.

Any post to this API will replace the existing set of files and directories with the uploaded set of files and directories. There is currently no support for an incremental update.

Note:

1. Only admin users can update the contents of a File System through this API
   
2. This API is available in version 4.8.1 and later

URL

Path Parameters

How to find the File System ID

The File System ID is a unique identifier given by Alation. You can find this ID in two ways.

1. Click on the File System in the Alation UI. Then check the url in your browser. The ID of the File System will be in the url. For example: If your URL is https://mycompany.alation.com/filesystem/2/, the filesystem ID is 2
   
2. Go to the settings page for a File System. There is an About section that will list it's ID.

Data Parameters

Storage Types

Each file can optionally indicate it's storage type. This is only relevant for S3 backed files. See S3 docs for details on what the storage types mean.

Sample Request Body

{"path": "/", "name": "var", "is_directory": true, "owner": "root", "group": "root", "permission_bits": 755, "size_in_bytes": 0, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}
{"path": "/var/", "name": "log", "group": "root", "is_directory": true, "owner": "root", "permission_bits": 755, "size_in_bytes": 0, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}
{"path": "/var/log/", "name": "mail.log", "group": "root", "is_directory": false, "owner": "root", "permission_bits": 755, "size_in_bytes": 28776, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}

NOTE:

1. ALL the files and directories in the File System must be included in the request body. Any not included will be removed from the File System because this is a replace operation and not an incremental update. Each line should contain exactly one file or directory that is represented by a JSON encoded object. The files and directories should be grouped according to their parent directory.
   
2. The request body must be utf-8 encoded. Other encodings may cause errors or the names may show up with strange looking characters.
   
3. The above sample request body uploads a single file mail.log to the file system.
   

Headers

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

{
    "job": {
        "url": "/api/job/1/",
        "errors_url": "/api/job_error/?job_id=1",
        "id": 1
    }
}

Error Response

Invalid Token

Status: 401 UNAUTHORIZED

Body

{
   "detail": "Authentication failed"
}

Missing Token Header

Status: 401 UNAUTHORIZED

Body

{
    "detail": "Authentication credentials were not provided."
}

Code Samples

cURL

#!/bin/bash

# This is an example token. Please replace this with your token.
API_TOKEN="2abcd-4c04-4c21-8692-eda27a877f90"

BASE_URL="https://alation.yourcompany.com/api/v1/bulk_metadata/file_upload"

# Replace contents of a file system with unique identifier, 1
curl -X POST "${BASE_URL}/1/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" --data-binary @body.txt

# contents of body.txt
: '
{"path": "/", "name": "var", "is_directory": true, "owner": "root", "group": "root", "permission_bits": 755, "size_in_bytes": 0, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}
{"path": "/var/", "name": "log", "group": "root", "is_directory": true, "owner": "root", "permission_bits": 755, "size_in_bytes": 0, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}
{"path": "/var/log/", "name": "mail.log", "group": "root", "is_directory": false, "owner": "root", "permission_bits": 755, "size_in_bytes": 28776, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}
'

Python

import requests
import json

# This is an example token. Please replace this with your token.
headers = {'Token': '2abcd-4c04-4c21-8692-eda27a877f90'}

data = '{"path": "/", "name": "var", "is_directory": true, "owner": "root", "group": "root", "permission_bits": 755, "size_in_bytes": 0, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}\n{"path": "/var/", "name": "logs", "group": "root", "is_directory": true, "owner": "root", "permission_bits": 755, "size_in_bytes": 0, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}\n{"path": "/var/logs/", "name": "mail.log", "group": "root", "is_directory": false, "owner": "root", "permission_bits": 755, "size_in_bytes": 28776, "ts_last_accessed": "2016-11-20 12:00:00", "ts_last_modified": "2016-01-01 12:00:00"}'

# replace/update contents of a file system
response = requests.post('https://alation.yourcompany.com/api/v1/bulk_metadata/file_upload/1/', data=data, headers=headers)
job_details = json.loads(response.text)
print ("Job URL: %s" % (job_details['job']['url']))
print ("Job error URL: %s" % (job_details['job']['errors_url']))

# check the job status
job_url = job_details['job']['url']
response = requests.get('https://alation.yourcompany.com' + job_url, headers=headers)
job = json.loads(response.text)
print ("Job Status: %s" % (job['status']))

# check for any erros
errors_url = job_details['job']['errors_url']
response = requests.get('https://alation.yourcompany.com' + errors_url, headers=headers)
error_details = json.loads(response.text)
if error_details:
    print ("Errors %s" % (error_details))
else:
    print ("No errors")