mirror of
https://github.com/LukeHagar/plexphp.git
synced 2025-12-06 04:20:51 +00:00
292 lines
12 KiB
Markdown
292 lines
12 KiB
Markdown
# Butler
|
|
|
|
## Overview
|
|
|
|
Butler is the task manager of the Plex Media Server Ecosystem.
|
|
|
|
|
|
### Available Operations
|
|
|
|
* [getButlerTasks](#getbutlertasks) - Get Butler tasks
|
|
* [startAllTasks](#startalltasks) - Start all Butler tasks
|
|
* [stopAllTasks](#stopalltasks) - Stop all Butler tasks
|
|
* [startTask](#starttask) - Start a single Butler task
|
|
* [stopTask](#stoptask) - Stop a single Butler task
|
|
|
|
## getButlerTasks
|
|
|
|
Returns a list of butler tasks
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use LukeHagar\Plex_API;
|
|
use LukeHagar\Plex_API\Models\Components;
|
|
|
|
$security = new Components\Security(
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
);
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setClientID('gcgzw5rz2xovp84b4vha3a40')
|
|
->setClientName('Plex Web')
|
|
->setClientVersion('4.133.0')
|
|
->setClientPlatform('Chrome')
|
|
->setDeviceName('Linux')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
$response = $sdk->butler->getButlerTasks();
|
|
|
|
if ($response->object !== null) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
**[?Operations\GetButlerTasksResponse](../../Models/Operations/GetButlerTasksResponse.md)**
|
|
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
|
|
| Errors\GetButlerTasksBadRequest | 400 | application/json |
|
|
| Errors\GetButlerTasksUnauthorized | 401 | application/json |
|
|
| LukeHagar\Plex_API\Models\Errors.SDKException | 4xx-5xx | */* |
|
|
|
|
|
|
## startAllTasks
|
|
|
|
This endpoint will attempt to start all Butler tasks that are enabled in the settings. Butler tasks normally run automatically during a time window configured on the server's Settings page but can be manually started using this endpoint. Tasks will run with the following criteria:
|
|
1. Any tasks not scheduled to run on the current day will be skipped.
|
|
2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately.
|
|
3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window.
|
|
4. If we are outside the configured window, the task will start immediately.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use LukeHagar\Plex_API;
|
|
use LukeHagar\Plex_API\Models\Components;
|
|
|
|
$security = new Components\Security(
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
);
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setClientID('gcgzw5rz2xovp84b4vha3a40')
|
|
->setClientName('Plex Web')
|
|
->setClientVersion('4.133.0')
|
|
->setClientPlatform('Chrome')
|
|
->setDeviceName('Linux')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
$response = $sdk->butler->startAllTasks();
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
**[?Operations\StartAllTasksResponse](../../Models/Operations/StartAllTasksResponse.md)**
|
|
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
|
|
| Errors\StartAllTasksBadRequest | 400 | application/json |
|
|
| Errors\StartAllTasksUnauthorized | 401 | application/json |
|
|
| LukeHagar\Plex_API\Models\Errors.SDKException | 4xx-5xx | */* |
|
|
|
|
|
|
## stopAllTasks
|
|
|
|
This endpoint will stop all currently running tasks and remove any scheduled tasks from the queue.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use LukeHagar\Plex_API;
|
|
use LukeHagar\Plex_API\Models\Components;
|
|
|
|
$security = new Components\Security(
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
);
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setClientID('gcgzw5rz2xovp84b4vha3a40')
|
|
->setClientName('Plex Web')
|
|
->setClientVersion('4.133.0')
|
|
->setClientPlatform('Chrome')
|
|
->setDeviceName('Linux')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
$response = $sdk->butler->stopAllTasks();
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
**[?Operations\StopAllTasksResponse](../../Models/Operations/StopAllTasksResponse.md)**
|
|
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
|
|
| Errors\StopAllTasksBadRequest | 400 | application/json |
|
|
| Errors\StopAllTasksUnauthorized | 401 | application/json |
|
|
| LukeHagar\Plex_API\Models\Errors.SDKException | 4xx-5xx | */* |
|
|
|
|
|
|
## startTask
|
|
|
|
This endpoint will attempt to start a single Butler task that is enabled in the settings. Butler tasks normally run automatically during a time window configured on the server's Settings page but can be manually started using this endpoint. Tasks will run with the following criteria:
|
|
1. Any tasks not scheduled to run on the current day will be skipped.
|
|
2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately.
|
|
3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window.
|
|
4. If we are outside the configured window, the task will start immediately.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use LukeHagar\Plex_API;
|
|
use LukeHagar\Plex_API\Models\Components;
|
|
use LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security(
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
);
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setClientID('gcgzw5rz2xovp84b4vha3a40')
|
|
->setClientName('Plex Web')
|
|
->setClientVersion('4.133.0')
|
|
->setClientPlatform('Chrome')
|
|
->setDeviceName('Linux')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
$response = $sdk->butler->startTask(Operations\TaskName::CleanOldBundles);
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ---------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
|
|
| `taskName` | [Operations\TaskName](../../Models/Operations/TaskName.md) | :heavy_check_mark: | the name of the task to be started. |
|
|
|
|
### Response
|
|
|
|
**[?Operations\StartTaskResponse](../../Models/Operations/StartTaskResponse.md)**
|
|
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
|
|
| Errors\StartTaskBadRequest | 400 | application/json |
|
|
| Errors\StartTaskUnauthorized | 401 | application/json |
|
|
| LukeHagar\Plex_API\Models\Errors.SDKException | 4xx-5xx | */* |
|
|
|
|
|
|
## stopTask
|
|
|
|
This endpoint will stop a currently running task by name, or remove it from the list of scheduled tasks if it exists. See the section above for a list of task names for this endpoint.
|
|
|
|
|
|
### Example Usage
|
|
|
|
```php
|
|
declare(strict_types=1);
|
|
|
|
require 'vendor/autoload.php';
|
|
|
|
use LukeHagar\Plex_API;
|
|
use LukeHagar\Plex_API\Models\Components;
|
|
use LukeHagar\Plex_API\Models\Operations;
|
|
|
|
$security = new Components\Security(
|
|
accessToken: "<YOUR_API_KEY_HERE>",
|
|
);
|
|
|
|
$sdk = Plex_API\PlexAPI::builder()
|
|
->setClientID('gcgzw5rz2xovp84b4vha3a40')
|
|
->setClientName('Plex Web')
|
|
->setClientVersion('4.133.0')
|
|
->setClientPlatform('Chrome')
|
|
->setDeviceName('Linux')
|
|
->setSecurity($security)->build();
|
|
|
|
try {
|
|
|
|
$response = $sdk->butler->stopTask(Operations\PathParamTaskName::BackupDatabase);
|
|
|
|
if ($response->statusCode === 200) {
|
|
// handle response
|
|
}
|
|
} catch (Throwable $e) {
|
|
// handle exception
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
| `taskName` | [Operations\PathParamTaskName](../../Models/Operations/PathParamTaskName.md) | :heavy_check_mark: | The name of the task to be started. |
|
|
|
|
### Response
|
|
|
|
**[?Operations\StopTaskResponse](../../Models/Operations/StopTaskResponse.md)**
|
|
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
|
|
| Errors\StopTaskBadRequest | 400 | application/json |
|
|
| Errors\StopTaskUnauthorized | 401 | application/json |
|
|
| LukeHagar\Plex_API\Models\Errors.SDKException | 4xx-5xx | */* |
|