TrimbleCloud.DataOcean3

Data Ocean SDK for .NET provides an interface for interacting with the Data Ocean service. It is a wrapper around the Data Ocean API.

Getting Started

Installation

This SDK is available as a NuGet package from Trimble Artifactory. To install, use the following command:

dotnet add package trimblecloud.dataocean3

Data Ocean Endpoints

Environment	Base URL Endpoint
Stage	https://cloud.stage.api.trimblecloud.com/dataocean/api/3.0
Production	https://cloud.api.trimble.com/dataocean/api/3.0

Create a DataOcean client

Configure a client using static model

using Trimble.ID;
using TrimbleCloud.DataOcean3;
var client = new DataOceanClient(new BearerTokenHttpClientProvider(tokenProvider, new Uri("https://cloud.stage.api.trimblecloud.com/dataocean/api/3.0"));
var files = await client.Files.GetFilesList().GetItems();

Configure a client using service provider model

using Trimble.ID;
using TrimbleCloud.DataOcean3;

// Setup
const TOKEN = "...";
const BASE_URL = "https://cloud.stage.api.trimblecloud.com/dataocean/api/3.0";
var tokenProvider = new FixedTokenProvider(TOKEN);
services.AddDataOcean(tokenProvider, BASE_URL);

// Usage
public class UseDataOcean(IDirectoriesAPI directoriesAPI, IFilesAPI filesAPI)
{
    private IDirectoriesAPI _directoriesAPI;

    public UseDataOcean(IDirectoriesAPI directoriesAPI, IFilesAPI filesAPI)
    {
        _directoriesAPI = directoriesAPI;
        _filesAPI = filesAPI;
    }

    public async Task DoWork()
    {
        var directories = await _directoriesAPI.GetDirectoriesList().GetItems();
        var files = await _directoriesAPI.GetFilesList().GetItems();
        var file = await _filesAPI.Create(new File() { ... });
        using (var stream = File.OpenRead("helloworld.txt"))
        {
            await _filesAPI.Upload(file.id, stream);
        }
    }
}
</code>

Get Started with Directories

Get a list of directories by parent directory ID

The following example shows how to get a list of directories.

var directories = await client.Directories.GetDirectoriesList(<directory-uuid>).GetItems();

Get a list of directories by path

The following example shows how to get a list of directories.

var directories = await client.Directories.GetDirectoriesList("/path/to/directory").GetItems();

Get a list of files in directory by ID

The following example shows how to get a list of files in directory.

var files = await client.Directories.GetFilesList(parentId: <id>, urlDuration: urlDuration).GetItems();

urlDuration in TimeSpan format specifices the duration of time for which the file download URL for each file will be valid can be specified in days(d), hours(h) or minutes(m). Minimum value 5m, maximum value 30d. Default value 1h.

Get a list of files in directory by path

The following example shows how to get a list of files in directory.

var files = await client.Directories.GetFilesList(path: "/path/to/directory", urlDuration: urlDuration).GetItems();

Get a directory by ID

The following example shows how to get a directory by ID.

var directory = await client.Directories.Read(id: directoryId);

Get a directory by path

The following example shows how to get a directory by path.

var directory = await client.Directories.Read(path: "/path/to/directory");

Create a directory

The following example shows how to create a directory.

var directory = await client.Directories.Create(new DirectoryCreate() { Path = "/path/to/directory", Metadata = new Dictionary<string, string>() { { "key", "value" } } });

Create a directory with ACL permissions

The following example shows how to create a directory with ACL permissions.

var directory = await client.Directories.Create(new DirectoryCreate() {
    Path = "/path/to/directory",
    Acl = new Dictionary<AclIdentity, AclPermission>()
    {
        { new AclApplicationIdentity(Guid.Parse("baee4a31-e307-42c2-aa8d-b7f400ba3f4e")), AclPermission.ReadOnly
    }
}});

Update a directory

The following example shows how to update a directory.

var directory = await client.Directories.Update(directoryId, new DirectoryUpdate() { Metadata = new Dictionary<string, string>() { { "key", "value" } } });

Update a directory by path

The following example shows how to update a directory by path.

var directory = await client.Directories.Update("/path/to/directory", new DirectoryUpdate() { Metadata = new Dictionary<string, string>() { { "key", "value" } } });

Delete a directory

The following example shows how to delete an empty directory.

await client.Directories.Delete(directoryId);

NOTE: If the directory is not empty, the delete operation will fail. To delete a non-empty directory, use the DeleteRecursively(Guid id) method.

Delete a directory by path

The following example shows how to delete an empty directory by path.

await client.Directories.Delete("/path/to/directory");

NOTE: If the directory is not empty, the delete operation will fail. To delete a non-empty directory, use the DeleteRecursively(string path) method.

Recursively delete a directory

The following example shows how to recursively delete a directory.

var job = await client.Directories.DeleteRecursively(directoryId);

Recursively delete a directory by path

The following example shows how to recursively delete a directory by path.

var job = await client.Directories.DeleteRecursively("/path/to/directory");

Copy a directory

The following example shows how to copy a directory.

var job = await client.Directories.Copy(directoryId, new DirectoryCreate() { Path = "/path/to/directory" });

Copy a directory by path

The following example shows how to copy a directory by path.

var job = await client.Directories.Copy("/path/to/directory", new DirectoryCreate() { Path = "/path/to/directory" });

Get Started with Files

Create a file

Create a new File object. This step is required before you are able to push file data into the service. If any of the directories provided in the path do not exist, they are automatically created. If the File already exists, a new version is created instead. If expires_at is explicitly supplied for a new version then all versions of that File will inherit the latest expires_at value.

The following example shows how to create a file.

var file = await client.Files.Create(new FileCreate()
    {
        Path = "/path/to/directory/helloworld.txt",
        RestrictedAccess = true,
        Metadata = new Dictionary<string, string>()
            {
                { "key", "value" }
            },
        MultiPart = true,
        Acl = new Dictionary<AclIdentity, AclPermission>()
            {
                { new AclApplicationIdentity(Guid.Parse("baee4a31-e307-42c2-aa8d-b7f400ba3f4e")), AclPermission.ReadOnly }
            },
        Region = new [] { "us1" }
    });

FileCreate parameters:

Parameter	Description
`Path`	The full path to the file. If the file already exists, a new version is created instead.
`RestrictedAccess`	True if the download link for the file should only be valid for a limited time. If false, the download link will be valid forever. Note that changing restricted_access to true later will not invalidate these links. Restricted download links will expire after some amount of time, currently 24 hours, after which clients must query Data Ocean to receive a newly signed link. Default: true
`Metadata`	A dictionary of key-value pairs to associate with the file.
`MultiPart`	True if the file is a multipart upload.
`Acl`	A dictionary of AclIdentity and AclPermission pairs to associate with the file.
`Region`	A list of regions to associate with the file.
`MasterId`	Use to create support files. References associated master file.
`ExpiresAt`	The time at which the file will expire. If not specified, the file will never expire.
`PathTemplate`	A template that describes how clients can access files in a fileset. For example, if files in an archive are organized into folders by country and named after the city, the `PathTemplate` could be set to `{country}/{city}.kml`. Clients can only specify this if fileset is true. Note that the `PathTemplate` is only provided to the user as a reminder of the original archive’s contents’ organization. Data Ocean doesn’t enforce or check that the archive contents match the path_template.
`Fileset`	Whether the object consists of a set of multiple files that should be treated as a single file, such as with shape files.

Get a file by ID

The following example shows how to get a file by ID.

var file = await client.Files.Read(id:fileId,version: fileVersion, region: region, urlDuration: urlDuration);

Get a file by path

The following example shows how to get a file by path.

var file = await client.Files.Read(path:"/path/to/directory/helloworld.txt", version: fileVersion, region: region, urlDuration: urlDuration);

Update a file

The following example shows how to update a file.

var file = await client.Files.Update(fileId, new FileUpdate() { Metadata = new Dictionary<string, string>() { { "key", "value" } } });

Update a file by path

The following example shows how to update a file by path.

var file = await client.Files.Update("/path/to/directory/helloworld.txt", new FileUpdate() { Metadata = new Dictionary<string, string>() { { "key", "value" } } });

Delete a file

The following example shows how to delete a file.

await client.Files.Delete(fileId);

Delete a file by path

The following example shows how to delete a file by path.

await client.Files.Delete("/path/to/directory/helloworld.txt");

Upload a file

Upload a file to an existing file object. if multiPart is set to true, the file will be uploaded in parts and it is handled by the SDK.

The following example shows how to upload a file.

using (var stream = File.OpenRead("helloworld.txt"))
{
    await client.Files.Upload(fileId, stream, version: fileVersion, concurrentRequests: concurrentRequests);
}

Parameter	Description
`concurrentRequests`	The number of concurrent requests to use when uploading the file. Default: 8.
`version`	The version of the file to upload to. If not specified, the latest version is used.
`stream`	The stream to upload.
`id`	The ID of the file to upload to.

Upload a file by path

Upload a file to an existing file object. if multiPart is set to true, the file will be uploaded in parts and it is handled by the SDK.

The following example shows how to upload a file.

using (var stream = File.OpenRead("helloworld.txt"))
{
    await client.Files.Upload("/path/to/directory/helloworld.txt", stream, version: fileVersion, concurrentRequests: concurrentRequests);
}

Parameter	Description
`concurrentRequests`	The number of concurrent requests to use when uploading the file. Default: 8.
`version`	The version of the file to upload to. If not specified, the latest version is used.
`stream`	The stream to upload.
`path`	The path of the file to upload to.

Download a file

Download a file from an existing file object.

The following example shows how to download a file.

using (var stream = File.OpenWrite("helloworld.txt"))
{
    await client.Files.Download(id: fileId, stream: stream, version: fileVersion, region: region, concurrentRequests: concurrentRequests);
}

Parameter	Description
`concurrentRequests`	The number of concurrent requests to use when downloading the file. Default: 8.
`version`	The version of the file to download. If not specified, the latest version is used.
`stream`	The stream to download to.
`id`	The ID of the file to download.
`region`	The region of the file to download.

Download a file by path

Download a file from an existing file object.

The following example shows how to download a file.

using (var stream = File.OpenWrite("helloworld.txt"))
{
    await client.Files.Download(path: "/path/to/directory/helloworld.txt", stream: stream, version: fileVersion, region: region, concurrentRequests: concurrentRequests);
}

Parameter	Description
`concurrentRequests`	The number of concurrent requests to use when downloading the file. Default: 8.
`version`	The version of the file to download. If not specified, the latest version is used.
`stream`	The stream to download to.
`path`	The path of the file to download.
`region`	The region of the file to download.

List files in a fileset

List all files in a fileset. This is only valid for filesets.

The following example shows how to list files in a fileset.

var files = await client.Files.GetFilesetManifest(id: fileId, version: fileVersion).GetItems();

List files in a fileset by path

List all files in a fileset. This is only valid for filesets.

The following example shows how to list files in a fileset.

var files = await client.Files.GetFilesetManifest(path: "/path/to/directory/helloworld.txt", version: fileVersion).GetItems();

Request scan

Enqueue a file to be scanned for malware.

The following example shows how to request scan.

var file = await client.Files.RequestScan(fileId);

Request scan by path

Enqueue a file to be scanned for malware.

The following example shows how to request scan.

var file = await client.Files.RequestScan("/path/to/directory/helloworld.txt");

Get File Versions

Get a list of all versions of a file.

The following example shows how to get file versions.

var files = await client.Files.GetFileVersions(id: fileId).GetItems();

Get File Versions by path

Get a list of all versions of a file.

The following example shows how to get file versions.

var files = await client.Files.GetFileVersions(path: "/path/to/directory/helloworld.txt").GetItems();

Samples

Find complete samples here