ApsaraVideo Live:CreateRtcMPUEventSub

Usage notes

You can call this operation to create a subscription to mixed-stream relay events. You can configure parameters such as callback URLs, application to which you want to subscribe, and channel information when you create a subscription.

QPS limit

You can call this operation up to 100 times per second. Requests that exceed this limit are dropped, and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limits.

Request parameters

Sample callback

Callbacks are sent to your application server as HTTP or HTTPS POST requests. The request is encoded in UTF-8 and the request body is a JSON struct. The callback request is successful if the HTTP status code 200 is returned. Sample code:

{
	"EventType": 1,
	"MsgId": "42bba8b5-94ab-468c-9dae-9b501dd6cb6e",
	"AppId": "rtcdev",
	"SubId": "Sub-9799B2C45009799B2C4500",
	"TaskId": "mpucallbacktest",
	"CallbackTs": 1712656430476,
	"Payload": {
		"DstUrl": "rtmp://domain/app/stream?auth",
		"EventTs": 1712656430384,
		"EventCode": 1,
		"ErrorCode": 0,
		"ErrorMessage": ""
	}
}

Callback information

The following table describes the fields that are included in the callback header.

The following table describes the fields that are included in the callback message.

• The following table describes the fields in Payload.

Callback event codes

The following flowchart shows the lifecycle of a callback event.

Note:

1. Callback information may be sent to your business server out of order. You can sort events by using EventTs in Payload. This allows you to ignore callbacks of expired events and helps you obtain the latest callback information.

2. If you create a mixed-stream relay task by calling the StartLiveMPUTask (new) operation, the task automatically stops when all users in the room leave for a specific period of time. The MPU_STATE_TERMINATED callback is fired when the task stops.

3. Callback configurations affect only incremental tasks. The following rules apply: 1. No callback is fired for tasks that are created before the callback configurations are set or after the callback configurations are deleted. 2. Callbacks are fired for tasks that are created after the callback configurations are set and before the callback configurations are deleted.

Error codes

When a stream relay task ends, you can use ErrorCode and ErrorMessage to identify the cause.

Callback authentication

By default, callback authentication is enabled. The following authentication logic applies:

• When ApsaraVideo Live initiates a callback request, it includes the Ali-Rtc-Timestamp and Ali-Rtc-Signature headers in the HTTP or HTTPS request so that the callback message receiving server can authenticate the signature. The value of the Ali-Rtc-Signature header is calculated by using the following formula: Ali-Rtc-Signature = MD5SUM(MD5CONTENT). In the formula, MD5CONTENT is a string in the following format: Callback domain name|Ali-Rtc-Timestamp value|Authentication key. The callback domain name is the domain name in the callback URL. The authentication key is the AppKey of the application.
• After receiving a callback message, the callback message receiving server concatenates the callback domain name, value of the Ali-Rtc-Timestamp header, and authentication key in the preceding format. The server calculates the MD5 value of the string to obtain an encrypted string. Then, the server compares the encrypted string with the value of the Ali-Rtc-Signature header in the HTTP or HTTPS request initiated by Real-Time Communication (RTC). If the two values are different, the request is invalid.

Callback retry

After Alibaba Cloud initiates a callback request, the callback is considered successful only if the HTTP status code 200 is returned by your business server. If a callback fails, ApsaraVideo Live resends the callback request 7 times at intervals of 1 second, 2 seconds, 5 seconds, 10 seconds, 60 seconds, 120 seconds, and 300 seconds. A callback record is generated each time a callback request is resent.

Response parameters

Examples

Sample requests

http(s)://[live.aliyuncs.com]/?Action=CreateRtcMPUEventSub
&AppId=yourAppId
&ChannelIds=yourChannelIds
&CallbackUrl=http://****.com/callback
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateRtcMPUEventSubResponse>
    <RequestId>******3B-0E1A-586A-AC29-742247******</RequestId>
    <SubId>Sub-******9799B2C4500******</SubId>
</CreateRtcMPUEventSubResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "******3B-0E1A-586A-AC29-742247******",
  "SubId" : "Sub-******9799B2C4500******"
}

Error codes

For a list of error codes, see Service error codes.