Allocations Payload#

The Allocations Payload feature allows you to send any file as a payload with a server allocation request, which provides a configurable way to configure games on a per match basis. After the payload is uploaded through the ProcessAllocation V1 endpoint, you can retrieve it from the game process. After an allocation ends, the payload associated with that allocation is no longer available. Refer to Payload lifecycle.

Limitations#

The Allocations Payload feature has the following limitations:

• Payloads can't exceed 30 KB. The endpoint rejects allocations with a payload larger than the limit size with a status of 400.
• You can include a payload as part of an allocation within the Multiplay ProcessAllocation V1 endpoint.
• You can remove payloads with the ProcessDeallocation V1 endpoint.

Payload lifecycle#

Payloads are temporary, session-based data tied to a specific allocation. After the allocation that a payload is linked to is deallocated, the payload is no longer available.

Payloads are retrievable until one of the following conditions is met:

• The game server is deallocated via the deallocation endpoint. When an allocation’s lifecycle is complete, Game Server Hosting clears out any data related to the allocation UUID.
• The payload reaches its time to live (TTL). The allocation timeout value sets the payload TTL in the Fleet scaling settings, which is one hour by default if not set at the fleet level.

Sending the payload#

To send a payload value, include the payload string value in the request body, and the payload is available throughout the lifecycle of the allocation.

https://multiplay.services.api.unity.com

Example request#

curl --location --request POST 'https://multiplay.services.api.unity.com/v1/allocations/projects/<projectid>/environments/<environmentid>/fleets/<fleetid>/allocations' \
--header 'Authorization: Basic YOUR_AUTH_CREDENTIALS' \
--header 'Content-Type: application/json' \
--data-raw '{
  allocationId: "<allocation_uuid>"",
  buildConfigurationId: <build_config_id>,
  regionId: "<region_id>"",
  payload: "this can be anything"
}'

Example response#

{
  "allocationId": "<allocation_uuid>",
  "href": "string"
}

Retrieving the payload#

After the allocation request is complete, you can access the payload from the game server. Send a request to the payload proxy, which is available locally on the game server machine, to retrieve the payload file from the game server. The payload proxy is service accessible at port 8086 and sits alongside the game server. It retrieves payloads uploaded through the allocation endpoint.

Example request#

curl -X GET http://localhost:8086/payload/<allocation_uuid>

Example response#

HTTP/1.1 200 OK
Date: Mon, 26 Jul 2021 17:00:33 GMT
Content-Length: 23
Content-Type: text/plain; charset=utf-8
This can be anything.