Unity REST API Integration¶
This covers integrating and using our REST API in the Unity editor. All the files covered here are part of the Genvid Unity Package and are automatically installed when running the py unity.py build command.
How to use the REST API¶
As long as you include the dll files in your project, you will be able call the GenvidRESTCSharp API without any issues. In this section, we cover step-by-step how to make proper calls to the API.
BastionClustersAPI¶
- Create a new
Genvid.Consul.Client
.
private static Genvid.Consul.Client _client = null;
private static Genvid.Consul.Client Consul
{
get
{
if (_client == null)
{
_client = new Genvid.Consul.Client();
}
return _client;
}
}
- Get the service
bastion-api
from the Consul client created in the last step. - Perform a
GetEnumerator
on the service and then get theCurrent
on the service. - Create the string:
http://
+ the current service ServiceAddress +:
+ the current service ServicePort +/v1
.
private static string BastionUrl
{
get
{
var iservices = Consul.catalog.service("bastion-api");
var services = iservices.GetEnumerator();
if (!services.MoveNext())
{
projectAvailable = false;
return "no project loaded";
}
else
{
projectAvailable = true;
}
var service = services.Current;
return string.Format("http://{0}:{1}/v1", service.ServiceAddress, service.ServicePort);
}
}
- Create a new
Genvid.Api.BastionClustersApi
object using the string you created as a parameter. - You can access the available clusters with the
Genvid.Api.BastionClustersApi
object. You need to do agetClusters()
on theGenvid.Api.BastionClustersApi
object which returns a list ofGenvid.Model.Bastion.ClusterOperator
.
var tempBastion = new Genvid.Api.BastionClustersApi(BastionUrl);
listClusterOperator = tempBastion.getClusters();
listClusterOperator.Sort(delegate (Genvid.Model.Bastion.ClusterOperator elementCompare1, Genvid.Model.Bastion.ClusterOperator elementCompare2)
{
return elementCompare1.id.CompareTo(elementCompare2.id);
});
Each
Genvid.Model.Bastion.ClusterOperator
in the list contains the same type of structure:-
ClusterOperator
¶ A Cluster from the Bastion-API.
Object Properties: { "category": "RLZpJDNqnMLHlmqUjpvT", "instanceID": "RZgVoZTZKVuIOQgJNaul", "id": "sERaSSAKbyoMUxqRRUYJ", "source": "weZKEEiKxuPcSlxRCeiT" }
-
HealthAPI¶
- Create a new
Genvid.Consul.Client
.
private static Genvid.Consul.Client _client = null;
private static Genvid.Consul.Client Consul
{
get
{
if (_client == null)
{
_client = new Genvid.Consul.Client();
}
return _client;
}
}
- Get the service
bastion-api
from the Consul client you created in the previous step. - Perform a
GetEnumerator
on the service and then get theCurrent
on the service. - Create the string:
http://
+ the current service ServiceAddress +:
+ the current service ServicePort +/v1/proxy/
+ theClusterName +/cluster-api/v1/
.
private string ClusterUrl
{
get
{
var iservices = Consul.catalog.service("bastion-api");
var services = iservices.GetEnumerator();
if (!services.MoveNext())
{
projectAvailable = false;
return "no project loaded";
}
else
{
projectAvailable = true;
}
var service = services.Current;
return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
}
}
- Create a new
Genvid.Api.HealthApi
object using the string you created as a parameter. - With the
Genvid.Api.HealthApi
object, you can access the health service of your choice. In our case, we want to access the SDK Health check by passing the service name as a parameter togetServiceHealth
.
var healthApi = new Genvid.Api.HealthApi(stringCluster);
HealthCheckList = healthApi.getServiceHealth("SDK Health check");
Afterwards, you can use the
Genvid.Api.HealthApi
object list to access data from it. In this case, you need the first element of the list.If you want a better format for the
Output
string, you can deserialize it as aGenvid.Model.Cluster.HealthCheckOutput
. Before attempting to deserialize theOutput
string, make sure you set the objectStatus
topassing
.
if (HealthCheckList.Count > 0)
{
if (HealthCheckList[healthCheckSelection].Status == "passing")
{
currentHealthCheckOutput = Newtonsoft.Json.JsonConvert.DeserializeObject<Genvid.Model.Cluster.HealthCheckOutput>(HealthCheckList[healthCheckSelection].Output);
}
else
{
currentHealthCheckOutput = null;
}
}
else
{
currentHealthCheckOutput = null;
}
See SDK Health Check for more information about the structure contents for the health check.
JobsAPI¶
- Create a new
Genvid.Consul.Client
.
private static Genvid.Consul.Client _client = null;
private static Genvid.Consul.Client Consul
{
get
{
if (_client == null)
{
_client = new Genvid.Consul.Client();
}
return _client;
}
}
- Get the service
bastion-api
you created in the previous step from the Consul client. - Perform a
GetEnumerator
on the service and then get theCurrent
on the service. - Create the string:
http://
+ the current service ServiceAddress +:
+ the current service ServicePort +/v1/proxy/
+ theClusterName +/cluster-api/v1/
.
private string ClusterUrl
{
get
{
var iservices = Consul.catalog.service("bastion-api");
var services = iservices.GetEnumerator();
if (!services.MoveNext())
{
projectAvailable = false;
return "no project loaded";
}
else
{
projectAvailable = true;
}
var service = services.Current;
return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
}
}
- Create a new
Genvid.Api.JobsApi
object using the string you created as a parameter. - Use the
Genvid.Api.JobsApi
object to perform the available tasksstartJob(properJobName)
orstopJob(properJobName)
.
public void connectToWebJobs(int typeExecution, string jobName)
{
var api = new Genvid.Api.JobsApi(ClusterUrl);
if (typeExecution == startJob)
{
api.startJob(jobName);
UnityEngine.Debug.Log(jobName + " is started !");
}
else if (typeExecution == stopJob)
{
api.stopJob(jobName);
UnityEngine.Debug.Log(jobName + " is stopped !");
}
}
LinksAPI¶
- Create a new
Genvid.Consul.Client
.
private static Genvid.Consul.Client _client = null;
private static Genvid.Consul.Client Consul
{
get
{
if (_client == null)
{
_client = new Genvid.Consul.Client();
}
return _client;
}
}
- Get the service
bastion-api
From the Consul client you created in the previous step. - Perform a
GetEnumerator
on the service and then get theCurrent
on the service. - Create the string:
http://
+ the current service ServiceAddress +:
+ the current service ServicePort +/v1/proxy/
+ theClusterName +/cluster-api/v1/
.
private string ClusterUrl
{
get
{
var iservices = Consul.catalog.service("bastion-api");
var services = iservices.GetEnumerator();
if (!services.MoveNext())
{
projectAvailable = false;
return "no project loaded";
}
else
{
projectAvailable = true;
}
var service = services.Current;
return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
}
}
- Create a new
Genvid.Api.JobsApi
object using the string you created as a parameter. - Use the
Genvid.Api.LinksApi
object to perform agetLinks
with the proper category and JobName as parameters. - Perform an
Application.OpenUrl
on the.href
for each object of the list returned.
public void openLink(string name, string category = "")
{
if (name == "cluster-ui")
{
string url = ClusterUIUrl;
UnityEngine.Debug.Log(string.Format("Opening Cluster-UI at {0}", url));
Application.OpenURL(url);
return;
}
var api = new Genvid.Api.LinksApi(ClusterUrl);
var links = api.getLinks(category, name);
foreach (var link in links)
{
UnityEngine.Debug.Log(string.Format("Opening {0} at {1}", link.name, link.href));
Application.OpenURL(link.href);
}
}
SettingsAPI¶
- Create a new
Genvid.Consul.Client
.
private static Genvid.Consul.Client _client = null;
private static Genvid.Consul.Client Consul
{
get
{
if (_client == null)
{
_client = new Genvid.Consul.Client();
}
return _client;
}
}
- Get the service
bastion-api
from the Consul client you created in the previous step. - Perform a
GetEnumerator
on the service and then get theCurrent
on the service. - Create the string:
http://
+ the current service ServiceAddress +:
+ the current service ServicePort +/v1/proxy/
+ theClusterName +/cluster-api/v1/
.
private string ClusterUrl
{
get
{
var iservices = Consul.catalog.service("bastion-api");
var services = iservices.GetEnumerator();
if (!services.MoveNext())
{
projectAvailable = false;
return "no project loaded";
}
else
{
projectAvailable = true;
}
var service = services.Current;
return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
}
}
- Create a new
Genvid.Api.JobsApi
object using the string you created as a parameter. - Use the
Genvid.Api.SettingsApi
object to perform agetSettings
which returns aGenvid.Model.Cluster.Settings
object.
private void loadSettings()
{
var tempSettings = new Genvid.Api.SettingsApi(ClusterUrl).getSettings();
var tempSettingsProperties = tempSettings.GetType().GetProperties();
if (oldSettingsLoaded == null || compareSettings(tempSettingsProperties, tempSettings, oldSettingsToSendLoaded, oldSettingsLoaded) == false)
{
oldSettingsLoaded = tempSettings;
oldSettingsToSendLoaded = oldSettingsLoaded.GetType().GetProperties();
var tempSettingsNew = new Genvid.Api.SettingsApi(ClusterUrl).getSettings();
var tempSettingsPropertiesNew = tempSettingsNew.GetType().GetProperties();
newSettings = tempSettingsNew;
settingsToSend = tempSettingsPropertiesNew;
}
}
- You can also use the
Genvid.Api.SettingsApi
object to perform asetSettings
with aGenvid.Model.Cluster.Settings
object as a parameter to save your settings.
public void saveSettings(Genvid.Model.Cluster.Settings newSettings)
{
var api = new Genvid.Api.SettingsApi(ClusterUrl);
api.setSettings(newSettings);
}
Genvid window usage¶
Warning
This feature is currently in beta. The window is functional, but we expect to make some changes in the future to add new features and improve the user experience. We welcome your feedback on the process.
A Genvid window is now available in the Window dropdown menu. This
menu is only available if you integrated files from Cluster-API into your
project along with GenvidWindow.cs
as indicated at the top of this page.
To see the content in this window, your Genvid Bastion must be set up and the Unity project loaded as explained previously. This gives you some direct access to the different websites available, as well as the ability to control some jobs running in your local cluster.
The following sections give more details on each section of the window and their functions.
Clusters¶
We display all the clusters currently available for the project in a combo list. < Select a Cluster > is the default selection. The number of clusters available is displayed beside the foldout. Make sure to select the proper cluster when using the SDK with this window.
Health check¶
In this section, we describe the content of the
Genvid.Model.Cluster.HealthCheckOutput.State
from the service
SDK Health check
. The contents include:
- ComposeConnected is the Compose connection status.
- NatsConnected is the NATS connection status.
- NumStreams is the number of streams connected.
This section only appears when the game is running, otherwise it displays the
error message No project currently running. At the top of this
section, there is a summary of the number of streams active and if both
Compose
and NATS
are connected.
Jobs¶
A foldout lists all the jobs available for your project along a Start All button. Opening the foldout displays a button labeled On/Off. The button is green when the job is activated and red when deactivated.
Click on the button to start or stop a job. All the tasks associated with the jobs are listed in the foldout when a job is active.
Links¶
All the links available for your project are listed with a button. When the button displays Open Link, click the button to open the link. When the button displays Error, clicking the button to display the error in the Console.
If a link is associated with a job, you need to start the job to use the link properly. For example, in our Unity sample the Tutorial Admin and Tutorial Demo links won’t work unless the Web job is running.
Logs¶
This section only include a button Open Link and upon clicking on it, the logs page is displayed.
Settings¶
All the settings associated with the project are listed within different
foldouts. Beside the foldout, we have the info.name
, the
encode.output.width
, the encode.output.height
and the audio status
encode.input.silent
. You can modify the settings by changing their value
either via a textbox or checkbox.
Note: You can’t write characters in a field that only contains numbers.
There are two buttons available at the bottom of the page:
- Reload settings reloads the settings (useful for reverting
- incorrect settings).
- Save Settings saves changes to the settings made in this
- window.
See The Genvid Settings for more information about each setting.