本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# ADS 請求的 MediaTailor 工作階段變數
<a name="variables-session"></a>

AWS Elemental MediaTailor 當您設定 AWS Elemental MediaTailor 在範本 ADS URL 中指定本節中列出的一或多個變數時， 會將工作階段資料傳送至廣告決策伺服器 (ADS)。您可以使用個別變數，也可以串連多個變數來建立單一值。MediaTailor 會產生一些值，並從資訊清單和玩家的工作階段初始化請求等來源取得其餘值。

下表說明您可以在範本 ADS 請求 URL 組態中使用的工作階段資料變數。表格中列出的區段編號對應至 2019a 版本的纜線電信工程師協會 (SCTE)-35 規格、[數位節目插入提示訊息](https://account.scte.org/standards/library/catalog/scte-35-digital-program-insertion-cueing-message/)，如需廣告預先擷取的詳細資訊，請參閱 [預先擷取廣告](prefetching-ads.md)。


| 名稱 | 可用於廣告預先擷取 | SCTE-35 規格區段 | Description | 
| --- | --- | --- | --- | 
| [avail.index] | 是 |  | 代表索引中廣告時段位置的數字。在播放工作階段開始時，MediaTailor 會在資訊清單中建立所有廣告時段的索引，並儲存工作階段其餘部分的索引。當 MediaTailor 向 ADS 提出請求以填滿時段時，它會包含廣告時段索引號碼。此參數可讓 ADS 使用競爭排除和頻率上限等功能，改善廣告選擇。 | 
| [avail.random] | 是 |  | MediaTailor 為每個 ADS 請求產生的介於 0 到 10，000，000，000 之間的隨機數字作為長數字。有些廣告伺服器使用此參數來啟用功能，例如區隔競爭公司的廣告。 | 
| [scte.archive\$1allowed\$1flag] | 是 | 10.3.3.1 | 選用的布林值。當此值為 0 時，會在區段上宣告記錄限制。當此值為 1 時，不會在區段上宣告記錄限制。 | 
| [scte.avail\$1num] | 是 | 9.7.2.1 | MediaTailor 從 SCTE-35 欄位 剖析的值avail\$1num，以長數字表示。MediaTailor 可以使用此值來指定線性廣告時段號碼。值必須是整數。 | 
| [scte.avails\$1expected] | 是 | 9，7.2.1 | 選用的長值，提供目前事件內的預期時段計數。 | 
| [scte.delivery\$1not\$1restricted\$1flag] | 是 | 10.3.3.1 | 選用的布林值。當此值為 0 時，會保留接下來的五個位元。當此值為 1 時，接下來的五個位元會採用 SCTE-35 規格中所述的意義。 | 
| [scte.device\$1restrictions] | 是 | 10.3.3.1 | 選用整數值，可發出三個預先定義、獨立和非階層的裝置群組訊號。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 segment\$1expected 描述。 | 
| [scte.event\$1id] | 是 | 9.1 和 9.7.2.1 | MediaTailor 從 SCTE-35 欄位 剖析的值splice\$1event\$1id，以長數字表示。MediaTailor 使用此值來指定線性廣告時段號碼或填入廣告伺服器查詢字串，例如廣告裝置位置。值必須是整數。 | 
| [scte.no\$1regional\$1blackout\$1flag] | 是 | 10.3.3.1 | 選用的布林值。當此值為 0 時，區域中斷限制適用於區段。當此值為 1 時，區域中斷限制不適用於區段。 | 
| [scte.segment\$1num] | 是 | 10.3.3.1 | 選用整數值，可對區段集合中的區段進行編號。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 segment\$1num 描述。 | 
| [scte.segmentation\$1event\$1id]  | 是 | 10.3.3.1 | MediaTailor 將此變數公開為 [scte.event_id](#scte.event_id)。 | 
| [scte.segmentation\$1type\$1id] | 是 | 10.3.3.1 | 指定分割類型的選用 8 位元整數值。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 segmentation\$1type\$1id 說明。 | 
| [scte.segmentation\$1upid] |  `segmentation_upid_type`：是 `private_data`：是  |  **segmentation\$1upid**：10.3.3.1 受管私有 UPID：10.3.3.3  |  對應至 SCTE-35 `segmentation_upid`元素。`segmentation_upid` 元素包含 `segmentation_upid_type`和 `segmentation_upid_length`。 MediaTailor 支援下列`segmentation_upid`類型： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/variables-session.html)  | 
| [scte.segmentation\$1upid.assetId] | 是 |  | 與 Podbuster 工作流程segmentation\$1 upid\$1type的受管私有 UPID (0xC) 搭配使用。MediaTailor 會從 MPU 的 private\$1data JSON 結構中的 assetId 參數衍生此值。如需詳細資訊，請參閱[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)。 | 
| [scte.segmentation\$1upid.cueData.key] | 是 |  | 與 Podbuster 工作流程segmentation\$1 upid\$1type的受管私有 UPID (0xC) 搭配使用。MediaTailor 會從 MPU 的 private\$1data JSON 結構中的 cueData.key 參數衍生此值。如需詳細資訊，請參閱[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)。 | 
| [scte.segmentation\$1upid.cueData.value] | 是 |  | 與 Podbuster 工作流程segmentation\$1 upid\$1type的受管私有 UPID (0xC) 搭配使用。MediaTailor 會從 MPU 的 private\$1data JSON 結構中的 cueData.key 參數衍生此值。如需詳細資訊，請參閱[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)。值可以是字串。 | 
| [scte.segmentation\$1upid.private\$1data.\$1index\$1] | 是 |  | 搭配 受管私有 UPID (0xC) segmentation\$1upid\$1type用於目標式廣告工作流程。MediaTailor 會分割冒號分隔的分段 UPID 權杖，並建立索引工作階段變數。索引對應於冒號分隔清單中的位置，忽略初始冒號的前導空格。例如，如果 `segmentation_upid = ":3213214:2313321/5:3943"`，則： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/variables-session.html) 值可以是字串。 | 
| [scte.segments\$1expected] | 是 | 10.3.3.1 | 選用整數值，提供區段集合中個別區段的預期計數。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 segment\$1expected 描述。 | 
| [scte.sub\$1segment\$1num] | 是 | 10.3.3.1 | 選用整數值，可識別子區段集合中的特定子區段。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 sub\$1segment\$1num 說明。 | 
| [scte.sub\$1segments\$1expected] | 是 | 10.3.3.1 | 選用整數值，提供子區段集合中個別子區段的預期計數。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 sub\$1segments\$1expected 描述。 | 
| [scte.unique\$1program\$1id] | 是 | 9.7.2.1 | MediaTailor 從 SCTE-35 splice\$1insert 欄位 剖析的整數值unique\$1program\$1id。ADS 會使用唯一計畫 ID (UPID) 以提供鎖定即時線性串流的計畫層級廣告。如果 SCTE-35 命令不是接合插入，MediaTailor 會將此值設為空值。值必須是整數。 | 
| [session.avail\$1duration\$1ms] | 是 |  |  廣告可用性插槽的持續時間，以毫秒為單位。預設值為 300，000 毫秒。從輸入資訊清單中 AWS Elemental MediaTailor 取得持續時間值，如下所示： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/variables-session.html)  | 
| [session.avail\$1duration\$1secs] | 是 |  | 廣告時段或廣告時段的持續時間，以秒為單位，四捨五入至最接近的秒數。MediaTailor 決定此值的方式與決定 的方式相同[session.avail\$1duration\$1ms]。 | 
| [session.client\$1ip] | 否 |  | MediaTailor 請求來自的遠端 IP 地址。如果已設定 X-forwarded-for標頭，則該值是 MediaTailor 用於 的值client\$1ip。 | 
| [session.id] | 否 |  | 目前播放工作階段的唯一數字識別符。播放器對工作階段提出的所有請求會具有相同的 ID，因此它可用於預期要與請求關聯以獲得單一檢視的 ADS 欄位。 | 
| [session.referer] | 否 |  | 通常，託管影片播放器的頁面 URL。MediaTailor 將此變數設定為播放器在對 MediaTailor 的請求中使用的Referer標頭值。如果播放器不提供此標頭，MediaTailor 會保留[session.referer]空白。如果您在資訊清單端點前面使用內容交付網路 (CDN) 或代理，並且希望此變數出現，請在此處從玩家代理正確的標頭。 | 
| [session.user\$1agent] | 否 |  | MediaTailor 從玩家的工作階段初始化請求收到的User-Agent標頭。如果您在資訊清單端點之前使用 CDN 或 Proxy，您必須從此處的播放器代理正確的標頭。 | 
| [session.uuid] | 否 |  |  替代 **[session.id]**。這是目前播放工作階段的唯一識別符，例如以下： <pre>e039fd39-09f0-46b2-aca9-9871cc116cde</pre>  | 
| [avail.source\$1content\$1time\$1epoch\$1ms] | 否 |  |  對於 HLS，該值是啟動時段之原始客群的 PDT。對於 DASH， 值是`<Period>`包含 `<SupplementalProperty> urn:scte:dash:utc-time`的 的 `<EventStream>`。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/variables-session.html)  | 

**Example**  
如果 ADS 需要名為 `deviceSession` 的查詢參數來傳遞工作階段的唯一識別符，則 AWS Elemental MediaTailor 中的範本 ADS URL 看起來可能如下所示：  

```
https://my.ads.server.com/path?deviceSession=[session.id]
```
AWS Elemental MediaTailor 會自動為每個串流產生唯一識別符，並輸入識別符來取代 `session.id`。如果識別符為 `1234567`，MediaTailor 對 ADS 提出的最終請求會如下所示：  

```
https://my.ads.server.com/path?deviceSession=1234567
```
如果 ADS 需要傳遞多個查詢參數， 中的範本 ADS URL AWS Elemental MediaTailor 可能如下所示：  

```
https://my.ads.server.com/sample?e=[scte.avails_expected]&f=[scte.segment_num]&g=[scte.segments_expected]&h=[scte.sub_segment_num]&j=[scte.sub_segments_expected]&k=[scte.segmentation_type_id]
```
下列 DASH 標記範例 XML 片段示範如何使用 `scte35:SpliceInsert`：  

```
<Period start="PT444806.040S" id="123456" duration="PT15.000S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="1350000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
        <scte35:SpliceInsert spliceEventId="1234567890" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
          <scte35:Program><scte35:SpliceTime ptsTime="5672624400"/></scte35:Program>
          <scte35:BreakDuration autoReturn="true" duration="1350000"/>
        </scte35:SpliceInsert>
      </scte35:SpliceInfoSection>
```
下列 DASH 標記範例 XML 片段示範如何使用 `scte35:TimeSignal`：  

```
<Period start="PT346530.250S" id="123456" duration="PT61.561S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="5310000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="183003" tier="4095">
        <scte35:TimeSignal>
          <scte35:SpliceTime ptsTime="3442857000"/>
        </scte35:TimeSignal>
        <scte35:SegmentationDescriptor segmentationEventId="1234567" segmentationEventCancelIndicator="false" segmentationDuration="8100000" segmentationTypeId="52" segmentNum="0" segmentsExpected="0">
          <scte35:DeliveryRestrictions webDeliveryAllowedFlag="false" noRegionalBlackoutFlag="false" archiveAllowedFlag="false" deviceRestrictions="3"/>
          <scte35:SegmentationUpid segmentationUpidType="12" segmentationUpidLength="2">0100</scte35:SegmentationUpid>
        </scte35:SegmentationDescriptor>
      </scte35:SpliceInfoSection>
    </Event>
```
下列 DASH 標記範例 XML 片段示範如何使用 `scte35:Binary`：  

```
<Period start="PT444806.040S" id="123456" duration="PT15.000S">
  <EventStream schemeIdUri="urn:scte:scte35:2014:xml+bin" timescale="1">
    <Event presentationTime="1541436240" duration="24" id="29">
      <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
        <scte35:Binary>/DAhAAAAAAAAAP/wEAUAAAHAf+9/fgAg9YDAAAAAAAA25aoh</Binary>
      </scte35:Signal>
    </Event>
    <Event presentationTime="1541436360" duration="24" id="30">
      <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
        <scte35:Binary>QW5vdGhlciB0ZXN0IHN0cmluZyBmb3IgZW5jb2RpbmcgdG8gQmFzZTY0IGVuY29kZWQgYmluYXJ5Lg==</Binary>
      </scte35:Signal>
    </Event>
```
下列 HLS 標籤範例示範如何使用 `EXT-X-DATERANGE`：  

```
#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2014-03-05T11:
15:00Z",PLANNED-DURATION=59.993,SCTE35-OUT=0xFC002F0000000000FF0
00014056FFFFFF000E011622DCAFF000052636200000000000A0008029896F50
000008700000000
```
下列 HLS 標籤範例示範如何使用 `EXT-X-CUE-OUT`：  

```
#EXT-OATCLS-SCTE35:/DA0AAAAAAAAAAAABQb+ADAQ6QAeAhxDVUVJQAAAO3/PAAEUrEoICAAAAAAg+2UBNAAANvrtoQ==  
#EXT-X-ASSET:CAID=0x0000000020FB6501  
#EXT-X-CUE-OUT:201.467
```
下列 HLS 標籤範例示範如何使用 `EXT-X-SPLICEPOINT-SCTE35`：  

```
#EXT-X-SPLICEPOINT-SCTE35:/DA9AAAAAAAAAP/wBQb+uYbZqwAnAiVDVUVJAAAKqX//AAEjW4AMEU1EU05CMDAxMTMyMjE5M19ONAAAmXz5JA==
```
下列範例示範如何使用`scte35:Binary`解碼：  

```
{
  "table_id": 252,
  "section_syntax_indicator": false,
  "private_indicator": false,
  "section_length": 33,
  "protocol_version": 0,
  "encrypted_packet": false,
  "encryption_algorithm": 0,
  "pts_adjustment": 0,
  "cw_index": 0,
  "tier": "0xFFF",
  "splice_command_length": 16,
  "splice_command_type": 5,
  "splice_command": {
    "splice_event_id": 448,
    "splice_event_cancel_indicator": false,
    "out_of_network_indicator": true,
    "program_splice_flag": true,
    "duration_flag": true,
    "splice_immediate_flag": false,
    "utc_splice_time": {
      "time_specified_flag": false,
      "pts_time": null
    },
    "component_count": 0,
    "components": null,
    "break_duration": {
      "auto_return": false,
      "duration": {
        "pts_time": 2160000,
        "wall_clock_seconds": 24.0,
        "wall_clock_time": "00:00:24:00000"
      }
    },
    "unique_program_id": 49152,
    "avail_num": 0,
    "avails_expected": 0
    "segment_num": 0,
    "segments_expected": 0,
    "sub_segment_num": 0,
    "sub_segments_expected": 0
  },
  "splice_descriptor_loop_length": 0,
  "splice_descriptors": null,
  "Scte35Exception": {
    "parse_status": "SCTE-35 cue parsing completed with 0 errors.",
    "error_messages": [],
    "table_id": 252,
    "splice_command_type": 5
  }
}
```