Configures stream ingest callbacks for an ingest domain.
Usage notes
You can call this operation to configure the callback URL and authentication information of an ingest domain.
QPS limit
You can call this operation up to 15 times per second per account. 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 limit on an API operation in ApsaraVideo Live.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | SetLiveStreamsNotifyUrlConfig | The operation that you want to perform. Set the value to SetLiveStreamsNotifyUrlConfig. |
DomainName | String | Yes | demo.aliyundoc.com | The ingest domain. |
NotifyUrl | String | Yes | http://guide.aliyundoc.com/notify | The URL to which the stream ingest callbacks are sent. |
NotifyReqAuth | String | No | yes | Specifies whether to enable callback authentication. Valid values:
Note Default value:
no.
For information about the authentication logic, see Authentication for stream ingest callbacks. |
NotifyAuthKey | String | No | 123456 | The authentication key.
Note This parameter is required if you set the NotifyReqAuth parameter to
yes.
Value requirements:
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
RequestId | String | 40A4F36D-A7CC-473A-88E7-154F92242566 | The ID of the request. |
Examples
Sample requests
http(s)://live.aliyuncs.com/?Action=SetLiveStreamsNotifyUrlConfig
&DomainName=demo.aliyundoc.com
&NotifyUrl=http://guide.aliyundoc.com/notify
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<SetLiveStreamsNotifyUrlConfigResponse>
<RequestId>4C747C97-7ECD-4C61-8A92-67AD806331FF</RequestId>
</SetLiveStreamsNotifyUrlConfigResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"SetLiveStreamsNotifyUrlConfigResponse" : {
"RequestId" : "4C747C97-7ECD-4C61-8A92-67AD806331FF"
}
}
Error codes
HttpCode | Error code | Error message | Description |
---|---|---|---|
400 | ConfigAlreadyExists | Config has already exist. | The error message returned because the configuration already exists. |
For a list of error codes, see Service error codes.
Callback logic
Callback logic for stream ingest status:
During stream ingest over Real-Time Messaging Protocol (RTMP), ApsaraVideo Live checks whether the stream ingest client closes the connection within 2 seconds after ApsaraVideo Live receives an OnPublish message. If the stream ingest client does not close the connection, ApsaraVideo Live sends a callback notification about the successful stream ingest. If your business requires ApsaraVideo Live to send this callback notification only when ApsaraVideo Live receives live streaming data after the connection is established, submit a ticket. For more information about how to submit a ticket, see Contact us.
For example, you have Ingest Domain A and Streaming Domain B. You can configure regular stream pulling and triggered stream pulling for Streaming Domain B. If you want to receive callback notifications about the stream pulling status, configure stream ingest callbacks for Ingest Domain A. After the configuration, ApsaraVideo Live uses the same callback logic as that for stream ingest status to send callback notifications about the stream pulling status under Streaming Domain B. By default, ApsaraVideo Live sends a callback notification about successful stream pulling if the stream pulling client does not close the connection within 2 seconds after the connection is established.
Authentication for stream ingest callbacks
By default, authentication for stream ingest callbacks is disabled. You can enable the feature when you specify the stream ingest callback URL. After you enable the feature, the following authentication logic applies:
1. When ApsaraVideo Live initiates a callback request, it includes the ALI-LIVE-TIMESTAMP
and ALI-LIVE-SIGNATURE
headers in the HTTP or HTTPS request so that the callback message receiving server can authenticate the signature. The value of ALI-LIVE-SIGNATURE
is calculated based on the following formula:
ALI-LIVE-SIGNATURE = MD5SUM (MD5CONTENT)
MD5CONTENT = <Domain name of the callback>|<ALI-LIVE-TIMESTAMP value>|<Authentication key>
2. After receiving a callback message, the callback message receiving server concatenates the domain name of the callback, value of the ALI-LIVE-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-LIVE-SIGNATURE header in the HTTP or HTTPS request initiated by ApsaraVideo Live. If the two values are different, the request is invalid.
Special error codes
Error code |
Error message |
HTTP status code |
Description |
---|---|---|---|
InternalError |
The request processing has failed due to some unknown error. |
500 |
The error message returned because an unknown error occurred. |
InvalidDomain.NotFound |
The domain provided does not exist in our records. |
404 |
The error message returned because the domain name is not found under your Alibaba Cloud account. |
IllegalOperation |
Illegal domain operate is not permitted. |
403 |
The error message returned because the current operation is not supported. For example, the specified domain name is not a domain name in ApsaraVideo Live. |
InvalidNotifyUrl.Malformed |
Specified parameter NotifyUrl is not valid. |
400 |
The error message returned because the callback URL is not a valid HTTP URL. |
InvalidNotifyUrl.Unsafe |
Specified NotifyUrl is not safe. |
400 |
The error message returned because the callback URL is unsecure. |