直播

若要播放直播影片，您必須先建立 LiveVideo 物件。LiveVideo 物件代表直播，您可以透過操縱物件屬性來控制直播設定。建立後，API 將傳回 LiveVideo 物件編號和串流影片網址，然後您可將這些資料傳送到編碼器，用來將資料串流至 LiveVideo 物件。

在用戶上直播

若要在 User 物件上直播，請取得具備 publish_video 權限的用戶存取權杖，並傳送要求至：

POST /<USER_ID>/live_videos?status=LIVE_NOW

請參閱 /live_videos 關係連線參考資料，以取得可包含用來說明播的其他查詢字串參數，例如標題和說明。

成功後，API 將在用戶建立 LiveVideo 物件，並傳回 secure_stream_url 和 LiveVideo 物件的 id。只要將資料傳送至加密的串流影片網址，直播便會以貼文形式在用戶個人檔案上顯示。您可查詢 LiveVideo 物件，以監控直播的品質及結束直播。

要求範例

curl -i -X POST \
 "https://graph.facebook.com/v21.0/<USER_ID>/live_videos
   ?status=LIVE_NOW
   &title=Today%27s%20Live%20Video
   &description=This%20is%20the%20live%20video%20for%20today."

回應範例

{
  "id": "1953020644813104",      //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

在粉絲專頁上直播

若要在 Page 上播放直播視訊，請取得具備 pages_read_engagement 和 pages_manage_posts 權限之粉絲專頁管理員的粉絲專頁存取權杖，然後傳送要求至：

POST /<PAGE_ID>/live_videos?status=LIVE_NOW

請參閱 /live_videos 關係連線參考資料，以取得可包含用來說明播的其他查詢字串參數，例如標題和說明。

成功後，API 將在粉絲專頁建立 LiveVideo 物件，並傳回 secure_stream_url 和 LiveVideo 物件的 id。只要將資料傳送至加密的串流影片網址，直播便會以貼文形式在粉絲專頁上顯示。您可查詢 LiveVideo 物件，以監控直播的品質及結束直播。

要求範例

curl -i -X POST \
  "https://graph.facebook.com/v21.0/<PAGE_ID>/live_videos
    ?status=LIVE_NOW
    &title=Today%27s%20Page%20Live%20Video
    &description=This%20is%20the%20live%20video%20for%20the%20Page%20for%20today"

回應範例

{
  "id": "1953020644813108",     //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

取得直播串流影片資料

您可讀取 LiveVideo 物件，以取得直播串流影片的預覽網址和串流健康狀態的資料，例如位元速率和影格速率。串流健康狀態資料每 2 秒重新整理一次，因此請將查詢限制在每 2 秒不超過一次。系統會偵測串流逾時，並在未收到資料超過 4 秒時回報。

若要讀取 LiveVideo 物件，請取得具備 publish_video 權限合適的用戶或粉絲專頁存取權杖，然後傳送查詢至：

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

請使用 {fields} 參數指定想要傳回的 LiveVideo 物件欄位。例如，下列要求可取得 LiveVideo 物件上的 ingest_streams，包括關於串流健康狀態的資料：

要求範例

curl -i -X GET \
  "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?fields=ingest_streams"

回應範例

{
  "ingest_streams": [
    {
      "stream_id": "0",
      "stream_url": "rtmp://rtmp-api.facebook...",
      "secure_stream_url": "rtmps://rtmp-api.facebook...",
      "is_master": true,
      "stream_health": {
        "video_bitrate": 4024116,
        "video_framerate": 60,
        "video_gop_size": 2000,
        "video_height": 720,
        "video_width": 1280,
        "audio_bitrate": 128745.4921875
      },
      "id": "1914910145231512"  // <INGEST_STREAM_ID>
    }
  ],
  "id": "<LIVE_VIDEO_ID>" 
}

回應屬性

結束直播

若要結束直播，請從編碼器停止串流直播視訊資料到串流影片網址或傳送要求至：

POST /<LIVE_VIDEO_ID>?end_live_video=true

這會將 LiveVideo 物件的狀態設為 VOD，並將其另存為點播影片（VOD），以供之後觀看。

成功時，API 會傳回 LiveVideo 物件的編號。

要求範例

curl -i -X POST \
  "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?end_live_video=true"

回應範例

{
  "id": "10213570560993813"  //<LIVE_VIDEO_ID>
}

您可在 LiveVideo 編號上執行 GET 操作，以確認其狀態已設定為 VOD：

GET /<LIVE_VIDEO_ID>?fields=status

回應範例

{
  "status": "VOD",  // Broadcast ended, saved as VOD
  "id": "10213570560993813"    //<LIVE_VIDEO_ID>
}

刪除直播

若要刪除已結束的直播並將其另存為 VOD，請傳送要求至：

DELETE /<LIVE_VIDEO_ID>

要求範例

curl -i -X DELETE \
 "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>"

回應範例

{
  success: true
}

精確影格直播

在開始直播之前，當我們解碼其初始串流資料並處理任何相關的 API 要求時，可能會使直播產生輕微的延遲。此情況可能使直播人員難以確切地知道直播何時開始。若要避免此問題，您可以將 LiveVideo 物件設為接受串流資料，但設為在串流資料本身內偵測到直播 RTMP 訊息之前，不會向廣告受眾直播。如此允許任何能夠預覽直播的用戶看到直播，同時允許串流編碼器精確地同時控制向廣告受眾開始直播的時間以及廣告受眾看到的第一個影格。

若要啟用精確影格直播，請依正常方式建立一個 LiveVideo 物件，並將其狀態設為「預覽」。建立之後，查詢 LiveVideo 物件並要求包含以下巢狀欄位的 secure_stream_url 欄位：

secure_stream_url.inband_go_live(require_inband_signal)

上述動作將在 LiveVideo 物件上啟用精確影格直播，且 API 將使用新的安全串流網址進行回覆，您接著可以將影片串流到該網址。您可以忽略首次建立 LiveVideo 物件時，系統傳送給您的初始安全串流網址。

在（1）將直播狀態設為「已上線」（透過圖形 API 呼叫或從 Live Producer 發佈的用戶）以及（2）編碼器傳送直播 RTMP 訊息後，直播將開始並供廣告受眾觀看。

直播 RTMP 訊息結構

AMF0 封包（類型 0x12），包含以下內容：

• onGoLive 字串
• 包含單一鍵值組的 ECMA 陣列（類型 0x08）：

  • 鍵：timestamp 字串（類型 0x02）
  • 值：數字（類型 0x00）：公開播放的第一個影片影格的時間戳記

如需詳細資訊，請參閱 RTMP 和 AMF0 規格。

要求範例

在 LiveVideo 上啟用精確影格直播的要求範例。

curl -i -X GET \
   "https://graph.facebook.com/v21.0/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."

回應範例

啟用精確影格直播的 LiveVideo 物件的安全串流網址。

{
  "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...",
  "id": "LIVE_VIDEO_ID"
}

取得錯誤代碼資料

若要取得與直播相關聯的錯誤代碼資料，請傳送要求至：

GET /<LIVE_VIDEO_ID>?fields=errors

API 會以 error code、type、message 和 timestamp 回覆。

回應範例

curl -i -X GET \
 "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?fields=errors"

回應範例

{
  "errors": {
    "data": [
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      }
    ]
  },
  "id": "{your-live-video-id}"
}

常見的直播視訊 API 錯誤代碼

權限錯誤代碼

另請參閱

• 存取權杖
• LiveVideo 參考資料
• Page 參考資料
• PageLiveVideos 參考資料
• 權限參考資料
• User 參考資料
• UserLiveVideos 參考資料