In a multichain storage system, a bucket is a logical container that stores folders or files. Each bucket has a unique name and can contain any number of folders and files. Folders are virtual containers that organize files and help manage data, and files are individual data objects that can be of any type or format. MCS Bucket files are referred to as objects.
This section describes how to use the python-MCS-SDK to perform common operations on the MCS bucket.
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
for i in bucket_client.list_buckets():
print(i.to_json())
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
# Return true if bucket created, else False
bucket_client.delete_bucket(bucket_name)
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
# Return None if MCS cannot find this bucket
print(bucket_client.get_bucket("<BUCKET_NAME>","<BUCKET_UID>").to_json())
Create an MCS Bucket
create_bucket(bucket_name)
Creates a bucket. Buckets under the same account cannot share the same name.
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
bucket_client.create_bucket("<BUCKET_NAME>")
Parameters
bucket_name : The name of the bucket
Return
Returns True if the bucket creation was successful
Get Buckets
list_buckets()
List all the existing buckets for the MCS account.
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
for i in bucket_client.list_buckets():
print(i.to_json())
Return
Returns a list of Bucket Objects
Copy {
"address": "0xA87...9b0",
"bucket_name": "test-bucket",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-01-04T17:52:04Z",
"deleted_at": null,
"file_number": 4,
"is_active": true,
"is_deleted": false,
"is_free": true,
"max_size": 34359738368,
"size": 9988,
"updated_at": "2023-01-04T17:52:04Z"
}
{
"address": "0xA87...9b0",
"bucket_name": "test-bucket2",
"bucket_uid": "552f8339-4d01-4163-8e1e-34e4b1df22fe",
"created_at": "2023-02-27T16:20:48Z",
"deleted_at": null,
"file_number": 0,
"is_active": true,
"is_deleted": false,
"is_free": true,
"max_size": 34359738368,
"size": 0,
"updated_at": "2023-02-27T16:20:48Z"
}
...
Delete Bucket
delete_bucket(bucket_name)
Removes a bucket from your account.
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
bucket_client.delete_bucket("<BUCKET_NAME>")
Parameters
bucket_name : The name of the bucket
Return
Returns True if the deletion was successful
Get Bucket information
get_bucket(bucket_name)
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
print(bucket_client.get_bucket("<BUCKET_NAME>").to_json())
Parameters
bucket_name : The name of the bucket
Return
Returns a Bucket Object
Copy {
"address": "0xA87...9b0",
"bucket_name": "test-bucket",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-01-04T17:52:04Z",
"deleted_at": null,
"file_number": 4,
"is_active": true,
"is_deleted": false,
"is_free": true,
"max_size": 34359738368,
"size": 9988,
"updated_at": "2023-01-04T17:52:04Z"
}
Create folder
create_folder(bucket_name, folder_name, prefix='')
The create_folder
the method allows you to create a folder in the specified bucket. It accepts buckets name, folder names, and prefixes. The folder will be created in bucket_name/prefix/folder_name
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
# If you want to place the folder directly in the root directory, you can leave the prefix field empty
bucket_client.create_folder("<BUCKET_NAME>","<FOLDER_NAME>","<PREFIX>")
Parameters
bucket_name : The name of the bucket
folder_name: The name of the folder to create
prefix: The prefix for the folder's object name
Return
Returns True if the folder creation was successful
Uploading file
upload_file(bucket_name, object_name, file_path, replace=False)
Uploads a file to a bucket. Use the bucket_name
to select the bucket, and object_name
to select the path and file name of the uploaded file. file_path
is the local path of the file.
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
# Object name is the destination path you want to upload to the bucket
# For example, if you want to upload the testfile.json file to path 111/222 in the TEST bucket, you would write:
# bucket_client.upload_file("TEST", "111/222/testfile.json", "<FILE_PATH>")
bucket_client.upload_file("<BUCKET_NAME>", "<OBJECT_NAME>", "<FILE_PATH>")
Parameters
bucket_name : The name of the bucket
object_name: The object name of the file ex. 'folder1/file.png'
will upload the file as file.png
inside bucket_name/folder1
file_path: The local file path
replace: File's of the same name cannot be uploaded. When replace is set to True, it will overwrite the previous file of the same name.
Return
Returns a File Object
Copy {
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "file1.txt",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 2,
"updated_at": "2023-02-08T18:35:33Z"
}
Uploading MCS Folder
upload_folder(self, bucket_name, object_name, folder_path)
Uploads folder_path
as a MCS folder under bucket_name
/object_name
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
bucket_client.upload_folder("<BUCKET_NAME>", "<OBJECT_NAME>", "<FOLDER_PATH>")
Parameters
bucket_name: The name of the bucket
object_name: The object name for the folder
folder_path: Local path of your folder
Return
Returns a list of File Objects
Copy [
{
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "file1.txt",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 2,
"updated_at": "2023-02-08T18:35:33Z"
},
{
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "file1.txt",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 2,
"updated_at": "2023-02-08T18:35:33Z"
},
...
]
Upload IPFS Folder
upload_ipfs_folder(self, bucket_name, object_name, folder_path)
Uploads folder_path
as an IPFS folder to MCS. This gives the folder its own CID, sharable to others.
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
bucket_client.upload_ipfs_folder("<BUCKET_NAME>", "<OBJECT_NAME>", "<FOLDER_PATH>")
Parameters
bucket_name: The name of the bucket
object_name: The object name for the folder
folder_path: Local path of your folder
Return
Returns a File Object for your IPFS folder
Copy {
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "ipfs-folder1",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 1,
"updated_at": "2023-02-08T18:35:33Z"
}
Downloading file
download_file(bucket_name, object_name, local_filename)
Downloads the file (located using bucket_name
/object_name
from IPFS and writes it to local_filename
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
bucket_client.download_file("<BUCKET_NAME>", "<OBJECT_NAME>", "<LOCAL_FILENAME>")
Parameters
bucket_name : The name of the bucket
object_name: The object name to download
local_filename: The download destination and filename
Return
Returns True if the file was downloaded successfully
Deleting file
delete_file(bucket_name, object_name)
Removes a file from a bucket
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
bucket_client.delete_file("<BUCKET_NAME>", "<OBJECT_NAME>")
Parameters
bucket_name : The name of the bucket
object_name: The object name to delete
Return
Returns True if the deletion was successful
Get file
get_file(bucket_name, object_name)
Get the file information of a file in one of your buckets
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
print(bucket_client.get_file("<BUCKET_NAME>", "<OBJECT_NAME>").to_json())
Parameters
bucket_name : The name of the bucket
object_name: The object name of the file
Return
Returns a File Object
Copy {
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "file1.txt",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 2,
"updated_at": "2023-02-08T18:35:33Z"
}
Get file list
list_files(bucket_name, prefix='', limit=10, offset=0)
Get a list of file information from one of your buckets
Copy from swan_mcs import APIClient, BucketAPI
mcs_api = APIClient("<API_KEY>", "<ACCESS_TOKEN>", "<CHAIN_NAME>")
bucket_client = BucketAPI(mcs_api)
for i in api.list_files("<BUCKET_NAME>", '<PREFIX>', "<LIMIT>", '<OFFSET>'):
print(i.to_json())
Return
Returns a list of File Objects
Copy [
{
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "file1.txt",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 2,
"updated_at": "2023-02-08T18:35:33Z"
},
{
"address": "0xA87...9b0",
"bucket_uid": "8721a157-8233-4d08-bb11-1911e759c2bb",
"created_at": "2023-02-08T18:35:33Z",
"deleted_at": null,
"filehash": "65a8e27d8879283831b664bd8b7f0ad4",
"gateway": "https://fce2d84f11.calibration-swan-acl.filswan.com/",
"id": 6153,
"ipfs_url": "https://ipfs.multichain.storage/ipfs/Qm...",
"is_deleted": false,
"is_folder": false,
"name": "file1.txt",
"object_name": "file1.txt",
"payloadCid": "Qm...",
"pin_status": "Pinned",
"prefix": "",
"size": 13,
"type": 2,
"updated_at": "2023-02-08T18:35:33Z"
},
...
]