Meta 的 Facebook 限時動態 API

本文件介紹如何使用 Facebook 限時動態 API 在 Facebook 專頁上發佈限時動態。

如要發佈限時動態，您的應用程式需要執行以下步驟：

1. 將您應用程式用戶的媒體上載至 Meta 伺服器
2. 在您應用程式用戶的專頁以限時動態形式發佈媒體

準備工作

本指南假設您已閱讀專頁 API 概覽、安裝了所需組件，並成功完成新手指南。

• 您的應用程式用戶需要能夠在專頁存取憑證所代表的專頁上執行 CREATE_CONTENT 任務，並向您的應用程式授予以下權限：

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

如要在 API 要求中使用企業系統用戶，則還需要 business_management 權限。

媒體要求

您提供的相片或影片必須符合以下規格。

相片規格

影片規格

限制

• 為限時動態上載的相片或影片不能在之前發佈的帖子中用過
• 影片限時動態不能超過 60 秒
• 要在 GET 要求中加入限時動態典藏以查看限時動態清單，您必須開啟 Facebook 限時動態典藏功能

最佳操作實例

為方便閱讀，我們已為本文件中的程式碼範例設定格式。請將以粗體及斜體標示的值（例如 page_id）替換為您的值。

影片限時動態

如要在 Facebook 專頁上發佈影片限時動態，您需要向 Meta 伺服器發起影片上載連線階段，將影片上載至 Meta 伺服器，然後發佈影片限時動態。

第 1 步：發起連線階段

如要發起上載連線階段，請向 /page_id/video_stories 端點傳送 POST 要求（其中 page_id 是您的 Facebook 專頁編號），並將 upload_phase 參數設為 start。

範例要求

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

若要求成功，應用程式收到的 JSON 回應中會包含影片編號和您上載影片所使用的 Facebook 網址。

範例回應

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v25.0/video_id",
}  

第 2 步：上載影片

發起上載連線階段並收到上載網址後，您就可以上載影片了。您可以上載以下任何一種文件：

• 公開 http／https 伺服器（如 CDN）上的託管影片檔案
• 您裝置中的本機影片檔案

上載託管檔案

如要上載託管的檔案，請向您在發起連線階段步驟中收到的 upload_url 端點傳送 POST 要求，並加入以下參數：

• file_url，設為影片檔案的網址

確保主機是 rupload.facebook.com。

API 現會拒絕託管在透過 robots.txt 限制存取權的網站上的檔案。開發人員需確保託管網站允許「facebookexternalhit/1.1（+http://www.facebook.com/externalhit_uatext.php）」用戶代理程式擷取託管檔案。

Meta CDN（例如 fbcdn 網址）上的託管檔案將遭拒。開發人員可改為使用多重發佈功能來在多個專頁上發佈影片，而無需分別將影片上載至各專頁。請參閱有關多重發佈功能的詳細指南。

範例要求

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

上載本機檔案

如要上載本機檔案，請向您在發起連線階段步驟中收到的 upload_url 端點傳送 POST 要求，並加入以下參數：

• offset，設為 0
• file_size，設為要上載影片的總大小，以位元組為單位

範例要求

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

若上載成功，應用程式收到的 JSON 回應中會包含設為 true 的 success。

上載回應範例

{
    "success": true
}  

上載中斷

如果影片上載中斷，可重新開始上載或恢復上載。

• 如要重新開始上載，請重新傳送 POST 要求，並將 offset 設為 0。
• 如要恢復上載，請重新傳送 POST 要求，並將 offset 設為狀態檢查結果中的 bytes_transfered 值。

取得上載狀態

如要檢查影片的狀態，在上載或發佈時，請向 /video_id 端點傳送 GET 要求，並加入以下參數：

• fields，設為 status

範例要求

curl -X GET "https://graph.facebook.com/v25.0/video_id" \
	-d "fields=status"

若要求成功，應用程式收到的 JSON 回應中會包含下列項目：

• 一個 status 物件，其中包含這些內容：

  • video_status，值為 ready、processing、expired 或 error
  • uploading_phase 物件，其中包含以下鍵值組合：

    • status，設為 in_progress、not_started、complete 或 error
    • bytes_transfered，設為已上載的位元組；如果上載中斷，該值可用作 offset 的值。
  • processing_phase 物件，其中包含以下鍵值組合：

    • status，設為 in_progress、not_started、complete 或 error
  • processing_phase 物件，其中包含以下鍵值組合：

    • status，設為 in_progress、not_started、complete 或 error
    • publish_status，設為 published 或 not_published
    • publish_time，設為實際時間或發佈時間的 UNIX 時戳

範例回應

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

第 3 步：發佈影片限時動態

如要在專頁上發佈影片限時動態，請向 /page_id/video_stories 端點傳送 POST 要求，並加入以下參數：

• video_id，設為已上載影片的編號
• upload_phase，設為 finish

範例要求

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

若要求成功，應用程式收到的 JSON 回應中會包含以下鍵值組合：

• success，設為 true
• post_id，設為限時動態帖子的編號

範例回應

{
  "success": true,
  "post_id": 1234
}

相片限時動態

第 1 步：上載相片

查閱專頁帖子參考資料 ，了解如何使用 /page_id/photos 端點將相片上載至 Meta 伺服器。務必加入 published 參數，並將其設為 false。

第 2 步：發佈相片限時動態

如要在專頁發佈相片限時動態，請向 /page_id/photo_stories 端點傳送 POST 要求，並加入以下參數：

• photo_id，設為已上載相片的編號

範例要求

curl -X POST "https://graph.facebook.com/v25.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

若要求成功，應用程式收到的 JSON 回應中會包含以下鍵值組合：

• success，設為 true
• post_id，設為限時動態帖子的編號

範例回應

{
  "success": true,
  "post_id": 1234
}

取得限時動態

如要取得專頁的完整限時動態清單和每則限時動態的資料，請向 /page_id/stories 端點傳送 GET 要求，其中 page_id 是您要查看的專頁的編號。

範例要求

    
curl -i -X GET "https://graph.facebook.com/v25.0/page_id/stories"

若要求成功，應用程式收到的 JSON 回應中會附有物件陣列，其中每個物件都包含已發佈到專頁的限時動態的資訊。每個物件都包含以下鍵值組合：

• post_id，設為已發佈限時動態帖子的編號
• status，設為 PUBLISHED、ARCHIVED
• creation_time，設為限時動態發佈時間的 UNIX 時戳
• media_type，設為 video 或 photo
• media_id，設為限時動態帖子中影片或相片的編號
• url，設為限時動態帖子的 Facebook 網址，例如 https://facebook.com/stories/8283482737484972

範例回應

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

您可以根據狀態（已發佈或已封存）以及日期（使用 since 和 until 參數）來篩選限時動態。

另請參閱

進一步了解本指南中討論的不同端點和概念。

相關指南

• 企業系統用戶
• Facebook 登入
• 商家專用 Facebook 登入
• Graph API — 使用 since 和 until 篩選出的分頁結果

端點參考資料

• 專頁參考資料
• 專頁影片限時動態參考資料
• 專頁相片限時動態參考資料
• 影片參考資料
• 限時動態洞察報告參考資料