這份文件已更新。
中文(香港) 的翻譯尚未完成。

英文更新時間：2020年10月5日

直播

如要廣播直播視像，您必須先建立一個 LiveVideo 物件。LiveVideo 物件表示直播，而且您可透過操控物件屬性來控制直播設定。成功建立後，API 將傳回 LiveVideo 物件編號和串流影片網址，您可以將它們傳遞到編碼器，並用於向 LiveVideo 物件串流數據。

在用戶直播內容

如要在用戶個人檔案直播內容，請獲取擁有 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/{user-id}/live_videos
   ?status=LIVE_NOW
   &title=Today%27s%20Live%20Video
   &description=This%20is%20the%20live%20video%20for%20today.
   &access_token={access-token}"

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{user-id}/live_videos",
  new JSONObject("{\"title\":\"Today's Live Video\",\"description\":\"This is the live video for today.\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{user-id}/live_videos"
           parameters:@{ @"status": @"LIVE_NOW",@"title": @""Today's Live Video"",@"description": @""This is the live video for today."",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/{user-id}/live_videos',
  'POST',
  {"status":"LIVE_NOW","title":"\"Today's Live Video\"","description":"\"This is the live video for today.\""},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{user-id}/live_videos',
    array (
      'status' => 'LIVE_NOW',
      'title' => '"Today\'s Live Video"',
      'description' => '"This is the live video for today."'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

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

在專頁直播內容

如要在專頁播放直播視像，請獲取擁有 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/{page-id}/live_videos
    ?status=LIVE_NOW
    &title=Today%27s%20Page%20Live%20Video
    &description=This%20is%20the%20live%20video%20for%20the%20Page%20for%20today
    &access_token=EAAC..."

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-id}/live_videos",
  new JSONObject("{\"title\":\"Today's Page Live Video\",\"description\":\"This is the live video for the Page for today.\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}/live_videos"
           parameters:@{ @"status": @"LIVE_NOW",@"title": @""Today's Page Live Video"",@"description": @""This is the live video for the Page for today."",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/{page-id}/live_videos',
  'POST',
  {"status":"LIVE_NOW","title":"\"Today's Page Live Video\"","description":"\"This is the live video for the Page for today.\""},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-id}/live_videos',
    array (
      'status' => 'LIVE_NOW',
      'title' => '"Today's Page Live Video"',
      'description' => '"This is the live video for the Page for today."'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

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

在群組直播內容

在群組播放直播視像前，群組必須先安裝您的應用程式。群組管理員可在 www.facebook.com 做到這一點，方法是前往群組的編輯群組設定 > 應用程式 > 加入應用程式，然後加您的應用程式。

如要在已安裝您應用程式的群組播放直播視像，請獲取擁有 publish_video 權限的群組管理員所擁有的用戶存取憑證，然後傳送要求至：

POST /{group-id}/live_videos?status=LIVE_NOW

請參閱 /live_videos 邊緣參考資料，以了解您可用於描述直播內容的其他查詢字串參數，例如標題和描述。

成功後，API 將在群組建立一個 LiveVideo 物件，並傳回 secure_stream_url 及 LiveVideo 物件的 id。將數據傳送至安全串流影片網址後，直播內容便將立即出現在群組的帖子中。您可以查詢 LiveVideo 物件，以監控直播內容的健康狀況，以及結束直播。

要求範例

curl -i -X POST \
  "https://graph.facebook.com/{group-id}/live_videos
    ?status=LIVE_NOW
    &title=Today%27s%20Group%20Live%20Video
    &description=This%20is%20the%20live%20video%20for%20the%20group%20for%20today
    &access_token={access-token}"

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{group-id}/live_videos",
  new JSONObject("{\"title\":\"Today's Group Live Video\",\"description\":\"This is the live video for the Group for today.\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{group-id}/live_videos"
           parameters:@{ @"status": @"LIVE_NOW",@"title": @""Today's Group Live Video"",@"description": @""This is the live video for the Group for today."",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/{group-id}/live_videos',
  'POST',
  {"status":"LIVE_NOW","title":"\"Today's Groups Live Video\"","description":"\"This is the live video for the Group for today.\""},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{group-id}/live_videos',
    array (
      'status' => 'LIVE_NOW',
      'title' => '"Today's Group Live Video"',
      'description' => '"This is the live video for the Group for today."'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

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

獲取直播串流影片數據

您可以讀取 LiveVideo 物件，以獲取直播串流影片的預覽網址及串流影片的健康狀況數據，如比特率和影格速率。串流影片的健康狀況數據每 2 秒會重新整理一次，因此請最多每 2 秒查詢 1 次。如果 4 秒後沒有收到任何數據，則系統會偵測並報告串流影片逾時。

如要讀取 LiveVideo 物件，請獲取擁有 publish_video 權限的合適用戶或專頁存取憑證，然後傳送查詢至：

GET /{live-video-id}?fields={fields}

使用 {fields} 參數來指定您想傳回的 LiveVideo 物件欄位。例如，以下是獲取 LiveVideo 物件的 ingest_streams 之要求，其中包含串流影片健康狀況的數據：

要求範例

curl -i -X GET \
  "https://graph.facebook.com/{live-video-id}
    ?fields=ingest_streams
    &access_token={access-token}"

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{live-video-id}",  
  new JSONObject("{\"fields\":\"ingest_streams\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "ingest_streams");
request.setParameters(parameters);
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{live-video-id}"     
           parameters:@{ @"fields": @"ingest_streams",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/{live-video-id}',     
  'GET',
  {"fields":"ingest_streams"},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{live-video-id}',      
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

{
  "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": "{your-live-video-id}" 
}

回應屬性

欄位名稱	描述
`audio_bitrate`	接收到的音訊串流之每秒位元數。
`is_master`	如果正在查詢的直播視像編號是向觀眾展示的影片，則為 `true`。
`secure_stream_url`	正在查詢的直播視像編號之安全 RTMPS 擷取網址。
`stream_url`	正在查詢的直播視像編號之 RTMP 擷取網址。
`video_bitrate`	接收到的影片串流之每秒位元數。
`video_framerate`	接收到的影片串流之每秒影格數。
`video_gop_size`	GOP（圖片群組）大小，以毫秒為單位。
`video_height`	接收到的影片影格高度，以像素為單位。
`video_width`	接收到的影片影格闊度，以像素為單位。

結束直播內容

如要結束直播內容，請停止將編碼器的直播視像數據串流至串流影片網址，或傳送要求至：

POST /{live-video-id}?end_live_video=true

這會將 LiveVideo 物件的狀態設定為 VOD，並將其儲存為點播影片 (VOD)，以供稍後觀看。

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

要求範例

curl -i -X POST \
  "https://graph.facebook.com/{live-video-id}
    ?end_live_video=true
    &access_token={access-token}"

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/live-video-id",
  new JSONObject("{\"end_live_video\":\"true\"}\"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{live-video-id}"
           parameters:@{ @"end_live_video": @"true",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/{live-video-id}',
  'POST',
  {"end_live_video":"true"},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{live-video-id}',
    array (
      'end_live_video' => 'true'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

{
  "id": "10213570560993813"
}

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

GET /{live-video-id}?fields=status

回應範例

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

刪除直播內容

如要刪除已結束的直播內容並將之儲存為 VOD，請傳送要求至：

DELETE /{live-video-id}

要求範例

curl -i -X DELETE \
 "https://graph.facebook.com/{live-video-id}?access_token={access-token}"

Bundle parameters = new Bundle();

GraphRequest request = new GraphRequest(
  accessToken,
  "/{live-video-id}",
  parameters,
  HttpMethod.DELETE,
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"{live-video-id}"
           parameters:nil
           HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/{live-video-id}',
  'DELETE',
  {},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->delete(
    '/{live-video-id}',
    array (),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

{
  success: true
}

獲取錯誤代碼數據

如要獲取與直播內容相關的錯誤代碼數據，請傳送要求至：

GET /{live-video-id}?fields=errors

成功時，API 將傳回 error code、type、message 及一個 timestamp。

回應範例

curl -i -X GET \
 "https://graph.facebook.com/{live-video-id}
   ?fields=errors
   &access_token={access-token}"

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/1951440638245129",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "errors");
request.setParameters(parameters);
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/1951440638245129"
           parameters:@{ @"fields": @"errors",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/1951440638245129',
  'GET',
  {"fields":"errors"},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/1951440638245129',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

回應範例

{ "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}" }

error_subcode	錯誤摘要	描述
`COPYRIGHT__LIVE_COPYRIGHT_VIOLATION`	直播版權侵權	系統已停止播放您的直播視像，因為影片可能含有屬於其他專頁的影音內容。
`VIDEO__CREATE_FAILED`	上載問題	上載您的影片時發生問題，因此影片無法上載。請再試一次。
`LIVE_VIDEO__DELETE_FAILED`	直播視像尚未刪除	刪除您的直播視像時發生問題，因此影片無法刪除。請再試一次。
`LIVE_VIDEO__EDIT_API_NOT_ALLOWED`	不允許在直播期間透過影片 API 編輯內容	不允許使用影片編輯 API 編輯直播視像。使用直播視像編號。
`LIVE_VIDEO__LIVE_STREAM_ERROR`	一般串流直播	串流直播期間出現錯誤
`LIVE_VIDEO__NOT_EXIST`	直播視像不存在	您想存取的直播視像不再存在於系統中。
`LIVE_VIDEO__PRIVACY_REQUIRED`	必須設定私隱	您必須在直播前設定私隱。