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.