Example: Retrieving a single file

Frequency of useCommon
TriggerUser initiated
Pre-conditions
  • A file at '/123/folder
  • The user has READ permissions on the file
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
Files.retrieve.call(
    ResourceRetrieveRequest(
        flags = UFileIncludeFlags(
            allowUnsupportedInclude = null, 
            filterByFileExtension = null, 
            filterCreatedAfter = null, 
            filterCreatedBefore = null, 
            filterCreatedBy = null, 
            filterHiddenFiles = false, 
            filterIds = null, 
            filterProductCategory = null, 
            filterProductId = null, 
            filterProvider = null, 
            filterProviderIds = null, 
            hideProductCategory = null, 
            hideProductId = null, 
            hideProvider = null, 
            includeMetadata = null, 
            includeOthers = false, 
            includePermissions = null, 
            includeProduct = false, 
            includeSizes = null, 
            includeSupport = false, 
            includeTimestamps = true, 
            includeUnixInfo = null, 
            includeUpdates = false, 
            path = null, 
        ), 
        id = "/123/folder", 
    ),
    user
).orThrow()

/*
UFile(
    createdAt = 1632903417165, 
    id = "/123/folder", 
    owner = ResourceOwner(
        createdBy = "user", 
        project = "f63919cd-60d3-45d3-926b-0246dcc697fd", 
    ), 
    permissions = null, 
    specification = UFileSpecification(
        collection = "123", 
        product = ProductReference(
            category = "u1-cephfs", 
            id = "u1-cephfs", 
            provider = "ucloud", 
        ), 
    ), 
    status = UFileStatus(
        accessedAt = null, 
        icon = null, 
        metadata = null, 
        modifiedAt = 1632903417165, 
        resolvedProduct = null, 
        resolvedSupport = null, 
        sizeInBytes = null, 
        sizeIncludingChildrenInBytes = null, 
        type = FileType.DIRECTORY, 
        unixGroup = null, 
        unixMode = null, 
        unixOwner = null, 
    ), 
    updates = emptyList(), 
    providerGeneratedId = "/123/folder", 
)
*/
Communication Flow: TypeScript
// Authenticated as user
await callAPI(FilesApi.retrieve(
    {
        "flags": {
            "includeOthers": false,
            "includeUpdates": false,
            "includeSupport": false,
            "includeProduct": false,
            "includePermissions": null,
            "includeTimestamps": true,
            "includeSizes": null,
            "includeUnixInfo": null,
            "includeMetadata": null,
            "filterCreatedBy": null,
            "filterCreatedAfter": null,
            "filterCreatedBefore": null,
            "filterProvider": null,
            "filterProductId": null,
            "filterProductCategory": null,
            "filterProviderIds": null,
            "filterByFileExtension": null,
            "path": null,
            "allowUnsupportedInclude": null,
            "filterHiddenFiles": false,
            "filterIds": null,
            "hideProductId": null,
            "hideProductCategory": null,
            "hideProvider": null
        },
        "id": "/123/folder"
    }
);

/*
{
    "id": "/123/folder",
    "specification": {
        "collection": "123",
        "product": {
            "id": "u1-cephfs",
            "category": "u1-cephfs",
            "provider": "ucloud"
        }
    },
    "createdAt": 1632903417165,
    "status": {
        "type": "DIRECTORY",
        "icon": null,
        "sizeInBytes": null,
        "sizeIncludingChildrenInBytes": null,
        "modifiedAt": 1632903417165,
        "accessedAt": null,
        "unixMode": null,
        "unixOwner": null,
        "unixGroup": null,
        "metadata": null,
        "resolvedSupport": null,
        "resolvedProduct": null
    },
    "owner": {
        "createdBy": "user",
        "project": "f63919cd-60d3-45d3-926b-0246dcc697fd"
    },
    "permissions": null,
    "updates": [
    ]
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/files/retrieve?includeOthers=false&includeUpdates=false&includeSupport=false&includeProduct=false&includeTimestamps=true&filterHiddenFiles=false&id=/123/folder" 

# {
#     "id": "/123/folder",
#     "specification": {
#         "collection": "123",
#         "product": {
#             "id": "u1-cephfs",
#             "category": "u1-cephfs",
#             "provider": "ucloud"
#         }
#     },
#     "createdAt": 1632903417165,
#     "status": {
#         "type": "DIRECTORY",
#         "icon": null,
#         "sizeInBytes": null,
#         "sizeIncludingChildrenInBytes": null,
#         "modifiedAt": 1632903417165,
#         "accessedAt": null,
#         "unixMode": null,
#         "unixOwner": null,
#         "unixGroup": null,
#         "metadata": null,
#         "resolvedSupport": null,
#         "resolvedProduct": null
#     },
#     "owner": {
#         "createdBy": "user",
#         "project": "f63919cd-60d3-45d3-926b-0246dcc697fd"
#     },
#     "permissions": null,
#     "updates": [
#     ]
# }
Communication Flow: Visual