Documentation

Cloud Save Files Client API

Cloud Save Files Client API

Cloud Save Files

Introduction

This is the API specification for the Unity Cloud Save service that allows player or custom non-player state to be accessed and persisted from a game client. The Player State API allows data to be stored against a specific player ID. Access using client authentication is limited to the specified player for both data reads and writes. The Game State API allows data to be stored against a custom ID provided by the user. All players are able to read the data from the custom ID using client authentication, but write operations are limited to Service Account authentication. To use this API, you must first enable it through the Unity Gaming Services dashboard.

General Information

Cloud Save Files is for storing data files (binary, JSON, text, CSV, etc.) against keys. The maximum size for player data is 1 GB across all keys for that player. A player can have data in a single file that is up to 1 GB in size, or use many files that equal to less than 1 GB in total size. Limits:
  • Maximum 255 characters per file name
  • Maximum 200 files per player
  • Maximum 1 GB in size per player across all files

Rate Limits

The API has rate limiting in place. The endpoints are limited to 600 requests per minute on a per-player basis. The API responds with a 
429
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.
Download OpenAPI specification:

List Player Files

Retrieves a list of names of all the files currently saved in storage for a player along with size (in bytes), last date modified and current WriteLock. Ordered alphabetically in page sizes of 20.
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 "List Player Files"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "List Player Files"

after

string
The key after which to retrieve the next page of files.

HTTP response status codes for "List Player Files":

Code samples for "List Player Files":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items"

Response example

{ "results": [ { "key": "save-slot-1.dat", "writeLock": "12345678901234567890", "modified": { "date": "2020-04-01T13:07:23Z" }, "created": { "date": "2020-04-01T13:07:23Z" }, "contentType": "text/plain", "size": 2048 } ], "links": { "next": "string" }}

Get Player File Download URL

Generates a signed URL that will allow the client to download the requested player file for a limited period of time. If successful, an object will be returned containing all necessary information to perform the download.
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 "Get Player File Download URL"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

HTTP response status codes for "Get Player File Download URL":

Code samples for "Get Player File Download URL":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}"

Response example

{ "signedUrl": "string", "httpMethod": "string", "requiredHeaders": {}}

Get Player File upload URL

Initiates the player file upload process and returns a URL to which the actual file contents can be uploaded. The type, length and MD5 hash of the file have to be provided up-front. If successful, an object will be returned containing all necessary information to perform the upload.
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 "Get Player File upload URL"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

Request body for "Get Player File upload URL"

Media Type:
application/json

contentType

string
required
The MIME type of the file that will be uploaded

contentLength

integer
required
The content length in bytes of the file that will be uploaded

contentMd5

string
required
The base64 encoded MD5 checksum of the file contents that will be uploaded

writeLock

string
example: 12345678901234567890
Enforces conflict checking when updating an existing file. This field should be omitted when creating a new file. When updating an existing file, omitting this field ignores write conflicts. When present, an error response will be returned if the writeLock in the request does not match the stored writeLock. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Get Player File upload URL":

Code samples for "Get Player File upload URL":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "contentType": "string", "contentLength": 0, "contentMd5": "string", "writeLock": "12345678901234567890"}' \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}"

Response example

{ "signedUrl": "string", "httpMethod": "string", "requiredHeaders": {}}

Delete Player File

Deletes the specified player file. If a WriteLock is provided, the file will only be deleted if it matches the stored WriteLock.
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 "Delete Player File"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

Query parameters for "Delete Player File"

writeLock

string
Enforces conflict checking when deleting an existing file. Omitting this field ignores write conflicts. When present, an error response will be returned if the writeLock in the request does not match the stored writeLock.

HTTP response status codes for "Delete Player File":

Code samples for "Delete Player File":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Player File Metadata

Retrieves the metadata (size, date last modified and created, key, content type, and current WriteLock) of a single player file.
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 "Get Player File Metadata"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

HTTP response status codes for "Get Player File Metadata":

Code samples for "Get Player File Metadata":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}/metadata"

Response example

{ "key": "save-slot-1.dat", "writeLock": "12345678901234567890", "modified": { "date": "2020-04-01T13:07:23Z" }, "created": { "date": "2020-04-01T13:07:23Z" }, "contentType": "text/plain", "size": 2048}