Streaming sessions API for Amazon Nimble Studio

Introduction

Amazon Nimble Studio empowers creative studios to produce visual effects, animation, and interactive content entirely in the cloud, from storyboard sketch to final deliverable. Studios can rapidly onboard and collaborate with artists globally and create content faster using access to virtual workstations, high-speed storage, and scalable rendering across Amazon Web Services’ (AWS) global infrastructure.

To provide studio administrators with the ability to better manage streaming sessions for all users, we introduced the Amazon Nimble Studio API, which lets streaming sessions launch programmatically. The Amazon Nimble Studio API opens several new possibilities for administrators or users to manage sessions. For example, a user can launch sessions before logging in to the instance, reducing wait time while an instance starts up. Users can also launch sessions from third-party applications like Autodesk ShotGrid.

Using Amazon Nimble Studio streaming sessions

Streaming sessions provide customers with a secure way to deliver remote desktops to any device over varying network conditions. Amazon Nimble Studio uses NICE DCV, a high-performance remote display protocol, to stream workstations to customers. These sessions run in environments preconfigured by launch profiles, which provide administrators the ability to manage resource access and share only the necessary studio resources with artists so that they can accomplish their tasks. These include the operating systems, software installations, file system access, render farm access, and security controls. After administrators create launch profiles and share these with artists, artists can launch streaming sessions with these preconfigured environments.

Administrators need a view into various aspects of running or previously terminated sessions across their studio. Properties such as active users, launch profiles, session status, instance types, and runtime can serve as very important information and metrics.

Managing streaming sessions using the Amazon Nimble Studio API

Amazon Nimble Studio provides an API through AWS Command Line Interface (AWS CLI) commands, as well as several programming languages through software development kits (SDKs). Specific Amazon Nimble Studio APIs reference material is located here. Using these APIs, studio administrators can accomplish many tasks, such as managing users; adding, removing, or updating components; or adding or removing launch profiles. With the latest API change, administrators can now manage streaming sessions as well.

The following shows examples of API calls (in the Python language) related to streaming sessions.

list_studios

This API call lets us retrieve all Amazon Nimble Studios deployed in the current account. Currently, this is limited to one active studio. The response object is an array of studio structures. We can target this because there can only be one.

import boto3
client = boto3.client('nimble')

response = client.list_studios()
try:
studioId = response['studios'][0]['studioId']
except IndexError:
raise ValueError("No Nimble Studio found!")

list_launch_profiles

This API call lets us retrieve all Amazon Nimble Studio launch profiles for a given studio. The response object has an array of LaunchProfile objects, which we can parse to get a LaunchProfileId to use later.

import boto3
client = boto3.client('nimble')

response = client.list_launch_profiles(
studioId='string' # use the studioId from the list_studios call
)
search_string = "Workstation-Default"
try:
launch_profile_id = [lp['launchProfileId'] for lp in response['launchProfiles'] if lp['name'] == search_string][0]
except IndexError:
raise ValueError("No Launch Profile with the Name: %s found" % search_string )

list_streaming_images

This API call lets us retrieve all Amazon Nimble Studio Amazon Machine Images (AMIs) for a given studio. (AMIs provide the information required to launch an instance.) The response object has an array of streaming images objects, which we can parse to get a StreamingImageID to use later.

import boto3
client = boto3.client('nimble')

response = client.list_streaming_images(
studioId='string' # use the studioId from the list_studios call
)
search_string = "NimbleStudioWindowsStreamImage"
try:
image_id = [ami['streamingImageId'] for ami in response['streamingImages'] if ami['name'] == search_string][0]
except IndexError:
raise ValueError("No AMI with the Name: %s found" % search_string )

Determine the owner of a session

To determine the ownerId based on a username, we used the AWS SSO Identity Store API and the AWS Directory Services API together.

(These APIs are part of AWS Single Sign-On (AWS SSO), which lets you centrally manage access to multiple AWS accounts or applications, and AWS Directory Service for Microsoft Active Directory (AWS Managed Microsoft AD), which lets directory-aware workloads and AWS resources use managed Active Directory (AD) on AWS.)

import boto3
is_client = boto3.client('identitystore')
ds_client = boto3.client('ds')

# retrieve the directory id and domain for our active directory
response = ds_client.describe_directories()
directory_id = response['DirectoryDescriptions'][0]['DirectoryId']
domain = response['DirectoryDescriptions'][0]['Name']

# retrieve the user id from the identity store
search_string = "admin" # replace with the real user name
response = is_client.list_users(
IdentityStoreId=directory_id,
Filters=[
{
'AttributePath': 'UserName',
'AttributeValue': f'{search_string}@{domain}'
},
]
)

try:
user_id = response['Users'][0]['UserId']
except IndexError:
raise ValueError("User with name: %s was not found" % search_string )

list_streaming_sessions

import boto3
client = boto3.client('nimble')

response = client.list_streaming_sessions(
ownedBy='string',# use the userId we retrieved in the section about determining the owner of a session
studioId='string' # use the studioId from the list_studios call
)

The new parameter ownedBy lets administrators target the call to specific users in the studio. This is optional and can be omitted to list all streaming sessions. The response structure includes entry sessions, which holds all sessions and their attributes.

create_streaming_session

import boto3
client = boto3.client('nimble')
response = client.create_streaming_session(
ec2InstanceType='g4dn.xlarge'|'g4dn.2xlarge'|'g4dn.4xlarge'|'g4dn.8xlarge'|'g4dn.12xlarge'|'g4dn.16xlarge',
launchProfileId='string', # use the launchProfileId from the list_launch_profiles call
ownedBy='string', # use the userId we retrieved in the section about determining the owner of a session
streamingImageId='string', # use the imageId from the list_streaming_images call
studioId='string', # use the studioId from the list_studios call
)

Similar to the list_streaming_sessions, we have the ownedBy parameter for the call as well, which lets us create a session for a particular user. We can see some parameters for which we first need to get identifiers (IDs).

Usage scenarios

Here are a few scenarios where the new ability to control streaming sessions in the Amazon Nimble Studio API comes in handy.

Scenario 1: Launching sessions on behalf of users before they are needed

This lets users log into the sessions right away and helps users avoid waiting for the sessions to spin up before they can start working.

An example implementation could use a simple table in Amazon DynamoDB (a fully managed NoSQL database) coupled with a Lambda function through AWS Lambda (a serverless, event-driven compute service). The Lambda function periodically checks the table and determines if a machine needs to be prelaunched to be ready for the users.

Scenario 2: Launching sessions from within other applications or production tools

An integration into Slack or Autodesk ShotGrid provides studio users a way to launch sessions directly from within these tools, bypassing the need to log into the Amazon Nimble Studio portal directly. For example, they could launch sessions on their way into the office or while they grab their morning coffee.

Scenario 3: Building a fully custom streaming sessions graphical user interface tool

This could be accomplished as a Qt app, for example, to build a fully featured Amazon Nimble Studio streaming sessions tool for administrators. Tools like these can be very important for larger organizations that need to manage large numbers of users and sessions.

Conclusion

In this blog post, we detailed new streaming sessions API calls and how to use them. We explained Amazon Nimble Studio sessions and the different environment configurations through launch profiles. In several examples, we showed how to accomplish tasks using the API, including starting streaming sessions on behalf of other users.

Using these API calls combined, studio administrators have powerful tools to manage sessions programmatically.