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/ExecuteEntityCloudScriptRequest 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 |
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 |
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 | ||
| 400 Bad Request |
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 |
|---|---|
|
Api |
The basic wrapper around every failed API response |
|
Cloud |
|
|
Entity |
Combined entity type and ID structure which uniquely identifies a single entity. |
|
Execute |
|
|
Execute |
Executes CloudScript with the entity profile that is defined in the request. |
|
Log |
|
|
Script |
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 |
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 |
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 |
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 |
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 |