Help Center> SparkRTC> API Reference> Recording rule management> Creating or Updating a Recording Rule
Updated on 2022-10-08 GMT+08:00

Creating or Updating a Recording Rule

Function

Creates or updates a recording rule.

  • If the current application does not have a recording rule in the requested location, a new recording rule will be created.

  • If the current application has a recording rule in the requested location, the recording rule will be replaced with the new one.

Constraints

Only one recording rule can be created for each application in a location.

URI

POST /v2/apps/{app_id}/record-rules

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

app_id

Yes

String

Application ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Content type.

X-Auth-Token

No

String

User token. This parameter is mandatory when token authentication is used. It can be obtained by calling the IAM API that is used for obtaining a user token. The value of X-Subject-Token in the response header is the user token.

Authorization

No

String

Authentication information. This parameter is mandatory when AK/SK-based authentication is used.

X-Sdk-Date

No

String

Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.

X-Project-Id

No

String

Project ID. This parameter is mandatory when AK/SK-based authentication is used.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

obs_addr

Yes

RecordObsFileAddr object

Bucket where recording files are stored.

record_formats

Yes

Array of strings

Recording format: The HLS and MP4 formats are supported.

  • If HLS is configured, the HLSRecordConfig parameter must be carried.

  • If MP4 is configured, the MP4RecordConfig parameter must be carried.

hls_config

No

HLSRecordConfig object

HLS recording rule configuration.

mp4_config

No

MP4RecordConfig object

MP4 recording rule configuration.

Table 4 RecordObsFileAddr

Parameter

Mandatory

Type

Description

location

Yes

String

ID of the region where the OBS bucket resides.

project_id

Yes

String

Project ID of the region where the OBS bucket resides.

bucket

Yes

String

OBS bucket name.

object

No

String

OBS object path, which complies with the OBS Object definition. If this parameter is left empty, recordings will be saved to the root directory.

Table 5 HLSRecordConfig

Parameter

Mandatory

Type

Description

record_cycle

Yes

Integer

Duration of periodic recording.

Value range: [60,43200] or 0. If the value is 0, the entire stream is recorded as a file.

Unit: second

record_prefix

No

String

Prefix of the M3U8 recording file containing the path and file name.

Default value: {app_id}/{record_format}/{stream}_{file_start_time}/{stream}_{file_start_time}

The following special variables can be customized:

  • app_id: application ID

  • record_format: recording format

  • stream: stream name

  • file_start_time: file generation time

record_slice_duration

No

Integer

TS slice duration for HLS recording, which is optional.

The value ranges from 2 to 60. The default value is 10.

Unit: second

record_max_duration_to_merge_file

No

Integer

Interval threshold for combining HLS chunks. If the stream interruption duration exceeds this threshold, a new file will be generated.

The value ranges from -1 to 300. The default value is 0.

Unit: second

If the value is set to 0, a new file will be generated once the stream is interrupted.

  • If the value is set to -1, the stream is appended to the original file after the stream is resumed (the interval does not exceed 30 days).

Table 6 MP4RecordConfig

Parameter

Mandatory

Type

Description

record_cycle

Yes

Integer

Duration of periodic recording.

Value range: [60, 10800].

Unit: second

record_prefix

No

String

Prefix of the recording file containing the path and file name.

Default value: {app_id}/{record_format}/{stream}_{file_start_time}/{stream}_{file_start_time}

The following special variables can be customized:

  • app_id: application ID

  • record_format: recording format

  • stream: stream name

  • file_start_time: file generation time

record_max_duration_to_merge_file

No

Integer

Interval threshold for combining MP4 chunks. If the stream interruption duration exceeds this threshold, a new file will be generated.

The value ranges from 0 to 300. The default value is 0.

Unit: second

If the value is set to 0, a new file will be generated once the stream is interrupted.

Response Parameters

Status code: 201

Table 7 Response header parameters

Parameter

Type

Description

X-request-Id

String

Request ID for task tracing.

Table 8 Response body parameters

Parameter

Type

Description

rule_id

String

Rule ID, which is returned by the server. This parameter does not need to be carried during rule creation or modification.

app_id

String

Application ID.

obs_addr

RecordObsFileAddr object

Bucket where recording files are stored.

record_formats

Array of strings

Recording format: HLS or MP4.

hls_config

HLSRecordConfig object

HLS recording rule configuration.

mp4_config

MP4RecordConfig object

MP4 recording rule configuration.

create_time

String

Creation time, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.

update_time

String

Update time, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.

Table 9 RecordObsFileAddr

Parameter

Type

Description

location

String

ID of the region where the OBS bucket resides.

project_id

String

Project ID of the region where the OBS bucket resides.

bucket

String

OBS bucket name.

object

String

OBS object path, which complies with the OBS Object definition. If this parameter is left empty, recordings will be saved to the root directory.

Table 10 HLSRecordConfig

Parameter

Type

Description

record_cycle

Integer

Duration of periodic recording.

Value range: [60,43200] or 0. If the value is 0, the entire stream is recorded as a file.

Unit: second

record_prefix

String

Prefix of the M3U8 recording file containing the path and file name.

Default value: {app_id}/{record_format}/{stream}_{file_start_time}/{stream}_{file_start_time}

The following special variables can be customized:

  • app_id: application ID

  • record_format: recording format

  • stream: stream name

  • file_start_time: file generation time

record_slice_duration

Integer

TS slice duration for HLS recording, which is optional.

The value ranges from 2 to 60. The default value is 10.

Unit: second

record_max_duration_to_merge_file

Integer

Interval threshold for combining HLS chunks. If the stream interruption duration exceeds this threshold, a new file will be generated.

The value ranges from -1 to 300. The default value is 0.

Unit: second

If the value is set to 0, a new file will be generated once the stream is interrupted.

  • If the value is set to -1, the stream is appended to the original file after the stream is resumed (the interval does not exceed 30 days).

Table 11 MP4RecordConfig

Parameter

Type

Description

record_cycle

Integer

Duration of periodic recording.

Value range: [60, 10800].

Unit: second

record_prefix

String

Prefix of the recording file containing the path and file name.

Default value: {app_id}/{record_format}/{stream}_{file_start_time}/{stream}_{file_start_time}

The following special variables can be customized:

  • app_id: application ID

  • record_format: recording format

  • stream: stream name

  • file_start_time: file generation time

record_max_duration_to_merge_file

Integer

Interval threshold for combining MP4 chunks. If the stream interruption duration exceeds this threshold, a new file will be generated.

The value ranges from 0 to 300. The default value is 0.

Unit: second

If the value is set to 0, a new file will be generated once the stream is interrupted.

Status code: 400

Table 12 Response header parameters

Parameter

Type

Description

X-request-Id

String

Request ID for task tracing.

Table 13 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Description.

Status code: 404

Table 14 Response header parameters

Parameter

Type

Description

X-request-Id

String

Request ID for task tracing.

Table 15 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Description.

Status code: 500

Table 16 Response header parameters

Parameter

Type

Description

X-request-Id

String

Request ID for task tracing.

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Description.

Example Requests

POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-rules

{
  "obs_addr" : {
    "bucket" : "obsName",
    "location" : "cn-north-4",
    "object" : "Record/",
    "project_id" : "ad7456ce8ef89adf567"
  },
  "record_formats" : [ "MP4" ],
  "mp4_config" : {
    "record_cycle" : 60,
    "record_max_duration_to_merge_file" : 0
  }
}

Example Responses

Status code: 201

The configuration is successful.

{
  "app_id" : "123456abc",
  "rule_id" : "456789abc",
  "create_time" : "2006-01-02T15:04:05.075Z",
  "obs_addr" : {
    "bucket" : "obsName",
    "location" : "cn-north-4",
    "object" : "Record/",
    "project_id" : "ad7456ce8ef89adf567"
  },
  "record_formats" : [ "MP4" ],
  "mp4_config" : {
    "record_cycle" : 60,
    "record_max_duration_to_merge_file" : 0
  },
  "update_time" : "2006-01-02T15:04:05.075Z"
}

Status code: 400

Configuration failed because the request cannot be understood by the server or parameters are incorrect.

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

Status code: 404

Configuration failed because the application does not exist.

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

Status code: 500

Configuration failed due to server error.

{
  "error_code" : "RTC.00002xxx",
  "error_msg" : "InternalError"
}

Status Codes

Status Code

Description

201

The configuration is successful.

400

Configuration failed because the request cannot be understood by the server or parameters are incorrect.

404

Configuration failed because the application does not exist.

500

Configuration failed due to server error.

Error Codes

See Error Codes.