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

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

VOD 串流資訊清單操控器

廣告連播放送 API 可讓您存取以適應性位元率準備的影片廣告連播，並直接將這些廣告連播縫合至面向使用者的 HLS 或 MPEG-DASH 媒體播放清單。

本指南著重於為 VOD 串流實作基本 Pod 服務資訊清單操作伺服器。

接收串流資訊清單要求

您的資訊清單操控工具必須提供 API 端點，才能監聽影片播放器用戶端應用程式傳送的資訊清單要求。這個端點至少必須從用戶端播放器應用程式收集串流 ID。這個串流 ID 可用於在廣告插播要求中，將串流工作階段識別為 Ad Manager。

您也需要收集其他資訊，以便識別適當的內容串流，例如內容 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 索取廣告，您的伺服器必須向廣告 Pod 端點提出 POST 要求，並傳遞要求的編碼設定檔和廣告代碼。這項要求也包含您在步驟 1 收集到的串流 ID。

系統會傳回廣告連播物件清單，其中包含發布商廣告代碼要求的廣告連播資訊清單檔案，以及應在何時何處插入內容的資訊。

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 回應才需要使用此屬性。這種情況並不常見。注意：如要進一步瞭解時間偏移類型，請參閱 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 設定檔解除多重訊號。此外，當 `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`	影片的浮點 FPS。
`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`	要套用至廣告 Pod 資訊清單的 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`	僅適用於 HLS 串流。將編碼設定檔 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
    }
  ]
}

將廣告插播片段縫合至內容

將廣告插播單元拼接至內容串流的程序會因導入方式、串流格式，以及您選擇從格式規格導入哪些功能而有所不同。以下工作流程是處理此程序的建議方式。導入方式的確切細節可能會因業務需求和內容串流而異。

HLS 串流

如果您要以 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 標記中，然後在內容資訊清單的目前位置插入清單。請繼續執行這個程序，直到所有廣告連播和變化版本串流都處理完畢為止。

產生的資訊清單必須符合 HLS 標準。因此，視內容資訊清單納入的規格功能而定，您可能需要對合併的資訊清單進行最後一次掃描，以修正媒體序號、內容時間長度、中斷序號，以及任何需要更新的其他標記，以便考量新的廣告區段。修正與標準的任何差異後，請將每個使用者專屬變化版本資訊清單推送至 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 格式的串流，只需產生單一檔案即可。這樣一來，相較於 HLS，DASH 串流更容易拼接。

正確準備的 MPEG DASH 媒體呈現說明 (MPD) 檔案應包含多個時段，每個時段都包含多個表示法。每個表示法都應與其中一個編碼設定檔相符。從 Ad Manager 傳回的每個廣告連播也是 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 放送 Pod 播放內容：
- Android
- HTML5
- iOS
- tvOS
使用 DAI API 進行廣告連播放送播放

VOD 串流資訊清單操控器

接收串流資訊清單要求

資訊清單要求端點範例

擷取內容串流

請求廣告連播資訊清單

JSON 內文

編碼設定檔

影片設定

音訊設定

字幕設定

DAI 選項

回應

要求範例 (cURL)

要求主體範例

回應範例

將廣告插播片段縫合至內容

HLS 串流

對編碼設定檔進行疊代

廣告連播陣列範例

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

收集的子類資料範例

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

收集的子類資料範例

內容資訊清單範例

廣告連播資訊清單範例

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

建立多變化版本播放清單

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

MPEG DASH 串流

內容 MPD 範例

廣告區塊 JSON 範例

廣告連播 MPD 範例

拼接 MPD 範例

其他資源