Documentation

Support

Multiplay Clanforge

Open Clanforge

Multiplay Clanforge

Image version create

Documentation for Image version create
Read time 3 minutesLast updated 2 hours ago
Create a new image version for the image identified by the specified image difference 
<diffid>
. If the image difference analysis has no changes, it will create a full image instead of a partial image. It's best practice to create a full image every so often by setting the 
full
variable to 
1
to prevent your images from becoming excessively large, which can lead to slow deployment times when scaling into the cloud. Refer to image roll-up frequency. 
https://api.multiplay.co.uk/cfp/v1/imageversion/create
METHOD
GET

Request parameters

VARIABLE
DESCRIPTION
OPTIONAL
diffid
The 
<diffid>
 parameter accepts the ID of a completed image difference analysis.
No
restart
The 
<restart>
 parameter accepts a boolean value that specifies whether to restart all the game servers that use the updated game image after the update is complete.

If set to 
1
, Clanforge will stop all affected game servers during the installation process. After the installation is complete, Clanforge will restart all affected game servers.

If set to 
0
 or omitted, Clanforge won't stop the affected game servers during the installation. Instead, the game server restarts after it exits or if the profile changes on allocation.
No
accountserviceid
The 
<accountserviceid>
 is the account service ID (ASID) associated with the specified resource. The credentials in the request header must have access to the ASID to perform the request.
No
full
The 
<full>
 parameter is a boolean value.

If set to 
1
, Clanforge creates a full image install instead of a partial image install.

If omitted or set to 
0
, Clanforge creates a differential (partial) install.

You must set 
<full>
 to 
1
 if the difference analysis specified by 
<diffid>
 includes no differences.

If you try to create a full install when the previous install was a full install and the 
<diffid>
 includes no differences, the request will fail.
Yes
game_build
The 
<game\_build>
 parameter is an option parameter that accepts a string value that identifies the game's internal build. This was previously the 
game\_version
.

If given then on successful completion the 
<version>
 field of Clanforge Game Version value will be set to the specified value.
Yes
force
The 
<force>
 parameter is a boolean value that specifies whether to force the image version creation even if there are active allocations.

If set to 
1
, Clanforge will create the image version on all game servers, even if the game servers have active game sessions.

If set to 
0
 or omitted, Clanforge will only create the image version on game servers without active allocations.

By default, if there are active allocations when you make this request, it will fail. To bypass this behavior and force the image version creation, set 
force=1
.
Yes
install_at
The 
<install\_at>
 parameter is unix timestamp representing the time at which the job is expected to start.
Yes
disable_timeout
The 
<disable\_timeout>
 parameter is is used in conjunction with 
<disable\_percentage>
 in order to start failing machines earlier than the default 4 hour timeout.

This value is an integer value representing minutes.

Example: a value of 
5
 means the timeout will be 5 minutes
Yes
disable_percentage
The 
<disable\_percentage>
 parameter is is used in conjunction with 
<disable\_timeout>
 in order to start failing machines earlier than the default 4 hour timeout.

This value is a decimal value between 0.00 and 100.00.

Example: with a 
90.0
 disable_percentage and 
20
 disable_timeout. Once install success reaches 90% across all machines in the fleet, all machines not reporting install success after 20 minutes will timeout and get disabled.
Yes

Response fields

Field

Type

Description

Optional

imageversionid
integer
ID of the image
No
jobcreated
integer
Unix timestamp of when the job was created
No
joberror
string
Message indicating the job error
Yes
jobeta
integer
Unix timestamp representing the time at which the job is expected to complete
Yes
jobfailed
integer
Numeric flag indicating whether the job has failed
No
jobprogress
integer
Percentage between 0 and 100 indicating job progress
No
jobstart
string
Unix timestamp of when the job was started
Yes
jobstateid
integer
Job state ID indicating the state of the job
Yes
jobstatename
string
Name of the job state
No
jobupdated
integer
Unix timestamp of when the job was last updated
No
success
boolean
Flag indicating whether this request was a success
No

Example request

curl --location --request GET 'https://api.multiplay.co.uk/cfp/v1/imageversion/create?diffid=<diff_id>&restart=<restart>&accountserviceid=<accountserviceid>&install_at=<timestamp>&full=<full>&game_build=<game_build>' \
--header 'Authorization: Basic YOUR_AUTH_CREDENTIALS'

Example response

{
    "imageversionid": <imageversionid>,
    "jobcreated": <jobcreated>,
    "joberror": <joberror>,
    "jobeta": <jobeta>,
    "jobfailed": <jobfailed>,
    "jobprogress": <jobprogress>,
    "jobstart": <jobstart>,
    "jobstateid": <jobstateid>,
    "jobstatename": <jobstatename>,
    "jobupdated": <jobupdated>
}