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

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

Cloud Code

Download OpenAPI specification:

Run script

Run a Cloud Code script for a project.

Authorizations

Client

HTTP: Client

HTTP Authorization Scheme: bearer

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

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

scriptId

string

required

Name of the script.

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":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid authentication token

Not found

Unprocessable entity. Returned code indicates one of: - Cannot run a script type - Invalid parameters for script - Script Timeout - Script Exception

Too many requests

Internal server error

Service unavailable

Gateway timeout

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

Client

HTTP: Client

HTTP Authorization Scheme: bearer

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

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

moduleId

string

required

Name of the Cloud Code module.

functionId

string

required

Name of the function to invoke from the given module.

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.

HTTP response status codes for "Run module function":

Bad request

Invalid authentication token

Not found

Unprocessable entity. Returned code indicates one of: - Cannot run a script type - Invalid parameters for script - Script Timeout - Script Exception

Too many requests

Internal server error

Service unavailable

Gateway timeout

Code samples for "Run module function":

Request example

Response example

{ "output": true}

Create a player subscription token

Create a subscription token for player messages.

Authorizations

Client

HTTP: Client

HTTP Authorization Scheme: bearer

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

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

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

Invalid authentication token

Too many requests

Internal server error

Service unavailable

Gateway timeout

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

Client

HTTP: Client

HTTP Authorization Scheme: bearer

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

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

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

Invalid authentication token

Too many requests

Internal server error

Service unavailable

Gateway timeout

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

Client

HTTP: Client

HTTP Authorization Scheme: bearer

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

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

HTTP response status codes for "Ready invokers":

Invalid authentication token

Too many requests

Internal server error

Service unavailable

Gateway timeout

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"}

Cloud Code

Overview

Limits

Modules

Scripts

Useful Links

Run script

Path parameters for "Run script"

projectId

scriptId

Request body for "Run script"

params

HTTP response status codes for "Run script":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid authentication token

404Not found

422Unprocessable entity. Returned code indicates one of: - Cannot run a script type - Invalid parameters for script - Script Timeout - Script Exception

429Too many requests

500Internal server error

503Service unavailable

504Gateway timeout

Code samples for "Run script":

Request example

Response example

POST/projects/{projectId}/scripts/{scriptId}

Run module function

Path parameters for "Run module function"

projectId

moduleId

functionId

Request body for "Run module function"

params

HTTP response status codes for "Run module function":

200OK

400Bad request

401Invalid authentication token

404Not found

422Unprocessable entity. Returned code indicates one of: - Cannot run a script type - Invalid parameters for script - Script Timeout - Script Exception

429Too many requests

500Internal server error

503Service unavailable

504Gateway timeout

Code samples for "Run module function":

Request example

Response example

POST/projects/{projectId}/modules/{moduleId}/{functionId}

Create a player subscription token

Path parameters for "Create a player subscription token"

projectId

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

200OK

401Invalid authentication token

429Too many requests

500Internal server error

503Service unavailable

504Gateway timeout

Code samples for "Create a player subscription token":

Request example

Response example

POST/projects/{projectId}/subscriptions/tokens/player

Create a project subscription token

Path parameters for "Create a project subscription token"

projectId

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

200OK

401Invalid authentication token

429Too many requests

500Internal server error

503Service unavailable

504Gateway timeout

Code samples for "Create a project subscription token":

Request example

Response example

POST/projects/{projectId}/subscriptions/tokens/project

Ready invokers

Path parameters for "Ready invokers"

projectId

HTTP response status codes for "Ready invokers":

200OK