Server-Side Cloud Script - Execute Entity Cloud Script

Cloud Script is one of PlayFab's most versatile features. It allows client code to request execution of any kind of custom server-side functionality you can implement, and it can be used in conjunction with virtually anything.

POST https://titleId.playfabapi.com/CloudScript/ExecuteEntityCloudScript

Request Header

Name Required Type Description
X-EntityToken True

string

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Request Body

Name Required Type Description
FunctionName True

string

The name of the CloudScript function to execute

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

Entity

EntityKey

The optional entity to perform this action on. Defaults to the currently logged in entity.

FunctionParameter

object

Object that is passed in to the function as the first argument

GeneratePlayStreamEvent

boolean

Generate a 'entity_executed_cloudscript' PlayStream event containing the results of the function execution and other contextual information. This event will show up in the PlayStream debugger console for the player in Game Manager.

RevisionSelection

CloudScriptRevisionOption

Option for which revision of the CloudScript to execute. 'Latest' executes the most recently created revision, 'Live' executes the current live, published revision, and 'Specific' executes the specified revision. The default value is 'Specific', if the SpecificRevision parameter is specified, otherwise it is 'Live'.

SpecificRevision

number

The specific revision to execute, when RevisionSelection is set to 'Specific'

Responses

Name Type Description
200 OK

ExecuteCloudScriptResult

400 Bad Request

ApiErrorWrapper

This is the outer wrapper for all responses with errors

Security

X-EntityToken

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Type: apiKey
In: header

Definitions

Name Description
ApiErrorWrapper

The basic wrapper around every failed API response

CloudScriptRevisionOption
EntityKey

Combined entity type and ID structure which uniquely identifies a single entity.

ExecuteCloudScriptResult
ExecuteEntityCloudScriptRequest

Executes CloudScript with the entity profile that is defined in the request.

LogStatement
ScriptExecutionError

ApiErrorWrapper

The basic wrapper around every failed API response

Name Type Description
code

integer

Numerical HTTP code

error

string

Playfab error code

errorCode

integer

Numerical PlayFab error code

errorDetails

object

Detailed description of individual issues with the request object

errorMessage

string

Description for the PlayFab errorCode

status

string

String HTTP code

CloudScriptRevisionOption

Name Type Description
Latest

string

Live

string

Specific

string

EntityKey

Combined entity type and ID structure which uniquely identifies a single entity.

Name Type Description
Id

string

Unique ID of the entity.

Type

string

Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types

ExecuteCloudScriptResult

Name Type Description
APIRequestsIssued

number

Number of PlayFab API requests issued by the CloudScript function

Error

ScriptExecutionError

Information about the error, if any, that occurred during execution

ExecutionTimeSeconds

number

FunctionName

string

The name of the function that executed

FunctionResult

object

The object returned from the CloudScript function, if any

FunctionResultTooLarge

boolean

Flag indicating if the FunctionResult was too large and was subsequently dropped from this event. This only occurs if the total event size is larger than 350KB.

HttpRequestsIssued

number

Number of external HTTP requests issued by the CloudScript function

Logs

LogStatement[]

Entries logged during the function execution. These include both entries logged in the function code using log.info() and log.error() and error entries for API and HTTP request failures.

LogsTooLarge

boolean

Flag indicating if the logs were too large and were subsequently dropped from this event. This only occurs if the total event size is larger than 350KB after the FunctionResult was removed.

MemoryConsumedBytes

number

ProcessorTimeSeconds

number

Processor time consumed while executing the function. This does not include time spent waiting on API calls or HTTP requests.

Revision

number

The revision of the CloudScript that executed

ExecuteEntityCloudScriptRequest

Executes CloudScript with the entity profile that is defined in the request.

Name Type Description
CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

Entity

EntityKey

The optional entity to perform this action on. Defaults to the currently logged in entity.

FunctionName

string

The name of the CloudScript function to execute

FunctionParameter

object

Object that is passed in to the function as the first argument

GeneratePlayStreamEvent

boolean

Generate a 'entity_executed_cloudscript' PlayStream event containing the results of the function execution and other contextual information. This event will show up in the PlayStream debugger console for the player in Game Manager.

RevisionSelection

CloudScriptRevisionOption

Option for which revision of the CloudScript to execute. 'Latest' executes the most recently created revision, 'Live' executes the current live, published revision, and 'Specific' executes the specified revision. The default value is 'Specific', if the SpecificRevision parameter is specified, otherwise it is 'Live'.

SpecificRevision

number

The specific revision to execute, when RevisionSelection is set to 'Specific'

LogStatement

Name Type Description
Data

object

Optional object accompanying the message as contextual information

Level

string

'Debug', 'Info', or 'Error'

Message

string

ScriptExecutionError

Name Type Description
Error

string

Error code, such as CloudScriptNotFound, JavascriptException, CloudScriptFunctionArgumentSizeExceeded, CloudScriptAPIRequestCountExceeded, CloudScriptAPIRequestError, or CloudScriptHTTPRequestError

Message

string

Details about the error

StackTrace

string

Point during the execution of the script at which the error occurred, if any

Error Codes

Name Code
CloudScriptAPIRequestCountExceeded 1209
CloudScriptAPIRequestError 1210
CloudScriptFunctionArgumentSizeExceeded 1208
CloudScriptHTTPRequestError 1211
CloudScriptNotFound 1136
InvalidEntityType 1373
JavascriptException 1099
TitleDeleted 1347