Getting started

4 minute read

Note	The code samples in this tutorial can be copy pasted into VS Code Polyglot Notebooks.

Getting started with the C# SDK

Install the latest DataVision.BeeYard.Sdk NuGet package.
```
#r "nuget:DataVision.BeeYard.Sdk"
```

Create HiveClient to interact with Hive.

using System.Reflection;
using DataVision.BeeYard.Sdk;
using DataVision.BeeYard.Sdk.Shared;
using DataVision.BeeYard.Sdk.Tokens;
using System.Text.Json;

var uri = new Uri("https://demo.beeyard.ai/hive/");
var version = typeof(HiveClient).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>().InformationalVersion;
Console.WriteLine($"Hive client version: {version}");
var agent = new UserAgent("csharp-sdk", version); // optional user agent

You can either login using stored access token (provided that you’ve succesfully logged in using DataVision.BeeYard.Cli before)

var clientCredentials = new ClientCredentials("byard", "");
var client = HiveClient.CreateWithFileSystemAccessToken(uri, clientCredentials, userAgent: agent);

You can also log in using your username and password. This utilizes password grant is and is applicable to users.

var passwordCredentials = new PasswordCredentials("{your username}", "{your password}", "byard", "");
var tokenUri = new Uri("https://demo.beeyard.ai/id/oauth/token");
var client = await HiveClient.CreateWithPasswordCredentialsAndLoginAsync(uri, passwordCredentials, tokenUri, userAgent: agent).ConfigureAwait(false);

Or login with service account credentials. This utilizes client credentials grant and is applicable to clients.

var clientCredentials = new ClientCredentials("{client id}", "{client secret}");
var tokenUri = new Uri("https://demo.beeyard.ai/id/oauth/token");
var client = HiveClient.CreateWithClientCredentials(uri, tokenUri, clientCredentials, userAgent: agent);

Caution

Make sure not to accidentally commit your credentials into source code when using username and password or client credentials option.

Important

HiveClient class wraps HttpClient, so the same rules concerning disposability apply.

Reading Hive system information

To make sure the authentication procedure worked correctly, you can try reading the version of Hive which requires an authenticated client. In case the response did not succeed, the errors are printed to the console.

using (var response = await client.ReadVersionAsync())
{
    if(response.IsSuccessStatusCode)
    {
        var output = await response.ReadPayloadAsync();
        Console.WriteLine($"Hive version: {output.Version}");
    }
    else
    {
        Console.WriteLine($"Response failed with status code: {response.StatusCode}");
        var errors = await response.ReadErrorsAsync();
        foreach(var error in errors)
        {
            Console.WriteLine(error.Message);
        }
    }
}

Note	You can use `response.EnsureSuccessStatusCode()` to make sure an exception is thrown in case the response fails.

On the other hand, the health information can be accessed anonymously:

Liveness

using (var response = await client.GetLivenessAsync())
{
    Console.WriteLine($"Live: {response.IsSuccessStatusCode}");
}

Readiness

using (var response = await client.GetReadinessAsync())
{
    if(response.IsSuccessStatusCode)
    {
        var output = await response.ReadPayloadAsync();
        Console.WriteLine($"Ready: {output.OverallStatus}");
    }
}

Working with Workspaces

List available Workspaces.

using (var response = await client.SearchWorkspacesAsync())
{
    response.EnsureSuccessStatusCode();

    var workspaces = await response.ReadPayloadAsync();
    foreach(var workspace in workspaces)
    {
        Console.WriteLine($"{workspace.WorkspaceId} {workspace.Namespace}");
    }

}

Create a new Workspace.

using DataVision.BeeYard.Sdk.Hive.Workspaces;
using DataVision.BeeYard.Sdk.Hive.Workspaces.TagTemplates;

var workspaceId = Guid.NewGuid();
var @namespace = "csharpsdk";
var templateA = new TagTemplate
{
    Section = "x",
    Name = "a"
};
var templateB = new TagTemplate
{
    Section = "x",
    Name = "b"
};

var workspaceInput = new WorkspaceDescriptorInput
{
    WorkspaceId = workspaceId,
    Name = "C# SDK Test",
    Namespace = @namespace,
    TagTemplates = new List<TagTemplate>
    {
        templateA, templateB
    }
};

using (var response = await client.CreateWorkspaceAsync(workspaceInput))
{
    response.EnsureSuccessStatusCode();
}

Note	You can often skip creating a new workspace as every BeeYard deployment usually contains a default one with namespace `workspace0`.

Working with Cells

Create a Cell in the just created Workspace

using DataVision.BeeYard.Sdk.Hive.Cells;
using DataVision.BeeYard.Sdk.Hive.Cells.Tags;
using DataVision.BeeYard.Sdk.Hive.Cells.Properties;

var cellId = Guid.NewGuid();
var sdkTag = Tag.CreateWorkspaceTag(@namespace);
var tagA = Tag.FromTagTemplate(templateA, @namespace);
var property42 = Property.FromLong("Number", 42);


var cellDescriptorInput = new CellDescriptorInput();
cellDescriptorInput.Id = cellId;
cellDescriptorInput.Description = "Cell created from C# SDK";
cellDescriptorInput.Created = DateTime.UtcNow - TimeSpan.FromDays(1);
cellDescriptorInput.Tags.Add(sdkTag);
cellDescriptorInput.Tags.Add(tagA);
cellDescriptorInput.Properties.Add(property42);

using (var response = await client.CreateCellAsync(cellDescriptorInput))
{
    if(!response.IsSuccessStatusCode)
    {
        Console.WriteLine("Failed to create cell");
        var errors = await response.ReadErrorsAsync();
        foreach(var error in errors)
        {
            Console.WriteLine(error.Message);
        }
    }
}

Add Tag to just created Cell

var tagB = Tag.FromTagTemplate(templateB, @namespace);
using (var response = await client.AddTagAsync(cellId, tagB))
{
    response.EnsureSuccessStatusCode();
}

Add image to Cell

using System.IO;

var imageName = "image.png";
using (var stream = File.OpenRead("{path to image}"))
{
    using (var response = await client.AddImageAsync(cellId, imageName, stream))
    {
        response.EnsureSuccessStatusCode();
    }
}

Read image from Cell

using (var response = await client.ReadFileAsync(cellId, imageName))
{
    response.EnsureSuccessStatusCode();

    Console.WriteLine($"{response.FileType} - {response.MimeType}: {response.Size} bytes");
    using (var content = await response.ReadPayloadAsStreamAsync())
    {
        // process image content
    }
}

Remove image from Cell

using (var response = await client.RemoveFileAsync(cellId, imageName))
{
    response.EnsureSuccessStatusCode();
}

Cleaning up

Remove all Cells from the Workspace.

using DataVision.BeeYard.Sdk.Shared.Search;

var workspaceFilter = Filter.Cell.TagsIn(Tag.CreateWorkspaceTag(@namespace));
using (var response = await client.SearchCellsAsync(workspaceFilter))
{
    if(response.IsSuccessStatusCode)
    {
        var descriptors = await response.ReadPayloadAsync();
        var ids = descriptors.Select(d => d.Id).ToList();
        foreach(var id in ids)
        {
            using (var removeResponse = await client.RemoveCellAsync(id))
            {
                removeResponse.EnsureSuccessStatusCode();
            }
        }
    }
}

Remove Workspace.

using (var response = await client.RemoveWorkspaceAsync(workspaceId))
{
    response.EnsureSuccessStatusCode();
}

Dispose HiveClient
```
client.Dispose();
```