AWS Elemental MediaTailor

(1)

AWS Elemental MediaTailor

API Reference

(2)

AWS Elemental MediaTailor: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

AWS Elemental MediaTailor API

Use the AWS Elemental MediaTailor API to conﬁgure scalable ad insertion and linear streams for your content. Using MediaTailor ad insertion, you can serve targeted ads to viewers while maintaining broadcast quality in over-the-top (OTT) video applications. Using MediaTailor channel assembly, you can assemble linear streams using your existing VOD content, and easily integrate a server-side ad insertion service such as MediaTailor. For information about using the service, including detailed information about the settings covered in this guide, see the AWS Elemental MediaTailor User Guide.

Through the REST API, you manage MediaTailor conﬁgurations the same as you do through the console.

For example, you specify ad insertion behavior and mapping information for the origin server and the ad decision server (ADS).

Specifying the REST API Endpoint

The AWS Elemental MediaTailor REST API endpoint is formatted as follows.

https://api.mediatailor.<region>.amazonaws.com/

For the list of MediaTailor Regions, see AWS Regions and Endpoints: MediaTailor.

Signing Requirements

MediaTailor supports authentication using AWS Signature Version 4. For more information, see Signature Version 4 Signing Process in the AWS General Reference.

When you access MediaTailor through the AWS CLI or one of the SDKs, the tools automatically sign the requests for you with the access key and secret key that you specify in your client conﬁguration.

For REST API use, you implement a cryptographic hash function that complies with AWS Signature Version 4 to calculate the security signature for your requests. You include a security signature in each REST API request to MediaTailor, and the service validates your signature before proceeding.

• To sign a request, you use your hash function to calculate a digital signature. You pass the function the text of your request and your secret access key. The function returns the corresponding hash value. You include the hash value in the signature portion of the Authorization header of your request.

• When it receives your request, MediaTailor runs its own calculation of the signature, and then compares that to the signature that you provided in the header. If they match, MediaTailor processes your request.

(7)

Channel

Resources

The AWS Elemental MediaTailor REST API includes the following resources.

Topics

• Channel (p. 2)

• ChannelPolicy (p. 12)

• ConﬁgureLogs PlaybackConﬁguration (p. 16)

• GetChannelSchedule (p. 18)

• ListAlerts (p. 22)

• ListChannels (p. 25)

• ListPlaybackConﬁgurations (p. 31)

• ListPrefetchSchedules (p. 40)

• ListSourceLocations (p. 46)

• ListVodSources (p. 51)

• PlaybackConﬁguration (p. 55)

• PrefetchSchedule (p. 65)

• Program (p. 72)

• PutPlaybackConﬁguration (p. 81)

• SourceLocation (p. 93)

• StartChannel (p. 102)

• StopChannel (p. 103)

• Tags (p. 105)

• VodSource (p. 109)

Channel

Creates, describes, updates, or deletes a channel. For information about MediaTailor channels, see Working with channels in the MediaTailor User Guide.

URI

/v1/channel/channelName

HTTP methods

GET

Operation ID: DescribeChannel

Describes the properties of a speciﬁc channel.

(8)

HTTP methods

Path parameters

Name Type Required Description

channelName String True The identiﬁer for

the channel you are working on.

Responses

Status code Response model Description

200 DescribeChannelResponse (p. 5)Success.

POST

Operation ID: CreateChannel Creates a channel.

Path parameters

Responses

PUT

Operation ID: UpdateChannel Updates an existing channel.

Path parameters

Responses

(9)

Schemas

DELETE

Operation ID: DeleteChannel

Deletes a channel. You must stop the channel before it can be deleted.

Path parameters

Responses

200 DeleteChannelResponse (p. 6)Success.

OPTIONS

Path parameters

Responses

200 None 200 response

Schemas

Request bodies

POST schema

{ "FillerSlate": {

"VodSourceName": "string", "SourceLocationName": "string"

},

"Outputs": [ {

"ManifestName": "string", "DashPlaylistSettings": {

"ManifestWindowSeconds": integer,

"SuggestedPresentationDelaySeconds": integer, "MinBufferTimeSeconds": integer,

(10)

Schemas

"MinUpdatePeriodSeconds": integer },

"HlsPlaylistSettings": {

"ManifestWindowSeconds": integer },

"SourceGroup": "string"

}

], "PlaybackMode": enum, "tags": {

} }

PUT schema

{ "FillerSlate": {

}, "Outputs": [ {

"HlsPlaylistSettings": {

} ]}

Response bodies

DescribeChannelResponse schema

{

"FillerSlate": {

}, "ChannelState": enum, "ChannelName": "string", "CreationTime": integer, "LastModifiedTime": integer, "Outputs": [

{

"PlaybackUrl": "string", "HlsPlaylistSettings": {

"ManifestWindowSeconds": integer

(11)

Properties

},

} ],

"Arn": "string",

"PlaybackMode": "string", "tags": {

}}

DeleteChannelResponse schema

{}

Properties

CreateChannelRequest

The conﬁguration for this channel.

FillerSlate

The slate used to fill gaps between programs in the schedule. You must configure filler slate if your channel uses the LINEAR PlaybackMode. MediaTailor doesn't support filler slate for channels using the LOOP PlaybackMode.

Type: SlateSource (p. 10) Required: False

Outputs

The channel's output properties.

Type: Array of type RequestOutputItem (p. 9) Required: True

PlaybackMode

The type of playback mode to use for this channel.

LINEAR - The programs in the schedule play once back-to-back in the schedule.

LOOP - The programs in the schedule play back-to-back in an endless loop. When the last program in the schedule stops playing, playback loops back to the ﬁrst program in the schedule.

Type: string Required: True

Values: LOOP | LINEAR

tags

The tags to assign to the channel.

Type: object Required: False

(12)

Properties

DashPlaylistSettings

Dash manifest conﬁguration parameters.

ManifestWindowSeconds

The total duration (in seconds) of each manifest. Minimum value: 30 seconds. Maximum value: 3600 seconds.

Type: integer Required: False

SuggestedPresentationDelaySeconds

Amount of time (in seconds) that the player should be from the live point at the end of the manifest.

Minimum value: 2 seconds. Maximum value: 60 seconds.

MinBuﬀerTimeSeconds

Minimum amount of content (measured in seconds) that a player must keep available in the buﬀer.

MinUpdatePeriodSeconds

Minimum amount of time (in seconds) that the player should wait before requesting updates to the manifest. Minimum value: 2 seconds. Maximum value: 60 seconds.

DeleteChannelResponse

This response includes only the "type" : "object" property.

DescribeChannelResponse

Returns a channel's properties.

FillerSlate

Contains information about the slate used to ﬁll gaps between programs in the schedule.

ChannelState

Indicates whether the channel is in a running state or not.

(13)

Properties

Values: RUNNING | STOPPED

ChannelName

The name of the channel.

CreationTime

The timestamp of when the channel was created.

Type: integer Required: False Format: date-time

LastModiﬁedTime

The timestamp of when the channel was last modiﬁed.

Outputs

Type: Array of type ResponseOutputItem (p. 9) Required: True

Arn

The ARN of the channel.

PlaybackMode

The channel's playback mode.

tags

The tags assigned to the channel.

(14)

Properties

HlsPlaylistSettings

HLS playlist conﬁguration parameters.

ManifestWindowSeconds

RequestOutputItem

The output conﬁguration for this channel.

ManifestName

The name of the manifest for the channel. The name appears in the PlaybackUrl.

DashPlaylistSettings

DASH manifest conﬁguration parameters.

Type: DashPlaylistSettings (p. 7) Required: False

HlsPlaylistSettings

Type: HlsPlaylistSettings (p. 9) Required: False

SourceGroup

A string used to match which HttpPackageConfiguration is used for each VodSource.

ResponseOutputItem

This response includes only the "property" : "type" property.

ManifestName

The name of the manifest for the channel that will appear in the channel output's playback URL.

(15)

Properties

DashPlaylistSettings

DASH manifest conﬁguration settings.

PlaybackUrl

The URL used for playback by content players.

HlsPlaylistSettings

HLS manifest conﬁguration settings.

SourceGroup

A string used to associate a package conﬁguration source group with a channel output.

SlateSource

Slate VOD source conﬁguration.

VodSourceName

The slate VOD source name. The VOD source must already exist in a source location before it can be used for slate.

Type: string Required: False

SourceLocationName

The name of the source location where the slate VOD source is stored.

UpdateChannelRequest

Updates a channel's Outputs.

FillerSlate

(16)

See also

Outputs

Type: Array of type RequestOutputItem (p. 9) Required: True

DescribeChannel

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWS SDK for Java V2

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3

CreateChannel

• AWS SDK for C++

• AWS SDK for Go

UpdateChannel

• AWS SDK for C++

• AWS SDK for Go

(17)

ChannelPolicy

DeleteChannel

• AWS SDK for C++

• AWS SDK for Go

ChannelPolicy

Manages a channel's IAM policy. IAM policies are used to control access to your channel.

URI

/v1/channel/channelName/policy

HTTP methods

GET

Operation ID: GetChannelPolicy

Retrieves information about a channel's IAM policy.

Path parameters

Responses

200 GetChannelPolicyResponse (p. 14)Success.

PUT

Operation ID: PutChannelPolicy

(18)

HTTP methods

Creates an IAM policy for the channel.

Path parameters

Responses

200 PutChannelPolicyResponse (p. 14)Success.

DELETE

Operation ID: DeleteChannelPolicy Deletes a channel's IAM policy.

Path parameters

Responses

200 DeleteChannelPolicyResponse (p. 14)Success.

OPTIONS

Path parameters

Responses

(19)

Schemas

Request bodies

PUT schema

{ "Policy": "string"

}

DELETE schema

{ }

Response bodies

GetChannelPolicyResponse schema

{ "Policy": "string"

}

PutChannelPolicyResponse schema

{ }

DeleteChannelPolicyResponse schema

{ }

Properties

DeleteChannelPolicyRequest

DeleteChannelPolicyResponse

GetChannelPolicyResponse

Returns the channel's IAM policy.

Policy

The IAM policy for the channel.

Type: string

(20)

See also

Required: False

PutChannelPolicyRequest

Adds an IAM policy for the channel.

Policy

Adds an IAM role that determines the permissions of your channel.

PutChannelPolicyResponse

GetChannelPolicy

• AWS SDK for C++

• AWS SDK for Go

PutChannelPolicy

• AWS SDK for C++

• AWS SDK for Go

DeleteChannelPolicy

(21)

ConﬁgureLogs PlaybackConﬁguration

• AWS SDK for C++

• AWS SDK for Go

ConﬁgureLogs PlaybackConﬁguration

Conﬁgures Amazon CloudWatch log settings for an existing MediaTailor playback conﬁguration.

URI

/v1/configureLogs/playbackConfiguration

HTTP methods

PUT

Operation ID: ConfigureLogsForPlaybackConfiguration

Conﬁgures Amazon CloudWatch log settings for a playback conﬁguration.

Responses

200 ConfigureLogsForPlaybackConfigurationResponse (p. 17)Success.

OPTIONS

Responses

Schemas

Request bodies

PUT schema

{

"PercentEnabled": integer,

"PlaybackConfigurationName": "string"

(22)

Properties

}

Response bodies

ConﬁgureLogsForPlaybackConﬁgurationResponse schema

{ "PercentEnabled": integer,

"PlaybackConfigurationName": "string"

}

Properties

ConﬁgureLogsForPlaybackConﬁgurationRequest

Conﬁgures Amazon CloudWatch log settings for an existing MediaTailor playback conﬁguration.

PercentEnabled

The percentage of session logs that MediaTailor sends to your Cloudwatch Logs account. For example, if your playback configuration has 1000 sessions and percentEnabled is set to 60, MediaTailor sends logs for 600 of the sessions to CloudWatch Logs. MediaTailor decides at random which of the playback configuration sessions to send logs for. If you want to view logs for a specific session, you can use the debug log mode.

Valid values: 0 - 100 Type: integer Required: True

PlaybackConﬁgurationName

The name of the playback conﬁguration.

ConﬁgureLogsForPlaybackConﬁgurationResponse

Amazon CloudWatch log settings for a playback conﬁguration.

PercentEnabled

The percentage of session logs that MediaTailor sends to your Cloudwatch Logs account.

Type: integer Required: True

PlaybackConﬁgurationName

The name of the playback conﬁguration.

(23)

See also

ConﬁgureLogsForPlaybackConﬁguration

• AWS SDK for C++

• AWS SDK for Go

GetChannelSchedule

Retrieves information about your channel's schedule.

URI

/v1/channel/channelName/schedule

HTTP methods

GET

Operation ID: GetChannelSchedule

Retrieves information about your channel's schedule.

Path parameters

Query parameters

nextToken String False Pagination token from

the GET list request.

Use the token to fetch the next page of results.

(24)

Schemas

maxResults String False Upper bound on

number of records to return. The maximum number of results is 100.

durationMinutes String False The schedule duration

in minutes. The maximum duration is 4320 minutes (three days).

Responses

200 GetChannelScheduleResponse (p. 19)Success.

OPTIONS

Path parameters

Responses

Schemas

Response bodies

GetChannelScheduleResponse schema

{

"NextToken": "string", "Items": [

{

"VodSourceName": "string", "ChannelName": "string",

"SourceLocationName": "string", "ScheduleEntryType": enum, "ScheduleAdBreaks": [ {

"VodSourceName": "string",

(25)

Properties

"SourceLocationName": "string",

"ApproximateDurationSeconds": integer, "ApproximateStartTime": integer }

],

"ApproximateDurationSeconds": integer, "Arn": "string",

"ApproximateStartTime": integer, "ProgramName": "string"

} ] }

Properties

GetChannelScheduleResponse

Returns the schedule entries for the channel.

NextToken

Pagination token from the GET list request. Use the token to fetch the next page of results.

Items

An array of schedule entries for the channel.

Type: Array of type ScheduleEntry (p. 21) Required: False

ScheduleAdBreak

The schedule's ad break properties.

VodSourceName

The name of the VOD source used for the ad break.

SourceLocationName

The name of the source location containing the VOD source used for the ad break.

ApproximateDurationSeconds

The approximate duration of the ad break, in seconds.

(26)

Properties

Type: integer Required: False Format: int64

ApproximateStartTime

The approximate time that the ad will start playing.

ScheduleEntry

The properties for a schedule.

VodSourceName

The name of the VOD source.

ChannelName

The name of the channel that uses this schedule.

SourceLocationName

The name of the source location.

ScheduleEntryType

The type of schedule entry.

Valid values: PROGRAM or FILLER_SLATE.

Values: PROGRAM | FILLER_SLATE

ScheduleAdBreaks

The schedule's ad break properties.

Type: Array of type ScheduleAdBreak (p. 20) Required: False

(27)

See also

ApproximateDurationSeconds

The approximate duration of this program, in seconds.

Type: integer Required: False Format: int64

Arn

The ARN of the program.

ApproximateStartTime

The approximate time that the program will start playing.

ProgramName

The name of the program.

GetChannelSchedule

• AWS SDK for C++

• AWS SDK for Go

ListAlerts

Lists the alerts that are associated with a MediaTailor channel assembly resource.

(28)

URI

/v1/alerts

HTTP methods

GET

Operation ID: ListAlerts

Returns a list of alerts for the given resource.

Query parameters

resourceArn String True The Amazon Resource

Name (ARN) of the resource.

Responses

200 ListAlertsResponse (p. 23)Success.

OPTIONS

Responses

Schemas

Response bodies

ListAlertsResponse schema

{

(29)

Properties

{

"ResourceArn": "string", "AlertCode": "string", "LastModifiedTime": integer, "RelatedResourceArns": [ "string"

],

"AlertMessage": "string"

} ]}

Properties

Alert

Alert conﬁguration parameters.

ResourceArn

The Amazon Resource Name (ARN) of the resource.

AlertCode

The code for the alert. For example, NOT_PROCESSED.

LastModiﬁedTime

The timestamp when the alert was last modiﬁed.

Type: integer Required: True Format: date-time

RelatedResourceArns

The Amazon Resource Names (ARNs) related to this alert.

Type: Array of type string Required: True

AlertMessage

If an alert is generated for a resource, an explanation of the reason for the alert.

(30)

See also

ListAlertsResponse

Lists the alerts for a given resource.

NextToken

Pagination token from the list request. Use the token to fetch the next page of results.

Items

An array of alerts that are associated with this resource.

Type: Array of type Alert (p. 24) Required: False

ListAlerts

• AWS SDK for C++

• AWS SDK for Go

ListChannels

Retrieves information about the channels that are associated with the current AWS account.

URI

/v1/channels

HTTP methods

GET

Operation ID: ListChannels

Retrieves a list of channels that are associated with this account.

(31)

Schemas

Query parameters

Responses

200 ListChannelsResponse (p. 26)Success.

OPTIONS

Responses

Schemas

Response bodies

ListChannelsResponse schema

{

"FillerSlate": {

},

"ChannelState": "string", "ChannelName": "string", "CreationTime": integer, "LastModifiedTime": integer, "Outputs": [

{

(32)

Properties

"PlaybackUrl": "string", "HlsPlaylistSettings": {

} ],

"Arn": "string",

"PlaybackMode": "string", "tags": {

} } ]}

Properties

Channel

The conﬁguration parameters for a channel.

FillerSlate

ChannelState

Returns the state whether the channel is running or not.

ChannelName

The name of the channel.

CreationTime

The timestamp of when the channel was created.

LastModiﬁedTime

The timestamp of when the channel was last modiﬁed.

Type: integer

(33)

Properties

Required: False Format: date-time

Outputs

Type: Array of type ResponseOutputItem (p. 29) Required: True

Arn

The ARN of the channel.

PlaybackMode

The type of playback mode for this channel.

LINEAR - Programs play back-to-back only once.

LOOP - Programs play back-to-back in an endless loop. When the last program in the schedule plays, playback loops back to the ﬁrst program in the schedule.

tags

The tags to assign to the channel.

DashPlaylistSettings

Dash manifest conﬁguration parameters.

ManifestWindowSeconds

SuggestedPresentationDelaySeconds

Amount of time (in seconds) that the player should be from the live point at the end of the manifest.

(34)

Properties

MinBuﬀerTimeSeconds

Minimum amount of content (measured in seconds) that a player must keep available in the buﬀer.

MinUpdatePeriodSeconds

Minimum amount of time (in seconds) that the player should wait before requesting updates to the manifest. Minimum value: 2 seconds. Maximum value: 60 seconds.

HlsPlaylistSettings

ManifestWindowSeconds

ListChannelsResponse

Returns a list of channels.

NextToken

Pagination token returned by the list request when results exceed the maximum allowed. Use the token to fetch the next page of results.

Items

An array of channels that are associated with this account.

Type: Array of type Channel (p. 27) Required: False

ResponseOutputItem

This response includes only the "property" : "type" property.

ManifestName

The name of the manifest for the channel that will appear in the channel output's playback URL.

(35)

See also

DashPlaylistSettings

DASH manifest conﬁguration settings.

PlaybackUrl

The URL used for playback by content players.

HlsPlaylistSettings

HLS manifest conﬁguration settings.

SourceGroup

A string used to associate a package conﬁguration source group with a channel output.

SlateSource

Slate VOD source conﬁguration.

VodSourceName

The slate VOD source name. The VOD source must already exist in a source location before it can be used for slate.

SourceLocationName

The name of the source location where the slate VOD source is stored.

ListChannels

• AWS SDK for C++

• AWS SDK for Go

ListPlaybackConﬁgurations

Retrieves existing playback configurations. For information about MediaTailor configurations, see Working with Configurations in AWS Elemental MediaTailor.

URI

/v1/playbackConfigurations

HTTP methods

GET

Operation ID: ListPlaybackConfigurations

Returns a list of the playback configurations defined in AWS Elemental MediaTailor. You can specify a maximum number of configurations to return at a time. The default maximum is 50. Results are returned in pagefuls. If MediaTailor has more configurations than the specified maximum, it provides parameters in the response that you can use to retrieve the next pageful.

Example Request

GET /playbackConfigurations

Example Response

Success: 200 {

"Items": [ {

"Name": "testConfig",

"AdDecisionServerUrl": "http://testAds.com", "VideoContentSourceUrl": "http://testOrigin.com", "PlaybackConfigurationArn": "arn:aws:mediatailor:us- east-1:111111111111:playbackConfiguration/testConfig", "tags": {

"testKey": "testValue"

}

(37)

Schemas

} {

"Name": "newTestConfig",

"AdDecisionServerUrl": "http://testAds.com", "VideoContentSourceUrl": "http://testOrigin.com", "PlaybackConfigurationArn": "arn:aws:mediatailor:us- east-1:111111111111:playbackConfiguration/newTestConfig", "tags": {

} } ] }

Query parameters

MaxResults String False Maximum number of

records to return.

NextToken String False Pagination token

returned by the GET list request when results exceed the maximum allowed. Use the token to fetch the next page of results.

Responses

200 ListPlaybackConfigurationsResponse (p. 32)Success.

OPTIONS

Responses

Schemas

Response bodies

ListPlaybackConﬁgurationsResponse schema

{ "NextToken": "string", "Items": [

{

"Bumper": {

"StartUrl": "string", "EndUrl": "string"

(38)

Properties

},

"DashConfiguration": {

"ManifestEndpointPrefix": "string", "MpdLocation": "string",

"OriginManifestType": enum },

"SessionInitializationEndpointPrefix": "string", "CdnConfiguration": {

"AdSegmentUrlPrefix": "string", "ContentSegmentUrlPrefix": "string"

},

"ManifestProcessingRules": { "AdMarkerPassthrough": { "Enabled": boolean }

},

"PersonalizationThresholdSeconds": integer, "PlaybackConfigurationArn": "string", "LivePreRollConfiguration": {

"AdDecisionServerUrl": "string", "MaxDurationSeconds": integer },

"HlsConfiguration": {

"ManifestEndpointPrefix": "string"

},

"LogConfiguration": { "PercentEnabled": integer },

"VideoContentSourceUrl": "string", "Name": "string",

"tags": { },

"TranscodeProfileName": "string", "ConfigurationAliases": {

},

"AdDecisionServerUrl": "string", "PlaybackEndpointPrefix": "string", "SlateAdUrl": "string",

"AvailSuppression": { "Mode": enum, "Value": "string"

} } ] }

Properties

AdMarkerPassthrough

For HLS, when set to true, MediaTailor passes through EXT-X-CUE-IN, EXT-X-CUE-OUT, and EXT-X- SPLICEPOINT-SCTE35 ad markers from the origin manifest to the MediaTailor personalized manifest.

No logic is applied to these ad markers. For example, if EXT-X-CUE-OUT has a value of 60, but no ads are ﬁlled for that ad break, MediaTailor will not set the value to 0.

Enabled

Enables ad marker passthrough for your conﬁguration.

Type: boolean Required: False

(39)

Properties

AvailSuppression

The conﬁguration for avail suppression, also known as ad suppression. For more information about ad suppression, see Ad Suppression.

Mode

Sets the ad suppression mode. By default, ad suppression is off and all ad breaks are filled with ads or slate. When Mode is set to BEHIND_LIVE_EDGE, ad suppression is active and MediaTailor won't fill ad breaks on or behind the ad suppression Value time in the manifest lookback window.

Values: OFF | BEHIND_LIVE_EDGE

Value

A live edge offset time in HH:MM:SS. MediaTailor won't fill ad breaks on or behind this time in the manifest lookback window. If Value is set to 00:00:00, it is in sync with the live edge, and MediaTailor won't fill any ad breaks on or behind the live edge. If you set a Value time, MediaTailor won't fill any ad breaks on or behind this time in the manifest lookback window. For example, if you set 00:45:00, then MediaTailor will fill ad breaks that occur within 45 minutes behind the live edge, but won't fill ad breaks on or behind 45 minutes behind the live edge.

Bumper

The conﬁguration for bumpers. Bumpers are short audio or video clips that play at the start or before the end of an ad break. To learn more about bumpers, see Bumpers.

StartUrl

The URL for the start bumper asset.

EndUrl

The URL for the end bumper asset.

CdnConﬁguration

The conﬁguration for using a content delivery network (CDN), like Amazon CloudFront, for content and ad segment management.

AdSegmentUrlPreﬁx

A non-default content delivery network (CDN) to serve ad segments. By default, AWS Elemental MediaTailor uses Amazon CloudFront with default cache settings as its CDN for ad segments. To set up

(40)

Properties

an alternate CDN, create a rule in your CDN for the origin ads.mediatailor.<region>.amazonaws.com.

Then specify the rule's name in this AdSegmentUrlPreﬁx. When AWS Elemental MediaTailor serves a manifest, it reports your CDN as the source for ad segments.

ContentSegmentUrlPreﬁx

A content delivery network (CDN) to cache content segments, so that content requests don’t always have to go to the origin server. First, create a rule in your CDN for the content segment origin server. Then specify the rule's name in this ContentSegmentUrlPreﬁx. When AWS Elemental MediaTailor serves a manifest, it reports your CDN as the source for content segments.

ConﬁgurationAliasesResponse

The predeﬁned aliases for dynamic variables.

key-value pairs

Type: object

DashConﬁguration

The conﬁguration for DASH content.

ManifestEndpointPreﬁx

The URL generated by MediaTailor to initiate a playback session. The session uses server-side reporting.

This setting is ignored in PUT operations.

MpdLocation

The setting that controls whether MediaTailor includes the Location tag in DASH manifests. MediaTailor populates the Location tag with the URL for manifest update requests, to be used by players that don't support sticky redirects. Disable this if you have CDN routing rules set up for accessing MediaTailor manifests, and you are either using client-side reporting or your players support sticky HTTP redirects.

Valid values are DISABLED and EMT_DEFAULT. The EMT_DEFAULT setting enables the inclusion of the tag and is the default value.

OriginManifestType

The setting that controls whether MediaTailor handles manifests from the origin server as multi-period manifests or single-period manifests. If your origin server produces single-period manifests, set this to SINGLE_PERIOD. The default setting is MULTI_PERIOD. For multi-period manifests, omit this setting or set it to MULTI_PERIOD.

(41)

Properties

Values: SINGLE_PERIOD | MULTI_PERIOD

HlsConﬁguration

The conﬁguration for HLS content.

ManifestEndpointPreﬁx

The URL that is used to initiate a playback session for devices that support Apple HLS. The session uses server-side reporting.

ListPlaybackConﬁgurationsResponse

Returns a list of playback conﬁgurations.

NextToken

Pagination token returned by the GET list request when results exceed the maximum allowed. Use the token to fetch the next page of results.

Items

Array of playback configurations. This might be all the available configurations or a subset, depending on the settings that you provide and the total number of configurations stored.

Type: Array of type PlaybackConﬁguration (p. 37) Required: False

LivePreRollConﬁguration

The conﬁguration for pre-roll ad insertion.

AdDecisionServerUrl

The URL for the ad decision server (ADS) for pre-roll ads. This includes the specification of static parameters and placeholders for dynamic parameters. AWS Elemental MediaTailor substitutes player- specific and session-specific parameters as needed when calling the ADS. Alternately, for testing, you can provide a static VAST URL. The maximum length is 25,000 characters.

MaxDurationSeconds

The maximum allowed duration for the pre-roll ad avail. AWS Elemental MediaTailor won't play pre-roll ads to exceed this duration, regardless of the total duration of ads that the ADS returns.

(42)

Properties

LogConﬁguration

Returns Amazon CloudWatch log settings for a playback conﬁguration.

PercentEnabled

The percentage of session logs that MediaTailor sends to your Cloudwatch Logs account. For example, if your playback configuration has 1000 sessions and percentEnabled is set to 60, MediaTailor sends logs for 600 of the sessions to CloudWatch Logs. MediaTailor decides at random which of the playback configuration sessions to send logs for. If you want to view logs for a specific session, you can use the debug log mode.

Valid values: 0 - 100 Type: integer Required: True

ManifestProcessingRules

The conﬁguration for manifest processing rules. Manifest processing rules enable customization of the personalized manifests created by MediaTailor.

AdMarkerPassthrough

For HLS, when set to true, MediaTailor passes through EXT-X-CUE-IN, EXT-X-CUE-OUT, and EXT-X- SPLICEPOINT-SCTE35 ad markers from the origin manifest to the MediaTailor personalized manifest.

No logic is applied to these ad markers. For example, if EXT-X-CUE-OUT has a value of 60, but no ads are ﬁlled for that ad break, MediaTailor will not set the value to 0.

Type: AdMarkerPassthrough (p. 33) Required: False

PlaybackConﬁguration

Creates a playback configuration. For information about MediaTailor configurations, see Working with configurations in AWS Elemental MediaTailor.

Bumper

The conﬁguration for bumpers. Bumpers are short audio or video clips that play at the start or before the end of an ad break. To learn more about bumpers, see Bumpers.

Type: Bumper (p. 34) Required: False

DashConﬁguration

The conﬁguration for a DASH source.

Type: DashConﬁguration (p. 35) Required: False

(43)

Properties

SessionInitializationEndpointPreﬁx

The URL that the player uses to initialize a session that uses client-side reporting.

CdnConﬁguration

The conﬁguration for using a content delivery network (CDN), like Amazon CloudFront, for content and ad segment management.

Type: CdnConﬁguration (p. 34) Required: False

ManifestProcessingRules

The conﬁguration for manifest processing rules. Manifest processing rules enable customization of the personalized manifests created by MediaTailor.

Type: ManifestProcessingRules (p. 37) Required: False

PersonalizationThresholdSeconds

Defines the maximum duration of underfilled ad time (in seconds) allowed in an ad break. If the duration of underfilled ad time exceeds the personalization threshold, then the personalization of the ad break is abandoned and the underlying content is shown. This feature applies to ad replacement in live and VOD streams, rather than ad insertion, because it relies on an underlying content stream. For more information about ad break behavior, including ad replacement and insertion, see Ad Behavior in AWS Elemental MediaTailor.

Type: integer Required: False Minimum: 1

PlaybackConﬁgurationArn

The Amazon Resource Name (ARN) for the playback conﬁguration.

LivePreRollConﬁguration

The conﬁguration for pre-roll ad insertion.

Type: LivePreRollConﬁguration (p. 36) Required: False

HlsConﬁguration

The conﬁguration for HLS content.

Type: HlsConﬁguration (p. 36)

(44)

Properties

Required: False

LogConﬁguration

The Amazon CloudWatch log settings for a playback conﬁguration.

Type: LogConﬁguration (p. 37) Required: False

VideoContentSourceUrl

The URL preﬁx for the parent manifest for the stream, minus the asset ID. The maximum length is 512 characters.

Name

The identiﬁer for the playback conﬁguration.

tags

The tags to assign to the playback conﬁguration.

TranscodeProﬁleName

The name that is used to associate this playback configuration with a custom transcode profile. This overrides the dynamic transcoding defaults of MediaTailor. Use this only if you have already set up custom profiles with the help of AWS Support.

ConﬁgurationAliases

The player parameters and aliases used as dynamic variables during session initialization. For more information, see Domain Variables.

Type: ConﬁgurationAliasesResponse (p. 35) Required: False

AdDecisionServerUrl

The URL for the ad decision server (ADS). This includes the specification of static parameters and placeholders for dynamic parameters. AWS Elemental MediaTailor substitutes player-specific and session-specific parameters as needed when calling the ADS. Alternately, for testing you can provide a static VAST URL. The maximum length is 25,000 characters.

(45)

See also

PlaybackEndpointPreﬁx

The URL that the player accesses to get a manifest from AWS Elemental MediaTailor.

SlateAdUrl

The URL for a video asset to transcode and use to fill in time that's not used by ads. AWS Elemental MediaTailor shows the slate to fill in gaps in media content. Configuring the slate is optional for non- VPAID playback configurations. For VPAID, the slate is required because MediaTailor provides it in the slots designated for dynamic ad content. The slate must be a high-quality asset that contains both audio and video.

AvailSuppression

The conﬁguration for avail suppression, also known as ad suppression. For more information about ad suppression, see Ad Suppression.

Type: AvailSuppression (p. 34) Required: False

ListPlaybackConﬁgurations

• AWS SDK for C++

• AWS SDK for Go

ListPrefetchSchedules

Lists the prefetch schedules for a playback conﬁguration.

(46)

URI

/v1/prefetchSchedule/PlaybackConfigurationName

HTTP methods

POST

Operation ID: ListPrefetchSchedules Creates a new prefetch schedule.

Path parameters

PlaybackConfigurationNameString True The name of the playback conﬁguration.

Responses

200 ListPrefetchSchedulesResponse (p. 42)Success.

OPTIONS

Path parameters

PlaybackConfigurationNameString True The name of the playback conﬁguration.

Responses

Schemas

Request bodies

POST schema

{ "StreamId": "string", "NextToken": "string", "MaxResults": integer }

(47)

Properties

Response bodies

ListPrefetchSchedulesResponse schema

{ "NextToken": "string", "Items": [

{

"Consumption": {

"AvailMatchingCriteria": [ {

"Operator": enum,

"DynamicVariable": "string"

} ],

"EndTime": integer, "StartTime": integer },

"Retrieval": { "EndTime": integer, "StartTime": integer, "DynamicVariables": { }

},

"StreamId": "string", "Arn": "string",

"PlaybackConfigurationName": "string", "Name": "string"

} ]}

Properties

AvailMatchingCriteria

MediaTailor only places (consumes) prefetched ads if the ad break meets the criteria deﬁned by the dynamic variables. This gives you granular control over which ad break to place the prefetched ads into.

As an example, let's say that you set DynamicVariable to scte.event_id and Operator to EQUALS, and your playback conﬁguration has an ADS URL of https://my.ads.server.com/path?

&podId=[scte.avail_num]&event=[scte.event_id]&duration=[session.avail_duration_secs].

And the prefetch request to the ADS contains these values https://my.ads.server.com/path?

&podId=3&event=my-awesome-event&duration=30. MediaTailor will only insert the prefetched ads into the ad break if has a SCTE marker with an event id of my-awesome-event, since it must match the event id that MediaTailor uses to query the ADS.

You can specify up to ﬁve AvailMatchingCriteria. If you specify multiple

AvailMatchingCriteria, MediaTailor combines them to match using a logical AND. You can model logical OR combinations by creating multiple prefetch schedules.

Operator

For the DynamicVariable speciﬁed in AvailMatchingCriteria, the Operator that is used for the comparison.

Type: string Required: True Values: EQUALS

(48)

Properties

DynamicVariable

The dynamic variable(s) that MediaTailor should use as avail matching criteria. MediaTailor only places the prefetched ads into the avail if the avail matches the criteria deﬁned by the dynamic variable. For information about dynamic variables, see Using dynamic ad variables in the MediaTailor User Guide.

You can include up to 100 dynamic variables.

ListPrefetchSchedulesRequest

Retrieves the prefetch schedule(s) for a speciﬁc playback conﬁguration.

StreamId

An optional filtering parameter whereby MediaTailor filters the prefetch schedules to include only specific streams.

NextToken

(Optional) If the playback conﬁguration has more than MaxResults prefetch schedules, use NextToken to get the second and subsequent pages of results.

For the ﬁrst ListPrefetchSchedulesRequest request, omit this value.

For the second and subsequent requests, get the value of NextToken from the previous response and specify that value for NextToken in the request.

If the previous response didn't include a NextToken element, there are no more prefetch schedules to get.

MaxResults

The maximum number of prefetch schedules that you want MediaTailor to return in response to the current request. If the playback conﬁguration has more than MaxResults prefetch schedules, use the value of NextToken in the response to get the next page of results.

Type: integer Required: False Minimum: 1 Maximum: 100

ListPrefetchSchedulesResponse

The list of prefetch schedules.

NextToken

The value that you will use forNextToken in the next ListPrefetchSchedulesRequest request.

(49)

Properties

Items

Lists the prefetch schedules. An empty Items list doesn't mean there aren't more items to fetch, just that that page was empty.

Type: Array of type PrefetchSchedule (p. 45) Required: True

PrefetchConsumption

A complex type that contains settings that determine how and when that MediaTailor places prefetched ads into upcoming ad breaks.

AvailMatchingCriteria

If you only want MediaTailor to insert prefetched ads into avails (ad breaks) that match speciﬁc dynamic variables, such as scte.event_id, set the avail matching criteria.

Type: Array of type AvailMatchingCriteria (p. 42) Required: False

EndTime

The time when MediaTailor no longer considers the prefetched ads for use in an ad break. MediaTailor automatically deletes prefetch schedules no less than seven days after the end time. If you'd like to manually delete the prefetch schedule, you can call DeletePrefetchSchedule.

Type: integer Required: True Format: date-time

StartTime

The time when prefetched ads are considered for use in an ad break. If you don't specify StartTime, the prefetched ads are available after MediaTailor retrives them from the ad decision server.

PrefetchRetrieval

A complex type that contains settings governing when MediaTailor prefetches ads, and which dynamic variables that MediaTailor includes in the request to the ad decision server.

EndTime

The time when prefetch retrieval ends for the ad break. Prefetching will be attempted for manifest requests that occur at or before this time.

Type: integer Required: True

(50)

Properties

Format: date-time

StartTime

The time when prefetch retrievals can start for this break. Ad prefetching will be attempted for manifest requests that occur at or after this time. Defaults to the current time. If not speciﬁed, the prefetch retrieval starts as soon as possible.

DynamicVariables

The dynamic variables to use for substitution during prefetch requests to the ad decision server (ADS).

You intially conﬁgure dynamic variables for the ADS URL when you set up your playback conﬁguration.

When you specify DynamicVariables for prefetch retrieval, MediaTailor includes the dynamic variables in the request to the ADS.

PrefetchSchedule

A complex type that contains prefetch schedule information.

Consumption

Consumption settings determine how, and when, MediaTailor places the prefetched ads into ad breaks.

Ad consumption occurs within a span of time that you deﬁne, called a consumption window. You can designate which ad breaks that MediaTailor ﬁlls with prefetch ads by setting avail matching criteria.

Type: PrefetchConsumption (p. 44) Required: True

Retrieval

A complex type that contains settings for prefetch retrieval from the ad decision server (ADS).

Type: PrefetchRetrieval (p. 44) Required: True

StreamId

An optional stream identiﬁer that you can specify in order to prefetch for multiple streams that use the same playback conﬁguration.

Arn

The Amazon Resource Name (ARN) of the prefetch schedule.

AWS Elemental MediaTailor

AWS Elemental MediaTailor

API Reference

AWS Elemental MediaTailor: API Reference

Table of Contents

AWS Elemental MediaTailor API

Specifying the REST API Endpoint

Signing Requirements

Resources

Channel

URI

HTTP methods

GET

Path parameters

Responses

POST

Path parameters

Responses

PUT

Path parameters

Responses

DELETE

Path parameters

Responses

OPTIONS

Path parameters

Responses

Schemas

Request bodies

Response bodies

Properties

CreateChannelRequest

FillerSlate

Outputs

PlaybackMode

tags

DashPlaylistSettings

ManifestWindowSeconds

SuggestedPresentationDelaySeconds

MinBuﬀerTimeSeconds

MinUpdatePeriodSeconds

DeleteChannelResponse

DescribeChannelResponse

FillerSlate

ChannelState

ChannelName

CreationTime

LastModiﬁedTime

Outputs

Arn

PlaybackMode

tags

HlsPlaylistSettings

ManifestWindowSeconds

RequestOutputItem

ManifestName

DashPlaylistSettings

HlsPlaylistSettings

SourceGroup

ResponseOutputItem

ManifestName

DashPlaylistSettings

PlaybackUrl

HlsPlaylistSettings

SourceGroup

SlateSource

VodSourceName

SourceLocationName

UpdateChannelRequest

FillerSlate

Outputs

See also

DescribeChannel

CreateChannel

UpdateChannel

DeleteChannel

ChannelPolicy

URI

HTTP methods

GET