Function
This API is used to create a relay task for pulling a stream from an external source and pushing it based on the settings specified by the tenant.
Authorization Information
Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.
- If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
- If you are using identity policy-based authorization, the following identity policy-based permissions are required.
| Action | Access Level | Resource Type (*: required) | Condition Key | Alias | Dependencies |
| live:stream:createPullTask | Write | - | - | - | - |
URI
POST /v1/{project_id}/pull/stream/task
Table 1 Path Parameters | Parameter | Mandatory | Type | Description |
| project_id | Yes | String | Project ID. For details about how to obtain the project ID, see Obtaining a Project ID. |
Request Parameters
Table 3 Request body parameters | Parameter | Mandatory | Type | Description |
| region | No | String | Definition Task execution region. Constraints If an ingest domain name is specified, use the region of the origin server of the ingest domain name. The default value is the region that the tenant belongs to. Range Length: 1 to 64 characters Default Value N/A |
| source_type | Yes | String | Definition Source stream type. Constraints N/A Range Default Value N/A |
| source_urls | Yes | Array of strings | Definition Source stream URL. Constraints If source_type is set to PullVodPushLive, you can specify multiple video URLs. |
| domain | No | String | Definition Ingest domain name. Constraints N/A Range Length: 0 to 255 characters Default Value N/A |
| app_name | No | String | Definition Application name. Constraints N/A Range Length: 0 to 128 characters Default Value N/A |
| stream_name | No | String | Definition Stream name. Constraints N/A Range Length: 0 to 512 characters Default Value N/A |
| push_args | No | String | Definition Stream push parameters. Constraints N/A Range Length: 0 to 2,048 characters Default Value N/A |
| destination_url | No | String | Definition Complete target URL. Constraints If this parameter is specified, domain, app_name, and stream_name must be empty or not be transferred. Range Length: 0 to 2,048 characters Default Value N/A |
| start_time | No | String | Definition Task start time. Constraints Range N/A Default Value N/A |
| end_time | No | String | Definition Task end time. Constraints Range N/A Default Value N/A |
| vod_loop_time | No | String | Definition Number of video playback rounds. Constraints This parameter is valid only when source_type is set to PullVodPushLive. Range -
-1: loops continuously until the specified end time. -
N: plays the file list for N rounds. Playback stops when the round count is exhausted or the end time is reached, whichever comes first. -
If this parameter is not transferred or is left empty (""), the default value takes effect. Default Value -1 |
| vod_refresh_type | No | String | Definition Effective logic for updated video URLs (source_urls). Constraints This parameter is valid only when source_type is set to PullVodPushLive. Range -
immediate_new_source: immediately starts playback from a new file. -
continue_from_file_start: resumes playback from the start of the last file that was streamed. This option is valid only for task updates. -
continue_from_break_point: resumes playback from the exact breakpoint of the last file that was streamed. This option is valid only for task updates. Default Value immediate_new_source |
| vod_start_video_index | No | Integer | Definition Index of the file to be played. The value starts from 0, indicating the first file. Constraints This parameter is valid only when source_type is set to PullVodPushLive. The maximum value is len(source_urls) – 1. Default Value 0 Value range: 0~2147483647 |
| vod_start_video_time | No | Integer | Definition Second from which the specified file is played. Constraints This parameter is valid only when source_type is set to PullVodPushLive. Default Value 0 Value range: 0~2147483647 |
| backup_source_type | No | String | Definition Type of the standby source. Constraints -
This parameter is valid only when source_type is set to PullVodPushLive. -
When the primary source stream is interrupted, the system automatically switches to the standby source stream. Range PullLivePushLive: livestreaming Default Value N/A |
| backup_source_urls | No | Array of strings | Definition Standby source URL. Constraints The array length is [0,30], and this parameter is valid only when source_type is set to PullVodPushLive. |
| callback_events | No | Array of strings | Definition List of callback events. If this parameter is left blank, callbacks are sent for all events. -
TaskStart: task start callback -
TaskExit: task stop callback -
VodSourceFileStart: file switchover callback (available only for PullVodPushLive tasks) -
VodSourceFileFinish: file playback completion callback (available only for PullVodPushLive tasks) -
ResetTaskConfig: task update callback (available only for PullVodPushLive tasks) -
TaskAlarm: alarm event notification Constraints N/A |
| callback_url | No | String | Definition Callback URL. Constraints N/A Range Length: 0 to 2,048 characters Default Value N/A |
Response Parameters
Status code: 200
Table 4 Response body parameters | Parameter | Type | Description |
| task_id | String | Definition Task ID. Range N/A |
| request_id | String | Definition Request ID. Range N/A |
Status code: 400
Table 5 Response body parameters | Parameter | Type | Description |
| error_code | String | Error code. |
| error_msg | String | Error description. |
| request_id | String | Request ID. |
Example Requests
POST https://{endpoint}/v1/{project_id}/pull/stream/task
{
"region" : "cn-north-4",
"source_type" : "PullLivePushLive",
"source_urls" : [ "rtmp://play.example.huawei.com/live/stream1" ],
"domain" : "publish.example.huawei.com",
"app_name" : "live",
"stream_name" : "test",
"start_time" : "2018-05-19T18:00:00Z",
"end_time" : "2018-05-19T21:00:00Z",
"push_args" : "arg1=value1",
"callback_events" : [ "TaskStart", "TaskExit", "TaskAlarm" ],
"callback_url" : "callback.example.com",
"backup_source_type" : "PullLivePushLive",
"backup_source_urls" : [ "rtmp://play.example.huawei.com/live/stream1_bak" ]
} Example Responses
Status code: 200
The relay task was created.
{
"task_id" : "7864b3dc-e92f-42db-a754-08e627b6d8dd",
"request_id" : "85968475-e92f-42db-a754-08e627b6d8dd"
} Status code: 400
The relay task failed to be created.
{
"error_code" : "LIVE.100011001",
"error_msg" : "Request Illegal",
"request_id" : "85968475-e92f-42db-a754-08e627b6d8dd"
} Status Codes
| Status Code | Description |
| 200 | The relay task was created. |
| 400 | The relay task failed to be created. |
