th triggers: cron and queue triggers

About

A trigger sends an HTTP POST to a path of a Container or function without a visitor. It works for internal-only and token-protected services too, and wakes a service that scaled to zero.

Cron (--schedule): five fields, minute hour day month weekday, or @hourly, @daily, @weekly, @monthly, in --time-zone (default Asia/Bangkok). The body is --body, or JSON naming the run.
Queue (--queue): every message of a queue in the same Project, --concurrency at once (1–10), as JSON {"trigger","queue","message":{"id","body","attributes","sentAt","receives"}}. A 2xx answer deletes the message; anything else hands it out again after 10 seconds, doubling up to 10 minutes, and past the queue’s max receives it moves to its dead-letter queue.

Trigger requests carry X-TH-Trigger, X-TH-Trigger-Id and X-TH-Trigger-Kind headers (queue ones also X-TH-Trigger-Queue, X-TH-Trigger-Message-Id and X-TH-Trigger-Receives). The public address removes these headers from visitors’ requests, so your app can trust them. A service has at most 20 triggers.

How-to guides

Run a task every night

Shell

th triggers create nightly --service api --schedule "0 3 * * *" --path /tasks/cleanup
th triggers run nightly --service api
th triggers list --service api

On Git Bash, start the path with // or set MSYS_NO_PATHCONV=1: Git Bash turns arguments that start with / into Windows paths.

Process a queue

Shell

th queue create jobs --max-receives 5 --dead-letter jobs-dlq
th triggers create worker --service api --queue jobs --concurrency 5 --path /jobs
th queue send jobs '{"order": 1042}'

Commands

Command	Description
`th triggers create`	Creates a trigger that POSTs to the service without a visitor.
`th triggers list`	Lists the triggers of a Container or function.
`th triggers update`	Changes a trigger; flags left out keep their value.
`th triggers run`	Fires a cron trigger once now, outside its schedule.
`th triggers pause`	Paused a trigger.
`th triggers resume`	Resumed a trigger.
`th triggers delete`	Deletes a trigger.

`th triggers create`

Creates a trigger that POSTs to the service without a visitor.

Syntax

Shell

th triggers create NAME --service NAME (--schedule CRON | --queue QUEUE) [flags]

--schedule "0 3 * * *"   on a cron schedule (minute hour day month weekday)
--queue jobs             for every message of a Queue of the same Project;
                         a 2xx answer deletes the message, anything else
                         hands it out again later (and past the queue's
                         max receives, to its dead-letter queue)

Examples

Shell

th triggers create nightly --service api --schedule "0 3 * * *" --path /tasks/nightly

Shell

th triggers create worker --service api --queue jobs --concurrency 5 --path /jobs

Positional arguments

Name	Description
`NAME`Required	The trigger’s name: lowercase letters, digits and -, unique on its service.
`CRON`Required

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function the trigger calls
`--schedule`	string		Cron schedule, e.g. "/15 * * *" or @daily
`--time-zone`	string	`Asia/Bangkok`	Time zone of the schedule
`--body`	string	`JSON naming the run`	Request body of a cron run
`--queue`	string		Queue whose messages call the service
`--concurrency`	number	`1`	Queue messages handed over at once, 1-10
`--path`	string	`/`	Path the platform POSTs to

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th triggers list`

Lists the triggers of a Container or function.

Syntax

Shell

th triggers list --service NAME

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th triggers update`

Changes a trigger; flags left out keep their value.

Syntax

Shell

th triggers update NAME --service NAME [--schedule CRON] [--time-zone TZ] [--body BODY]
    [--queue QUEUE] [--concurrency N] [--path PATH] [--rename NEW]

A trigger's kind does not change.

Positional arguments

Name	Description
`NAME`Required	The trigger’s name: lowercase letters, digits and -, unique on its service.

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function the trigger calls
`--schedule`	string		Cron schedule, e.g. "/15 * * *" or @daily
`--time-zone`	string	`Asia/Bangkok`	Time zone of the schedule
`--body`	string	`JSON naming the run`	Request body of a cron run
`--queue`	string		Queue whose messages call the service
`--concurrency`	number	`1`	Queue messages handed over at once, 1-10
`--path`	string	`/`	Path the platform POSTs to
`--rename`	string		New name

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th triggers run`

Fires a cron trigger once now, outside its schedule.

Syntax

Shell

th triggers run NAME --service NAME

See the result with th triggers list.

Positional arguments

Name	Description
`NAME`Required	The trigger’s name: lowercase letters, digits and -, unique on its service.

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th triggers pause`

Paused a trigger.

Syntax

Shell

th triggers pause NAME --service NAME

Positional arguments

Name	Description
`NAME`Required	The trigger’s name: lowercase letters, digits and -, unique on its service.

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th triggers resume`

Resumed a trigger.

Syntax

Shell

th triggers resume NAME --service NAME

Positional arguments

Name	Description
`NAME`Required	The trigger’s name: lowercase letters, digits and -, unique on its service.

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th triggers delete`

Deletes a trigger.

Syntax

Shell

th triggers delete NAME --service NAME [--quiet]

--quiet skips the prompt.

Positional arguments

Name	Description
`NAME`Required	The trigger’s name: lowercase letters, digits and -, unique on its service.

Parameters

Name	Type	Default	Description
`--service`Required	string		Container or function

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

Help centre: the th command line