Program
A Program enables you to control the publishing and storage of segments in a live stream. Programs can run concurrently. This allows you to publish and archive different parts of the event as needed.
You can specify the number of hours you want to retain the recorded content for the program by setting the ArchiveWindowLength property (up to 25 hours). Clients can seek through the archived content for the specified number of hours. If the program runs longer than the specified ArchiveWindowLength, the older content is removed. For more information, see the ArchiveWindowLength documentation below.
This topic gives an overview of the Program entity and also demonstrates how to execute various operations with the Media Services REST API.
Important
When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests.
For more information, see Setup for Media Services REST API Development and Connecting to Media Services with the Media Services REST API.
Program Entity Properties
The Program entity contains the following properties.
| Property | Type | Description |
|---|---|---|
IdRead-only. Set by Media Services. |
Edm.String | The Program ID, assigned upon creation. The format is: nb:pgid:UUID:<GUID>. |
Name |
Edm.String | The name of the Program. The maximum length is 256 characters and can consist of any English characters and numbers, including '-' and ' ' as long as it starts and ends with alphanumeric characters. |
AssetId |
Edm.String | The Asset ID to be used for Program processing. The property can only be updated when the Program is in the Stopped state. An asset cannot be deleted if it is used by a program. You can delete an asset after deleting the program that uses it. |
CreatedRead-only. Set by Media Services. |
Edm.DateTime | A UTC date/time value that indicates the time of creation. |
Description |
Edm.String | User provided description. The maximum length is 256 characters. |
ArchiveWindowLengthRequired. |
Edm.Time | The number of hours you want to retain the recorded content for the program. This value can be set from a minimum of 5 minutes to a maximum of 25 hours. This also dictates the maximum amount of time clients can seek back in time from the current live position. Programs can run over the specified amount of time, but content that falls behind the window length is continuously discarded. This value of this property also determines how long the client manifests can grow. To delete archived content, stop and delete the program and then delete the asset associated with the program. |
LastModifiedRead-only. Set by Media Services. |
Edm.DateTime | The date and time of the last modification. |
ManifestName |
Edm.String | The manifest file name, without extension. This property can be updated only when the Program is in the Stopped state. |
StateRead-only. Set by Media Services. |
Edm.String | Gets the current state. Possible values include: - Stopped. After creating a Program, it is in the Stopped state. In this state, the Program properties can be updated, but streaming is not allowed. The Program can be started, updated, or deleted from this state. - Starting. Program is being started. No updates or streaming is allowed during this state. - Running. Program is capable of processing and archiving live streams. - Stopping. Program is being stopped. No updates or streaming is allowed during this state. |
ChannelIdRead-only. Set by Media Services. |
Edm.String | The ID of the Program's parent Channel. |
Channel |
Channel | The Program's parent channel specified by the ChannelId. |
Create Programs
Create a new Program.
| Method | Request URI | HTTP Version |
|---|---|---|
| POST | https://<accountname>.restv2.<location>.media.azure.net/api/Programs | HTTP/1.1 |
Sample Request
You can try out the following example in the Fiddler’s Composer tab.
To get the latest x-ms-version:, see Media Services REST.
Request headers:
POST https://testrest.cloudapp.net/api/Programs HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
x-ms-version: 2.19
Content-Type: application/json;odata=minimalmetadata
Host: <host URI>
User-Agent: Microsoft ADO.NET Data Services
Authorization: Bearer <token value>
Request body:
{"Id":null,"Name":"testprogram001","Description":"","Created":"0001-01-01T00:00:00","LastModified":"0001-01-01T00:00:00","ChannelId":"nb:chid:UUID:83bb19de-7abf-4907-9578-abe90adfbabe","AssetId":"nb:cid:UUID:bc495364-5357-42a1-9a9d-be54689cfae2","ArchiveWindowLength":"PT1H","State":null,"ManifestName":null}
If successful, a 202 Accepted status code is returned along with a representation of the created entity in the response body.
{"odata.metadata":"https://testrest.cloudapp.net/api/$metadata#Programs/@Element","Id":"nb:pgid:UUID:b870dd57-4b04-41b6-849d-b2470e50e7e6","Name":"testprogram001","Description":"","Created":"2014-08-11T18:12:27.8381256Z","LastModified":"2014-08-11T18:12:27.8381256Z","ChannelId":"nb:chid:UUID:83bb19de-7abf-4907-9578-abe90adfbabe","AssetId":"nb:cid:UUID:bc495364-5357-42a1-9a9d-be54689cfae2","ArchiveWindowLength":"PT1H","State":"Stopped","ManifestName":"f91329ec-26f5-4026-87f5-f5437d4da9e6"}
Note
This operation completes synchronously, so therefore, there is no operation-id to track.
Start Programs
Start a Program. A Program can only be started when it is in the Stopped state and the channel is in the Running state.
| Method | Request URI | HTTP Version |
|---|---|---|
| Start | https://<accountname>.restv2.<location>.media.azure.net/api/Programs(‘ProgramId’)/Start | HTTP/1.1 |
Sample Request
You can try out the following example in the Fiddler’s Composer tab.
To get the latest x-ms-version:, see Media Services REST.
Request headers:
POST https://testrest.cloudapp.net/api/Programs('nb:pgid:UUID:0f9ceb51-50fe-4769-aaed-f8c19d76b9bc')/Start HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
x-ms-version: 2.19
Content-Type: application/json;odata=minimalmetadata
Host: <host URI>
User-Agent: Microsoft ADO.NET Data Services
Authorization: Bearer <token value>
If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Program. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.
Stop Programs
Stop a Program. A Program can be stopped only when it is in the Running state. This is an asynchronous operation.
| Method | Request URI | HTTP Version |
|---|---|---|
| Stop | https://<accountname>.restv2.<location>.media.azure.net/api/Programs(‘ProgramId’)/Stop | HTTP/1.1 |
Sample Request
You can try out the following example in the Fiddler’s Composer tab.
To get the latest x-ms-version:, see Media Services REST.
Request headers:
POST https://testrest.cloudapp.net/api/Programs('nb:pgid:UUID:0f9ceb51-50fe-4769-aaed-f8c19d76b9bc')/Stop HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
x-ms-version: 2.19
Content-Type: application/json;odata=minimalmetadata
Host: <host URI>
User-Agent: Microsoft ADO.NET Data Services
Authorization: Bearer <token value>
If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Program. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.
List Programs
Programs are retrieved using a GET HTTP request.
| Method | Request URI | HTTP Version |
|---|---|---|
| GET | Get all Programs in the Media Services account: https://<accountname>.restv2.<location>.media.azure.net/api/Programs Get a specified Program in the Media Services account: https://<accountname>.restv2.<location>.media.azure.net/api/Programs(‘ProgramId’) Get all Programs associated with a specified Channel: https://<accountname>.restv2.<location>.media.azure.net/api/Channels('channelid')/Programs |
HTTP/1.1 |
Sample Request
You can try out the following example in the Fiddler’s Composer tab.
To get the latest x-ms-version:, see Media Services REST.
Request headers:
GET https://testrest.cloudapp.net/api/Programs HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
x-ms-version: 2.19
Content-Type: application/json;odata=minimalmetadata
Host: <host URI>
User-Agent: Microsoft ADO.NET Data Services
Authorization: Bearer <token value>
If successful, this operation returns a 200 OK status code and a list of all of the Programs created in your Media Services account.
Update Programs
Update a Program. The Program must be the Stopped state.
| Method | Request URI | HTTP Version |
|---|---|---|
| PATCH/PUT/MERGE For more information about these operations, see PATCH/PUT/MERGE. |
https://<accountname>.restv2.<location>.media.azure.net/api/Programs(‘ProgramId’) | HTTP/1.1 |
Sample Request
You can try out the following example in the Fiddler’s Composer tab.
To get the latest x-ms-version:, see Media Services REST.
Request headers:
PATCH https://testrest.cloudapp.net/api/Programs('nb:pgid:UUID:0f9ceb51-50fe-4769-aaed-f8c19d76b9bc') HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
x-ms-version: 2.19
Content-Type: application/json;odata=minimalmetadata
Host: <host URI>
User-Agent: Microsoft ADO.NET Data Services
Authorization: Bearer <token value>
Request body:
{"ArchiveWindowLength":"PT3H"}
If the update completes synchronously, it returns a 204 No Content status code; otherwise it returns a 202 Accepted status code. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Program. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.
Delete Programs
Delete a Program. A Program can be deleted only when it is in the Stopped state.
| Method | Request URI | HTTP Version |
|---|---|---|
| DELETE | https://<accountname>.restv2.<location>.media.azure.net/api/Programs(‘ProgramId’) | HTTP/1.1 |
Sample Request
You can try out the following example in the Fiddler’s Composer tab.
To get the latest x-ms-version:, see Media Services REST.
Request headers:
DELETE https://testrest.cloudapp.net/api/Programs('nb:pgid:UUID:0f9ceb51-50fe-4769-aaed-f8c19d76b9bc') HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
x-ms-version: 2.19
Content-Type: application/json;odata=minimalmetadata
Host: <host URI>
User-Agent: Microsoft ADO.NET Data Services
Authorization: Bearer <token value>
If successful, a 204 No Content status code is returned.
Note
This operation completes synchronously, so therefore, there is no operation-id to track.