기술 자료

Scheduler Admin API v1

버전 v1

Scheduler Admin API v1

버전 v1

Scheduler Admin API

Introduction

This is the admin client API specification for the Unity Scheduler service. The Scheduler service is responsible for scheduling events to be sent to the Triggers service.

Rate Limits

The API has rate limiting in place. Request are limited on a per-user basis to 600 requests per minute which would allow for a sustained 10 requests per second. The List endpoint is limited to 120 requests per minute, which allows for sustained 2 requests per second. 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 Scheduler Configs

Get list of schedules for the given project and environment
Authorizations
ServiceAccount (scheduler.configs.list)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: scheduler.configs.list

Path parameters for "{title}"

projectId

string
필수
The project's Project ID

environmentId

string
필수
The Environment ID of a project

Header parameters for "{title}"

unity-live-release-name

string
Live Release name to scope the request to. Validated by the gateway's Live Releases filter and resolved to unity-live-release-id. Create assigns the schedule to the release; list, get and delete see only that release's schedules. Deleting a schedule that belongs to a release without this header returns 409.

Query parameters for "{title}"

limit

integer
기본: 1000
The number of schedules to display per page

after

string | null
기본: null
A token to get the next page

eventName

string
Filter by the event a schedule emits. Not unique — several schedules may share an eventName — so this can return many schedules. Matches the 
<eventName>
in a trigger's 
com.unity.services.scheduler.<eventName>.v<n>
subscription.

payloadVersion

integer
Filter by payload version. Typically combined with 
eventName
to match a trigger's pinned 
.v<n>
.

state

string
Which lifecycle states to return. 
active
(default) returns schedules that have not passed their end date; 
expired
returns only those past it; 
all
returns both. Expired schedules are hidden unless this is set to 
expired
or 
all
.

type

string
Filter by schedule type. 
recurring
returns cron schedules; 
one-time
returns schedules that fire once; 
interval
returns fixed-period schedules. Omit to return all.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/scheduler/v1/projects/{projectId}/environments/{environmentId}/configs"

Response example

{ "after": "eyJTZWFyY2hBZnRlciI6WzAsMSwyMl0sIlNjcm9sbElEIjoiIiwiUG9pbnRJblRpbWVJRCI6IjAwMCJ9=", "configs": [ { "eventName": "example-event", "id": "00000000-0000-0000-0000-000000000001", "name": "Example Recurring", "payload": "{}", "payloadVersion": 1, "schedule": "0 * * * *", "status": "active", "type": "recurring" }, { "eventName": "example-event", "id": "00000000-0000-0000-0000-000000000002", "name": "Example One Time", "payload": "{}", "payloadVersion": 1, "schedule": "2023-10-02T15:00:00Z", "status": "active", "type": "one-time" } ]}

Create Schedule Config

Add schedule to project environment
Authorizations
ServiceAccount (scheduler.configs.create)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: scheduler.configs.create

Path parameters for "{title}"

projectId

string
필수
The project's Project ID

environmentId

string
필수
The Environment ID of a project

Header parameters for "{title}"

unity-live-release-name

string
Live Release name to scope the request to. Validated by the gateway's Live Releases filter and resolved to unity-live-release-id. Create assigns the schedule to the release; list, get and delete see only that release's schedules. Deleting a schedule that belongs to a release without this header returns 409.

Request body for "{title}"

Media Type:
application/json

endAt

string
Optional RFC3339 timestamp. The schedule will not fire after this instant. Must be in the future, after startAt, and after the first fire.

eventName

string
필수
The schedule event name is passed through to the triggers service as part of the event type so that the trigger event is defined as 
com.unity.services.scheduler.{scheduleEventName}.v1
The triggers service uses this to identify incoming events and execute the configured action. For a trigger configuration to action an incoming event with type 
com.unity.services.scheduler.example-event.v1
, it would require a value of 
example-event
to be passed in here.

name

string
필수
The display name used to identify a schedule. This must be unique for currently scheduled events.

payload

string
Defines JSON event payload. Maximum size of 1kb.

payloadVersion

integer
필수
No description

schedule

string
필수
Defines when the planned event should occur.
If the schedule config has a type of 
one-time
this field must have a valid RFC3339 timestamp.
If the schedule config has a type of 
interval
this field must be a fixed period of the form 
<number><unit>
, where unit is one of 
m
(minutes), 
h
(hours), 
d
(days), or 
w
(weeks) — for example 
3d
(every 3 days) or 
2w
(every 2 weeks). The period must be at least 60 minutes (the same floor as recurring), so 
90m
is accepted but 
30m
is rejected. Unlike cron, an interval is a true fixed period that does not reset at month boundaries. When 
startAt
is set the cadence is anchored to it. Combined units (e.g. 
1d12h
) are not supported.
If the schedule config has a type of 
recurring
this field must have a valid cron expression as per below:

Field name

Allowed values

Allowed special characters

Minutes0-59* / , -
Hours0-23* / , -
Day of month1-31* / , -
Month1-12 or JAN-DEC* / , -
Day of week0-6 or SUN-SAT* / , -
Recurring and interval schedules have a minimum scheduled frequency of once per hour.

startAt

string
Optional RFC3339 timestamp. The schedule will not fire before this instant. When omitted, the schedule is eligible to fire immediately.

type

필수
Defines the type of schedule config. Supported schedule types:
  • recurring
  • one-time
  • interval
One of

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "endAt": "2024-01-01T00:00:00Z", "eventName": "string", "name": "string", "payload": "string", "payloadVersion": 0, "schedule": "string", "startAt": "2024-01-01T00:00:00Z", "type": "recurring"}' \ "https://services.api.unity.com/scheduler/v1/projects/{projectId}/environments/{environmentId}/configs"

Response example

{ "id": "string"}

Get Schedule Config

Retrieves the configuration for a specific schedule
Authorizations
ServiceAccount (scheduler.configs.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: scheduler.configs.get

Path parameters for "{title}"

projectId

string
필수
The project's Project ID

environmentId

string
필수
The Environment ID of a project

configId

string
필수
example: 00000000-0000-0000-0000-000000000000
ID of the scheduler config. List the scheduler configurations to retrieve IDs.

Header parameters for "{title}"

unity-live-release-name

string
Live Release name to scope the request to. Validated by the gateway's Live Releases filter and resolved to unity-live-release-id. Create assigns the schedule to the release; list, get and delete see only that release's schedules. Deleting a schedule that belongs to a release without this header returns 409.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/scheduler/v1/projects/{projectId}/environments/{environmentId}/configs/{configId}"

Response example

{ "eventName": "example-event", "id": "00000000-0000-0000-0000-000000000001", "name": "Example Recurring Event", "payload": "{}", "payloadVersion": 1, "schedule": "0 * * * *", "status": "active", "type": "recurring"}

Update Schedule Config Status

Activates or deactivates a schedule config. Deactivating pauses the schedule so it stops firing; activating resumes it. Fires that would have occurred while the schedule was deactivated are skipped and are not made up on activation. An 
expired
or one-time schedule cannot be changed (
409
). The request is idempotent: setting the current status succeeds.
One-time schedules cannot be deactivated and return 
409
. Deactivated schedules still count towards the schedule limit.
Authorizations
ServiceAccount (scheduler.configs.update)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: scheduler.configs.update

Path parameters for "{title}"

projectId

string
필수
The project's Project ID

environmentId

string
필수
The Environment ID of a project

configId

string
필수
example: 00000000-0000-0000-0000-000000000000
ID of the scheduler config. List the scheduler configurations to retrieve IDs.

Header parameters for "{title}"

unity-live-release-name

string
Live Release name to scope the request to. Validated by the gateway's Live Releases filter and resolved to unity-live-release-id. Create assigns the schedule to the release; list, get and delete see only that release's schedules. Deleting a schedule that belongs to a release without this header returns 409.

Request body for "{title}"

Media Type:
application/json

status

string
필수
The status to set. 
expired
is derived and cannot be set.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "status": "active"}' \ "https://services.api.unity.com/scheduler/v1/projects/{projectId}/environments/{environmentId}/configs/{configId}"

Response example

{ "eventName": "example-event", "id": "00000000-0000-0000-0000-000000000001", "name": "Example Recurring Event", "payload": "{}", "payloadVersion": 1, "schedule": "0 * * * *", "status": "inactive", "type": "recurring"}

Delete Schedule Config

Deletes the configuration for a specific schedule
Authorizations
ServiceAccount (scheduler.configs.delete)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: scheduler.configs.delete

Path parameters for "{title}"

projectId

string
필수
The project's Project ID

environmentId

string
필수
The Environment ID of a project

configId

string
필수
example: 00000000-0000-0000-0000-000000000000
ID of the scheduler config. List the scheduler configurations to retrieve IDs.

Header parameters for "{title}"

unity-live-release-name

string
Live Release name to scope the request to. Validated by the gateway's Live Releases filter and resolved to unity-live-release-id. Create assigns the schedule to the release; list, get and delete see only that release's schedules. Deleting a schedule that belongs to a release without this header returns 409.

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/scheduler/v1/projects/{projectId}/environments/{environmentId}/configs/{configId}"

Response example

{ "code": 55, "detail": "Failed to parse request body. Error: Unexpected end of JSON input", "status": 400, "title": "Bad Request", "type": "problems/basic"}

Delete Schedule Configs

Deletes multiple schedule configurations
Authorizations
ServiceAccount (scheduler.configs.delete)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: scheduler.configs.delete

Path parameters for "{title}"

projectId

string
필수
The project's Project ID

environmentId

string
필수
The Environment ID of a project

Header parameters for "{title}"

unity-live-release-name

string
Live Release name to scope the request to. Validated by the gateway's Live Releases filter and resolved to unity-live-release-id. Create assigns the schedule to the release; list, get and delete see only that release's schedules. Deleting a schedule that belongs to a release without this header returns 409.

Request body for "{title}"

Media Type:
application/json
Array Type:
[ "string"]

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '[ "string"]' \ "https://services.api.unity.com/scheduler/v1/projects/{projectId}/environments/{environmentId}/configs:batch-delete"

Response example

{ "errors": { "00000000-0000-0000-0000-000000000001": { "code": 55, "detail": "Bad request", "instance": null, "status": 400, "title": "Error", "type": "problems/basic" }, "00000000-0000-0000-0000-000000000002": { "code": 3, "detail": "Temporary Service Error", "instance": null, "status": 503, "title": "Error", "type": "problems/basic" } }}