Pod Serving API 目前處於封閉測試階段。如要進一步瞭解 Pod 服務，或是想要導入 Pod Serving API，請與您的 Google 客戶經理聯絡。

本頁面由 Cloud Translation API 翻譯而成。

VOD 串流資訊清單操控器

Pod Serving API 提供可自動調整位元率的影片廣告連播存取權且可直接合成至面向使用者的 HTTP 即時串流 MPEG-DASH 媒體播放清單。

本指南的重點在於實作基本的 Pod 供應資訊清單操控 VOD 串流服務的伺服器

接收串流資訊清單要求

資訊清單操縱器必須提供 API 端點，才能監聽資訊清單來自影片播放器用戶端應用程式的廣告請求您至少必須使用這個端點從用戶端播放器應用程式收集串流 ID這個串流 ID 的用途是在廣告連播請求中指明向 Ad Manager 發送的串流工作階段。

您還需要收集其他資訊， Content ID 就是內容串流

資訊清單要求端點範例

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}

路徑參數

stream_id 用戶端影片播放器應用程式中的 Ad Manager 串流 ID。

content_id 與系統中內容影片相對應的假設 ID。

format

與串流格式相對應的假設參數。下列其中一項：

`mpd`	適用於 MPEG-DASH 串流
`m3u8`	HTTP 即時串流串流

擷取內容串流

使用從資訊清單要求中收集到的內容 ID 選取內容再搭配廣告拼接

請求廣告連播資訊清單

若要向 Ad Manager 請求廣告，您的伺服器必須向廣告提出 POST 要求廣告聯播端點，傳遞所請求的編碼設定檔、廣告代碼和指定目標參數。這項要求也含有您在步驟中收集到的串流 ID 1.

您會在報表內收到廣告連播物件清單，其中包含以下項目的資訊清單檔案：由發布商的廣告代碼要求的廣告連播，以及適合插入內容的位置

POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json

路徑參數
`network_code`	發布商的 Ad Manager 360 聯播網代碼。
`stream_id`	用戶端影片播放器應用程式的串流 ID。

JSON 內文

內文參數
`encoding_profiles`	`Required`	您要接收的編碼設定檔的 JSON 表示法清單各個廣告插播時間點詳情請見下文為了讓系統盡可能流暢地播放內容，這個字串應符合內容串流中使用的編碼設定檔
`ad_tag`	`Required`	請求 VMAP 廣告的廣告代碼。
`cuepoints`	`Optional`	內容串流中的提示點清單，其中會插播片中廣告插入文字提示點的測量單位為浮點秒數。只有在 VMAP 回應包含片中廣告時，才需要填寫位置時間偏移。這很罕見。注意：請參閱 IAB 的 VMAP 標準第 2.3.1 節，進一步瞭解時間偏移類型。
`content_duration_seconds`	`Optional`	內容時間長度 (以秒為單位)。只有在 VMAP 回應包含片中廣告時，才需要填寫 percentage 時間偏移。這很罕見。注意：請參閱 IAB 的 VMAP 標準第 2.3.1 節，進一步瞭解時間偏移類型。
`manifest_type`	`Optional`	所請求的廣告串流格式，可以是 `hls` 或 `dash`。預設值為 `hls`。
`dai_options`	`Optional`	控制資訊清單算繪方式的其他選項。詳情請見下文
編碼設定檔
`profile_name`	`Required`	此編碼設定檔的 ID。這個值可以是任何字串，但您不能擁有多個名稱相同的編碼設定檔同一個串流。
`type`	`Required`	此編碼設定檔描述的串流編碼類型。內容類型包括：`media`、`iframe`、`subtitles`。
`container_type`	`Required`	此編碼設定檔使用的容器格式。容器格式如下： `mpeg2ts`、`fmp4cmaf`、`hls_packed_audio` 注意：片段處理的 MP4 設定檔必須 demuxed。此外，如果 `manifest_type` 為 `dash`， `container_type` 必須是 `fmp4cmaf`。
`video_settings`	`Optional`	如果編碼設定檔類型為 iframe，則為必要欄位。否則只有在媒體類型包含影片的情況下才能使用。詳情請參閱詳情
`audio_settings`	`Optional`	如果編碼設定檔含有音訊，則為必要欄位。只有在類型為媒體。詳情請見下文
`subtitle_settings`	`Optional`	如果編碼設定檔包含字幕，則為必要欄位。詳情請見下文
影片設定
`codec`	`Required`	RFC6381 轉碼器字串。範例：`avc1.4d000c`
`bitrate`	`Required`	一個整數，代表這個設定檔的影片位元率上限，以位元組為單位。第二。
`frames_per_second`	`Required`	影片的浮點每秒影格數。
`resolution`	`Required`	包含影片「寬度」和「高度」(以像素為單位) 的 JSON 編碼值。範例：`{"width": 640, "height": 320}`
音訊設定
`codec`	`Required`	RFC6381 轉碼器字串。範例：`mp4a.40.5`
`bitrate`	`Required`	一個整數，代表這個設定檔的音訊位元率上限，以位元組為單位。第二。範例：`300000`
`channels`	`Required`	整數，代表音訊聲道數 (包括低頻率) 頻道。
`sample_rate`	`Required`	一個整數，代表赫茲中的音訊取樣率。範例：`4800`
字幕設定
`format`	`Required`	頻內字幕使用的檔案格式。支援的值如下： `webvtt` 或 `ttml`。
`language`	`Optional`	以 RFC5646 語言字串表示的字幕語言。如有提供，這個值僅適用於 DASH 轉譯。範例：`en-us`
DAI 選項
`dash_profile`	`Optional`	要套用至廣告連播資訊清單的 MPEG-DASH 設定檔。這項設定適用於僅限 DASH 資訊清單。允許的值為 `live` 或 `on-demand`。預設值為 `on-demand`。 `live` 值對應 MPEG-DASH 設定檔 `"urn:mpeg:dash:profile:isoff-live:2011"`。 `on-demand` 值對應 MPEG-DASH 設定檔 `urn:mpeg:dash:profile:isoff-on-demand:2011`。注意：儘管名稱為何，`live` 設定檔可以只會套用至隨選影片內容這通常是用於直播活動的影片封存檔。
`ad_pod_timeout`	`Optional`	浮動選取廣告和建立廣告連播的時間上限點的秒數這段時間過後，Ad Manager 會傳回已在`ad_pods`回應中選取相關廣告，且將停止和資料處理之間
`sam_id`	`Optional`	指定替代的偵錯鍵，可用於查詢以下項目中的工作階段：串流活動監控

回應

回應參數
`valid_for`	這些廣告連播播放清單在 `dhms` 中的有效期間 (天、小時、分鐘、秒) 格式。
`valid_until`	這些廣告連播播放清單視為 ISO8601 的有效日期和時間日期時間字串，位於 `yyyy-MM-dd'T'hh:mm:ss.sssssssss[+\|-]hh:mm` 格式。
`ad_pods`	為這個串流選取的廣告連播清單。
廣告連播
`manifest_uris`	僅適用於 HTTP 即時串流串流。將設定檔 ID 編碼和 HLS 資訊清單 URI 的對應。
`mpd_uri`	僅適用於 DASH 串流。DASH MPD 的 URI。
`type`	廣告連播的類型。廣告連播類型為：`pre`、`mid` 或 `post`。
`start`	僅適用於片中廣告連播。這個廣告連播在串流中的位置應該以浮點秒為單位。
`duration`	此廣告連播的時間長度 (以浮點秒為單位)。
`midroll_index`	僅適用於片中廣告連播。目前片中廣告連播的索引。建立索引開頭為 `1`。

要求範例 (cURL)

curl -X POST \
     -d '@request-body.json' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/streams/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/adpods

要求主體範例

這是上述 cURL 呼叫中參照的 request-body.json 內容。

{
  "encoding_profiles": [
   {
     "profile_name": "1080p",
     "type": "media",
     "container_type": "mpeg2ts",
     "video_settings": {
       "codec": "avc1.4d000c",
       "bitrate": 5000000,
       "frames_per_second": 30.0,
       "resolution": {
         "width": 1920,
         "height": 1080
       }
     },
     "audio_settings": {
       "codec": "mp4a.40.5",
       "bitrate": 300000,
       "channels": 2,
       "sample_rate": 48000
     }
   },
   {
     "profile_name": "360p",
     "type": "media",
     "container_type": "mpeg2ts",
     "video_settings": {
       "codec": "avc1.4d000d",
       "bitrate": 1000000,
       "frames_per_second": 30.0,
       "resolution": {
         "width": 640,
         "height": 360
       }
     },
     "audio_settings": {
       "codec": "mp4a.40.5",
       "bitrate": 64000,
       "channels": 2,
       "sample_rate": 48000
     }
   },
   {
     "profile_name": "subtitles-webvtt",
     "type": "subtitles",
     "subtitle_settings": {
       "format": "webvtt"
     }
   }
 ],
 "ad_tag": "https://pubads.g.doubleclick.net/gampad/ads?...",
 "manifest_type": "hls"
}

回應範例

{
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00",
  "ad_pods": [
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/0/profile/1080p.m3u8",
        "360p": "https://{...}/pod/0/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt"
      },
      "type": "pre",
      "duration": 10.0
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/1/profile/1080p.m3u8",
        "360p": "https://{...}/pod/1/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/1/profile/subtitles-en.vtt"
      },
      "type": "mid",
      "start": 15.0,
      "duration": 15.0,
      "midroll_index": 1
    },
    {
      "manifest_urls":{
        ]"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
        "360p": "https://{...}/pod/2/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt""
      },
      "type": "post",
      "duration": 10.0
    }
  ]
}

將廣告連播合併到內容

將廣告連播合併到內容串流中的程序，詳細導入作業、串流格式，以及你選擇使用哪些功能從格式規格中實作下列工作流程有關處理此程序的建議。模型的具體細節導入方式可能會因您的業務需求和內容而有所差異串流。

HTTP 即時串流串流

如果你併接採用 HLS 格式的串流，內容串流就會是多變化版本播放清單成獨立串流資訊清單的連結，每個編碼設定檔各有一個連結。您的廣告 Pod 都需要插入每個變數資訊清單。單向做法是備妥所有變化版本資訊清單，並傳遞至傳遞網路 (CDN) 代管服務。最終的多變化版本播放清單是一組連結，可連至這些 CDN 代管資訊清單。

對編碼設定檔進行疊代

針對每個編碼設定檔，收集所有相關廣告連播資訊清單 Ad Manager 回應及相關聯的開始時間。適用於片頭廣告請將開始時間設為 0。如果是片尾廣告，請將內容的時間長度設為廣告連播的開始時間識別多變化版本中的變化版本串流符合每個編碼設定檔音訊與視訊設定的播放清單。

廣告連播陣列範例

"ad_pods": [
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/0/profile/1080p.m3u8",
        "360p": "https://{...}/pod/0/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/0/profile/subitles-en.vtt"
      },
      "type": "pre",
      "duration": 10.0
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/1/profile/1080p.m3u8",
        "360p": "https://{...}/pod/1/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/1/profile/subitles-en.vtt"
      },
      "type": "mid",
      "start": 15.0,
      "duration": 15.0,
      "midroll_index": 1
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/2/profile/1080p.m3u8",
        "360p": "https://{...}/pod/2/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/2/profile/subitles-en.vtt"
      },
      "type": "post",
      "duration": 10.0
    }
  ]

多變化版本內容播放清單範例

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://{...}/subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://{...}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://{...}/360p.m3u8

系統收集的變化版本資料範例

Encoding profile: "1080p"
Profile settings: {...}
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
    0 -> https://{...}/pod/0/profile/1080p.m3u8
   15 -> https://{...}/pod/1/profile/1080p.m3u8
  600 -> https://{...}/pod/2/profile/1080p.m3u8

在各個變化版本資訊清單中插入廣告

針對每個變化版本串流，檢查內容資訊清單的區隔，所經過的內容總時間。當您返回起始位置時從廣告連播清單中擷取區隔清單，然後在兩個 #EXT-X-DISCONTINUITY 標記中插入區隔清單內容資訊清單中的目前位置繼續這個程序，直到所有廣告 Pod 和變化版本串流已處理完成

產生的資訊清單必須符合 HTTP 即時串流標準。因此，您確定內容資訊清單包含哪些規格功能，您可能需要針對合併的資訊清單進行最終檢查，才能修正媒體問題序號、內容長度、不連續序號，以及任何其他代碼需要更新，以便將新的廣告區隔納入考量。修正與標準有所差異後使用者專屬的變化版本資訊清單，並傳送至您的 CDN 進行代管。

如果內容資訊清單已加密，請儲存最後一項加密鍵。#EXT-X-KEY接著：您需要先新增標記 #EXT-X-KEY:METHOD=NONE，才能移除加密。每個廣告連播的第一個區隔最後，您必須新增儲存的每個廣告連播後，在內容第一個區段前 #EXT-X-KEY 標記，並還原內容加密

系統收集的變化版本資料範例

Encoding profile: "1080p"
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
    0 -> https://dai.google.com/{...}pod/0/profile/1080p.m3u8
   15 -> https://dai.google.com/{...}pod/1/profile/1080p.m3u8
  600 -> https://dai.google.com/{...}pod/2/profile/1080p.m3u8

內容資訊清單範例

這是列於 https://{...}/1080p.m3u8 資訊清單的內容收集的變化版本資料

#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}

廣告連播資訊清單範例

這是 https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 資訊清單列出的變化版本資料

#EXTM3U
{...}
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts

拼接的變化版本資訊清單範例

這就是生成的拼接變化版本資訊清單，並傳遞至 CDN 代管於 https://cdn.{...}/{userid}/1080p.m3u8。

#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}

建立多變化版本播放清單

收集每個已完成的變體資訊清單的 CDN 位址，以及比對編碼設定檔詳細資料，並將結果組合成新的多變數資訊清單。系統會傳回這個使用者專屬的資訊清單做為回應加入您在步驟 1 收到的資訊清單要求。

最終多變化版本播放清單範例

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://cdn.{...}-subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://cdn.{...}/{userid}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://cdn.{...}/{userid}/360p.m3u8

MPEG DASH 串流

如果要以 MPEG DASH 格式合併串流，只需產生單一檔案因此，DASH 串流比 HTTP 即時串流更容易合併。

正確準備的 MPEG DASH 媒體顯示說明 (MPD) 檔案，由多個時段組成，每個時段都包含多種表示法。每項表示法應該會與其中一個編碼設定檔相符。每個廣告連播傳回也是個 MPD 檔案，其中包含一系列比對表示法

如要同時拼接這些 MPD 檔案，請先記下每個廣告連播如果是片頭廣告，請在任何內容前插入片頭廣告連播時段。如果是片尾廣告，請在所有內容後方插入片尾廣告連播時段。反覆執行 MPD 內容時段，持續追蹤所有已處理內容時段的播放時間。抵達邊界時找出與廣告連播開始時間相對應的時段，然後在當中插入相應邊界的對應片中廣告 MPD 檔案

最終拼接的 MPD 檔案必須完全符合 MPEG_DASH 規格。因此您可能需要反覆修改最終的檔案調整媒體的顯示時間長度，並解決其他任何可能產生的衝突。

MPD 範例內容

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M00.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Example Stream</Title>
  </ProgramInformation>
  <Period duration="PT0H0M15.000S" id="content-period-1">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-2">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-3">
    ...
  </Period>
  ...
</MPD>

廣告連播 JSON 範例

[{
  "mpd_uri": "https://{...}pod/1.mpd",
  "type": "mid",
  "start": 15.0,
  "duration": 15.0,
  "midroll_index": 1
}]

廣告連播 MPD 範例

這是上述廣告連播 JSON 中的 mpd_uri 內容。

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H0M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Ad Pod 1</Title>
  </ProgramInformation>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
    ...
  </Period>
  ...
</MPD>

拼接的 MPD 範例

做為您對初始串流資訊清單要求的回應。

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Example Stream</Title>
  </ProgramInformation>
  <Period duration="PT0H0M15.000S" id="content-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-2">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-3">
    ...
  </Period>
  ...
</MPD>

其他資源

使用 IMA SDK 進行廣告連播放送：
- Android
- HTML5
- iOS
- tvOS
使用 DAI 的廣告連播放送播放功能 API

VOD 串流資訊清單操控器

接收串流資訊清單要求

資訊清單要求端點範例

擷取內容串流

請求廣告連播資訊清單

JSON 內文

編碼設定檔

影片設定

音訊設定

字幕設定

DAI 選項

回應

要求範例 (cURL)

要求主體範例

回應範例

將廣告連播合併到內容

HTTP 即時串流串流

對編碼設定檔進行疊代

廣告連播陣列範例

多變化版本內容播放清單範例

系統收集的變化版本資料範例

在各個變化版本資訊清單中插入廣告

系統收集的變化版本資料範例

內容資訊清單範例

廣告連播資訊清單範例

拼接的變化版本資訊清單範例

建立多變化版本播放清單

最終多變化版本播放清單範例

MPEG DASH 串流

MPD 範例內容

廣告連播 JSON 範例

廣告連播 MPD 範例

拼接的 MPD 範例

其他資源