Documentation

Cloud Code Client API

Version: v1

Cloud Code Client API

Version: v1

Cloud Code

Overview

This is the API specification for the Unity Cloud Code service that enables game developers to run custom server-side code for their games.

Limits

The combined size of the
POST
request body cannot exceed 1 MB.
The combined size of the response body cannot exceed 2 MiB.
The API has rate limiting in place. Request are limited on a per-player basis to 600 requests per minute which would allow for a sustained 10 requests per second.
The API responds with a
429
HTTP status code if the rate limit is exceeded.
It will also respond with a
Retry-After
header to be used in conjunction with a client's retry logic. The value is the number of seconds until a request for the given player will be accepted.

Modules

You can deploy a Cloud Code module with the UGS CLI by using the deploy command, or by using the Cloud Code admin APIs. Cloud Code modules are C# projects built either with .NET Core or .NET Framework.
A Cloud Code module can have one or more Cloud Code functions, which are defined with the attribute
CloudCodeFunction
. For example, the following code represents a Cloud Code module named
HelloWorld
with a function named
SayHello
.
SayHello
accepts a single string parameter called
name
.
public class HelloWorld{ [CloudCodeFunction("SayHello")] public string SayHello(string name) { return $"Hello, {name}!"; }}

Scripts

You can create a Cloud Code script in the UGS dashboard, or by using the Cloud Code admin APIs.

Useful Links

Download OpenAPI specification:

Run script


Run a Cloud Code script for a project.
Authorizations
Use any one of the following options.
Client
HTTP: Client
HTTP Authorization Scheme: bearer
or
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Run script"

projectId

string
required
ID of the project.
example: 8bdacc33-6eef-4577-beb0-633c86259f5b

scriptId

string
required
Name of the script.
minLength: 1maxLength: 50pattern: ^[a-zA-Z0-9-_]+$

Request body for "Run script"

Media Type:
application/json

params

object
required
Object containing key-value pairs that map on to the parameter definitions for the script. Parameters are required according to the definition.

HTTP response status codes for "Run script":

Code samples for "Run script":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "params": {}}' \ "https://cloud-code.services.api.unity.com/v1/projects/{projectId}/scripts/{scriptId}"

Response example

{ "output": { "playerInfo": { "playerID": "TestUser", "userName": "TestUserName", "displayName": "Name", "email": "test@test.com", "country": null, "deviceType": null, "platform": "IOS", "dateCreated": "string" } }}

Run module function


Run a Cloud Code function from a module for a project.
Authorizations
Use any one of the following options.
Client
HTTP: Client
HTTP Authorization Scheme: bearer
or
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Run module function"

projectId

string
required
ID of the project.
example: 8bdacc33-6eef-4577-beb0-633c86259f5b

moduleId

string
required
Name of the Cloud Code module.
minLength: 1maxLength: 50pattern: ^[a-zA-Z0-9_]*$

functionId

string
required
Name of the function to invoke from the given module.
minLength: 1

Request body for "Run module function"

Media Type:
application/json

params

object
required
Object containing key-value pairs that map on to the parameter definitions for the given function of a module. Parameters are required according to the arguments defined in the function signature.

scope

object
The scope to run the module function in. Required when the function belongs to a scoped class, and must match that class's scope type. State kept by a scoped class is stored per scope, so calls with the same
type
and
id
share state.

type

string
required
The type of scope to run the module function in.
enum: "Player", "MultiplayerSession"

id

string
required
The ID of the scope. For
Player
, this is the player ID. For
MultiplayerSession
, this is the multiplayer session ID.
minLength: 1
example: YL9Ia3mKqq0s620EsWhcc3PW2U3D

HTTP response status codes for "Run module function":

Code samples for "Run module function":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "params": {}, "scope": { "type": "Player", "id": "YL9Ia3mKqq0s620EsWhcc3PW2U3D" }}' \ "https://cloud-code.services.api.unity.com/v1/projects/{projectId}/modules/{moduleId}/{functionId}"

Response example

{ "output": true}

Create a player subscription token


Create a subscription token for player messages.
Authorizations
Use any one of the following options.
Client
HTTP: Client
HTTP Authorization Scheme: bearer
or
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Create a player subscription token"

projectId

string
required
ID of the project.
example: 8bdacc33-6eef-4577-beb0-633c86259f5b

HTTP response status codes for "Create a player subscription token":

Code samples for "Create a player subscription token":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-code.services.api.unity.com/v1/projects/{projectId}/subscriptions/tokens/player"

Response example

{ "channel": "$cloud-code!!!player-YL9Ia3mKqq0s620EsWhcc3PW2U3D!!!fc1099a0-a0af-44fe-9c0c-b4b068a090cc!!!b90c4336-189e-494f-82e6-ca4c774cbaec", "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsb3VkLWNvZGU6YWY2ZjlmMzItMGEwMy00MjM5LWI4MTQtOWZhZGZmYmU1NjA5IiwidHlwIjoiSldUIn0.eyJlbnZpcm9ubWVudE..."}

Create a project subscription token


Create a subscription token for project messages.
Authorizations
Use any one of the following options.
Client
HTTP: Client
HTTP Authorization Scheme: bearer
or
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Create a project subscription token"

projectId

string
required
ID of the project.
example: 8bdacc33-6eef-4577-beb0-633c86259f5b

HTTP response status codes for "Create a project subscription token":

Code samples for "Create a project subscription token":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-code.services.api.unity.com/v1/projects/{projectId}/subscriptions/tokens/project"

Response example

{ "channel": "$cloud-code!!!project!!!fc1099a0-a0af-44fe-9c0c-b4b068a090cc!!!b90c4336-189e-494f-82e6-ca4c774cbaec", "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsb3VkLWNvZGU6YWY2ZjlmMzItMGEwMy00MjM5LWI4MTQtOWZhZGZmYmU1NjA5IiwidHlwIjoiSldUIn0.eyJlbnZpcm9ubWVudE..."}

Ready invokers


Run a warm-up operation to ready the invokers for the project so the first module call is not delayed by provisioning.
Authorizations
Use any one of the following options.
Client
HTTP: Client
HTTP Authorization Scheme: bearer
or
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Ready invokers"

projectId

string
required
ID of the project.
example: 8bdacc33-6eef-4577-beb0-633c86259f5b

HTTP response status codes for "Ready invokers":

Code samples for "Ready invokers":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-code.services.api.unity.com/v1/projects/{projectId}/warm"

Response example

{ "$ref": "#/components/examples/GatewayUnauthorizedErrorResponse"}