All Products
Search
Document Center

ApsaraVideo Live:CreateEventSub

更新時間:Jun 17, 2024

Creates a callback to subscribe to channel or user events.

Usage notes

You can call this operation to create a callback to subscribe to channel or user events. When you create a callback, you can configure parameters such as the callback URL and event type.

QPS limit

You can call this operation up to 100 times per second. Requests that exceed this limit are dropped and you may experience service interruptions. We recommend that you take note of this limit when you call this operation.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter

Type

Required

Example

Description

Action

String

Yes

CreateEventSub

The operation that you want to perform. Set the value to CreateEventSub.

AppId

String

Yes

9qb1****

The application ID.

ChannelId

String

No

123333

The channel ID. You can call the ListEventSub operation to query the ID of a subscribed channel.

Note
  • This parameter is required if you specify the Users.N parameter.

  • If you set this parameter to * or do not specify this parameter, all channels are subscribed to. Each application ID allows only one all-channel subscription.

  • You can create up to 20 subscriptions for each application ID.

Users.N

String

No

user1

The user whose events you want to subscribe to. If you leave this parameter empty, the events of all users in the channel are subscribed to, including the events of the streamer and viewers. Specify this parameter in the following format:

Users.1=****
Users.2=****
......

Events.N

String

Yes

ChannelEvent

The type of the event. Valid values:

  • ChannelEvent: channel events.

  • UserEvent: user events in the channel.

CallbackUrl

String

Yes

http://****.com/callback

The callback URL. For more information about the content of the messages that are sent to the callback URL, see the Callback section in this topic.

Callback

Callback messages are sent to the callback URL that is specified by the CallbackUrl parameter. The following sample code provides an example:

Request:
POST /callbackURL
Body
application/json
{
    "MsgId": "Message ID",
    "MsgTimestamp": 12312324, // The UNIX timestamp when the message was sent.
    "SubscribeID": "Subscription ID",
    "AppId":"",     // The ID of the application in which the message was generated. 
    "ChannelID":"", // The ID of the channel in which the message was generated.
    "Contents": [
      {
        "Event": "UserEvent",// The type of the event that is subscribed to. In this case, the type is user event.
        "UserEvent": {
          "UserId": "80331631628db0d1",    // The user ID.
          "EventTag": "Publish",    // The event. Valid values: Join, Leave, Publish, Unpublish, and Roleupdate.
          "SessionId": "0dr15rrnhkz0jnvz6o8sxo01hoondhu1", // The ID of the session in which the event was generated.
          "Timestamp": 1609854786,    // The UNIX timestamp when the event occurred.
          "Reason": 1, // The reason for joining or leaving the channel. This parameter is available only if the event is a Join event.
          "Role": 1, // The role of the user. The roles include streamer and viewer.
          "CurrentMedias":"1,2,3"// The types of the streams that were ingested by the user.
        }
      },
      {
        "Event": "ChannelEvent",// The type of the event that is subscribed to. In this case, the type is channel event.
        "ChannelEvent": {
          "ChannelId": "8888889999",
          "EventTag": "Open",   // The event. Valid values: Open and Close.
          "Timestamp": 1609854530 // The UNIX timestamp when the event occurred.
        }
      }
   ]
}
Response 
HTTP STATUS 200

Parameters of a user event

Parameter

Type

Required

Description

UserId

string

Yes

The user ID.

SessionId

string

Yes

The session ID.

EventTag

string

Yes

The event. Valid values:

Join: The user joined the channel.

Leave: The user left the channel.

PublishVideo: The user ingested a video stream.

PublishAudio: The user ingested an audio stream.

PublishScreen: The user ingested a stream for screen sharing.

UnpublishVideo: The user stopped ingesting a video stream.

UnpublishAudio: The user stopped ingesting an audio stream.

UnpublishScreen: The user stopped ingesting a stream for screen sharing.

Roleupdate: The role of the user was changed.

Timestamp

number

Yes

The timestamp when the event occurred.

Reason

integer

Yes

The reason for joining or leaving the channel. This parameter is available only if the event is a Join event. Valid values:

1: The user joined or left the channel as needed.

2: The user reconnected to the channel to join the channel again when the user already existed in the channel.

3: The user performed stream relay across channels.

4: The user left the channel due to a timeout.

5: The user started a new session and was forced to go offline in the current session.

6: The user was kicked out of the channel.

7: The channel was closed.

Role

integer

Yes

The role of the user. Valid values:

1: streamer

2: viewer

CurrentMedias

integer

Yes

The type of the stream. Valid values:

1: audio

2: video

3: screen sharing

Parameters of a channel event

Parameter

Type

Required

Description

EventTag

string

Yes

The event. Valid values:

Open: The channel was opened.

Close: The channel was closed.

Timestamp

number

Yes

The timestamp when the event occurred.

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 Ali-Rtc-Timestamp is calculated based on 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.

Exception handling

A keep-alive mechanism is implemented between clients who have joined a channel or started stream ingest and the Alibaba Cloud server. If the server does not receive heartbeat information from clients for 90 seconds, the server considers the client timed out and the user left the channel and fires callbacks. Heartbeats may fail to be detected because a network disconnection occurs or the application accidentally exits.

Response parameters

Parameter

Type

Example

Description

RequestId

String

760bad53276431c499e30dc36f6b26be

The request ID.

SubscribeId

String

ad53276431c****

The subscription ID.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateEventSub
&AppId=9qb1****
&ChannelId=123333
&Users=["user1"]
&Events=["ChannelEvent"]
&CallbackUrl=http://****.com/callback
&<Common request parameters>

Sample success responses

XML format

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

<CreateEventSubResponse>
    <RequestId>760bad53276431c499e30dc36f6b26be</RequestId>
    <SubscribeId>ad53276431c****</SubscribeId>
</CreateEventSubResponse>

JSON format

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

{
  "RequestId" : "760bad53276431c499e30dc36f6b26be",
  "SubscribeId" : "ad53276431c****"
}

Error codes

HttpCode

Error code

Error message

Description

400

InputInvalid

%s.

The specified parameters are invalid.

400

QuotaLimitError

%s.

For each application ID, you can create up to 20 subscriptions and only one all-channel subscription is allowed.

400

ErrorInvalidCallBackUrl

%s.

The value specified for the CallbackUrl parameter is invalid. Check the callback URL and try again.

403

NoAuth

%s.

You do not have the required permissions.

404

ResourceNotExist

%s.

The requested resource does not exist. Check whether the resource exists and try again.

500

ServerError

%s.

An unknown error occurred. Try again later or submit a ticket.

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