Streams
Read Stream
Description
Reads an event stream from system. This read operation provides the client with an origin server address for the given stream name and scope.
To help select nodes from a geographically, Stream Manager allows you to specify two geo info query parameters.
-
region
: Theregion
query parameter can be specified if origin / edge at a specific region is required. If a node is found at the requested region, that will be provided else the next best optimal node will be provided. -
geozone
: Thegeozone
query parameter can be specified to target one or more regions as grouped under thegeozone
. Ageozone
is a macro location concept such as a continent, which can be used to group one or more regions together.
The region
and geozone
parameters are mutually exclusive. If region
is specifed, the geozone
defaults to global
and if the geozone
parameter is specified, the region(s) will be determined by what regions are grouped under the geozone
. If the Geo Information
has not been provisoned and the geozone is specified, it will result in a user error.
- For Broadcasters the Origin address is used to publish a stream
- For Subscribers the Origin address helps in looking up a suitable Edge address for the stream via Origin API gateway
- Query parameter region , is used to optionally lookup a node in a specific region for a broadcast or subscribe request. The specified value for region should match the regions supported by your cloud service provider (Google Compute or Amazon Web Services.
If a stream is not publishing, a subscribe type request will result in a http code 400
or 404
.
REQUEST
- URL:
Broadcaster
SIMPLE REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast
OR
REGION SPECIFIC REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast®ion={regionName}
OR
REGION STRICT REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast®ion={regionName}&strict=true
In using strict
with this request, the broadcast will not be executed if the region specified does not have any live nodes.
OR
GEOZONE SPECIFIC REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&geozone={geozoneCode}
OR
GEOZONE STRICT REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&geozone={geozoneCode}&strict=true
This request requires that the geo information should have been provisioned in Stream Manager about target geozones nd what regions they include.
-
When you specify
endpoints
> 0 along withstrict=true
in a geozone request, Stream Manager will try to collect{endpoints}
number of origins/edges while attempting to utilize each region in the geozone only once. The request will succeed only if each region of the geozone can provide one node (without repeatition) and the requested number of endpoints does not exceed the total number of regions in the geozone. -
When you specify
endpoints
> 0 along withstrict=false
in a geozone request, Stream Manager will try to collect{endpoints}
number of origins/edges from any regions in the geozone without any specific considerations. If however all the regions of the geozone together cannot provide the minimum required endpoints, the request will fail.
OR
MULTI ORIGIN REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&endpoints={count}
Where count corresponds to the number of origins that are needed for the broadcast stream. The attribute accepts a numeric value starting from 1. If the attribute is skipped the count assumes the value of 1, thereby returning one server endpoint for ingest. For count >1 Stream Manager returns an array response whereas for count = 1, a single object is returned. With the strict
flag, the request will fail if the number of nodes existing do not match the number requested.
MULTI ORIGIN STRICT REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&endpoints={count}&strict=true
Where count corresponds to the number of origins that are needed for the broadcast stream. The attribute accepts a numeric value starting from 1. If the attribute is skipped the count assumes the value of 1, thereby returning one server endpoint for ingest. For count >1 Stream Manager returns an array response whereas for count = 1, a single object is returned. With the strict
flag, the request will fail if the number of nodes existing do not match the number requested.
OR
TRANSCODER REQUEST
NOTE: The transcoder broadcast will generate additional multiple bitrate stream variants based off of the original stream (which in turn is used for adaptive bitrate subscription). Before you make a transcode broadcast request, you must create a Stream Provision with the additional bitrate and resolution settings.
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&transcode=true
This request should return a Transcoder node IP address. Note: if you have not provisioned the stream name, then this request will return an Origin server IP address.
Subscriber
SIMPLE REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe
OR
REGION SPECIFIC REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe®ion={regionName}
OR
REGION STRICT REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe®ion={regionName}&strict=true
In using strict
with this request, the broadcast will not be executed if the region specified does not have any live nodes.
OR
MULTI EDGE REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe&endpoints={count}
OR
MULTI EDGE STRICT REQUEST
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe&endpoints={count}&strict=true
Where count corresponds to the number of edges that are needed for subscribing to the stream. The attribute accepts a numeric value starting from 1. If the attribute is skipped the count assumes the value of 1, thereby returning one server endpoint for ingest. For count >1 Stream Manager returns an array response whereas for count = 1, a single object is returned. With the strict
flag, the request will fail if the number of nodes existing do not match the number requested.
For Broadcaster (i.e., ?action=broadcast
)
- Success: HTTP CODE
200
- DATA:
{
"name": "<stream-name>",
"scope": "<stream-scope>",
"serverAddress": "<origin-host-address>",
"region": "<region-code>"
}
For Subscriber (i.e., ?action=subscribe
)
- Success: HTTP CODE
200
- DATA:
{
"name": "<stream-name>",
"scope": "<stream-scope>",
"serverAddress": "<edge-host-address>",
"region": "<region-code>"
}
Example Broadcaster (?action=broadcast)
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/live/demo?action=broadcast
- Method : GET
RESPONSE
- Success: HTTP CODE
200
- DATA:
{
"name": "demo",
"scope": "/live",
"serverAddress": "104.197.131.87",
"region": "us-east-1"
}
Example Subscriber (?action=subscribe)
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/live/demo?action=subscribe
- Method : GET
RESPONSE
- Success: HTTP CODE
200
- DATA:
{
"name": "demo",
"scope": "/live",
"serverAddress": "104.197.85.57",
"region": "us-east-1"
}
Read Stream With Stats
Description
Reads event stream details from system. If a stream is not broadcasting, this operation will result in a 400
or 404
HTTP code.
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}/stats
- Method: GET
RESPONSE
- Failure: HTTP CODE
400
or404
- Data :
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- Success: HTTP CODE
200
- Data:
{
"name": "<stream-name>",
"scope": "<stream-scope>",
"serverAddress": "<origin-host-address>",
"region": "<region-code>",
"currentSubscribers": <subscriber-count>,
"startTime": <start-timestamp>
}
Example
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/live/demo/stats
- Method : GET
RESPONSE
- Success: HTTP CODE
200
- Data:
{
"name": "demo",
"scope": "/live",
"serverAddress": "104.197.131.87",
"region": "us-east-1",
"currentSubscribers": 0,
"startTime": 1454369656708
}
List Streams
Description
Reads all streams active in the system.
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/list
- Method: GET
RESPONSE
- Failure: HTTP CODE
400
or404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- Success: HTTP CODE
200
- Data:
[
{
"type": "node-role",
"name": "<stream-name>",
"scope": "<stream-scope>",
"serverAddress": "<origin-host-address>",
"region": "region-code>"
}
]
Example
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/list
- Method : GET
RESPONSE
- Success: HTTP CODE
200
- Data:
[
{
"type": "origin",
"name": "stream1",
"scope": "live",
"serverAddress": "34.200.228.163",
"region": "us-east-1"
},
{
"type": "edge",
"name": "stream1",
"scope": "live",
"serverAddress": "34.238.220.153",
"region": "us-east-1"
}
]
List All Streams With Stats
Description
Lists all active streams in the system with stats. This api call can produce two different kinds of results – aggregated
and non-aggregated
.Aggregated result displays list of publishing streams (streams at origin) and renders the value of currentSubscribers
as the net total of individual currentSubscribers
values taken from each edge of the nodegroup.Non-Aggregated result displays streams list for each node (origin & edge) that the stream resides on, with the currentSubscribers
value corresponding only to that node.
The optional boolean query parameter aggregate
is used to differentiate between aggregated & non-aggregated stats request.A value of true
will specify request for aggregated stats whereas a value of false
implies a non-aggregated stats request. If the parameter is not specified it defaults to true
.
AGGREGATED STATS REQUEST
http://{host}:{port}/streammanager/api/3.1/event/list/stats
OR
NON-AGGREGATED STATS REQUEST
http://{host}:{port}/streammanager/api/3.1/event/list/stats?aggregate=false
For Aggregated Stats (default)
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/list/stats
- Method: GET
RESPONSE
- Failure: HTTP CODE
400
or404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- Success: HTTP CODE
200
- DATA:
[
{
"name": "<stream-name>",
"scope": "<stream-scope>",
"serverAddress": "<origin-host-address>",
"type": "<node-role>",
"region": "<region-code>",
"currentSubscribers": <aggregate-subscriber-count>,
"startTime": <start-timestamp>
}
]
Example
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/list/stats
- Method : GET
RESPONSE
- Success: HTTP CODE
200
- DATA:
[
{
"currentSubscribers": 0,
"startTime": 1545130249838,
"type": "origin",
"name": "stream1",
"scope": "live",
"serverAddress": "100.27.43.27",
"region": "us-east-1"
},
{
"currentSubscribers": 1,
"startTime": 1545130259426,
"type": "edge",
"name": "origin",
"scope": "live",
"serverAddress": "100.27.43.27",
"region": "us-east-1"
}
]
For Non-Aggregated Stats (i.e., ?aggregate=false
)
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/list/stats?aggregate=false
- Method: GET
RESPONSE
- Failure: HTTP CODE
400
or404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- Success: HTTP CODE
200
- DATA:
[
{
"name": "<stream-name>",
"scope": "<stream-scope>",
"serverAddress": "<node-host-address>",
"type": "<node-role>",
"region": "<region-code>",
"currentSubscribers": <subscriber-count>,
"startTime": <start-timestamp>
}
]
Example
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/event/list/stats
- Method : GET
RESPONSE
- Success: HTTP CODE
200
- DATA:
[
{
"currentSubscribers": 0,
"startTime": 1545130249838,
"type": "origin",
"name": "stream1",
"scope": "live",
"serverAddress": "100.27.43.27",
"region": "us-east-1"
},
{
"currentSubscribers": 0,
"startTime": 1545130249838,
"type": "edge",
"name": "stream1",
"scope": "live",
"serverAddress": "34.237.139.9",
"region": "us-east-1"
},
{
"currentSubscribers": 0,
"startTime": 1545130259426,
"type": "origin",
"name": "stream2",
"scope": "live",
"serverAddress": "100.27.43.27",
"region": "us-east-1"
},
{
"currentSubscribers": 0,
"startTime": 1545130259426,
"type": "edge",
"name": "stream2",
"scope": "live",
"serverAddress": "34.237.139.9",
"region": "us-east-1"
}
]
Delete All Streams
Description
Deletes/Clears all inactive stream entries from the system. The call is meant for administration/maintenance use. It can be used to forcefully clear stream entries that are “stuck” in the system. Using the optional query param includeActive
in the api request, you can also force it to remove active
stream entries (entried for healthy live streams). NOTE: If you delete active
streams, although it does not actually change the state of the live stream, it will make it imposssible for any new subscribers to be added to that stream going through Stream Manager, and additionally that stream will not be listed under the event/list
.
CLEAR INACTIVE STREAM ENTRIES
http://{host}:{port}/streammanager/api/3.1/admin/event?accessToken=<accessToken>
CLEAR ALL STREAM ENTRIES
http://{host}:{port}/streammanager/api/3.1/admin/event?includeActive=true&accessToken=<accessToken>
For Removing Inactive Stream Entries (default behaviour)
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/admin/event?accessToken=<accessToken>
- Method: DELETE
RESPONSE
- Failure: HTTP CODE
400
or404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- Success: HTTP CODE
200
- Data:
{
"count": <deleted-stream--count>,
"timestamp": <timestamp>
}
Example
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/admin/event?accessToken=xyz123
- Method : DELETE
RESPONSE
- Success: HTTP CODE
200
- Data:
{
"count": 0,
"timestamp": 1476193803551
}
For Removing All Stream Entries (?includeActive=true
)
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/admin/event?includeActive=true&accessToken=<accessToken>
- Method: DELETE
RESPONSE
- Failure: HTTP CODE
400
or404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- Success: HTTP CODE
200
- Data:
{
"count": <deleted-stream--count>,
"timestamp": <timestamp>
}
Example
REQUEST
- URI:
http://{host}:{port}/streammanager/api/3.1/admin/event?includeActive=true&accessToken=xyz123
- Method : DELETE
RESPONSE
- Success: HTTP CODE
200
- Data:
{
"count": 1,
"timestamp": 1476193803551
}