Meta 的 Facebook 限時動態 API

本文件說明如何使用 Facebook 限時動態 API 在 Facebook 粉絲專頁上發佈限時動態。

若要發佈限時動態，您需要執行以下步驟：

1. 將您的影音素材上傳到 Meta 伺服器
2. 以限時動態將影音素材發佈到您的粉絲專頁

準備工作

本指南假設您已閱讀粉絲專頁 API 總覽及實作所需的元件，並已順利完成「開始使用」指南。

• 您需要實作「Facebook 登入」或「商家專用 Facebook 登入」，才能向您的應用程式用戶要求存取其 Facebook 粉絲專頁和接收粉絲專頁存取權杖所需的權限。

• 您的應用程式用戶需要能夠在存取權杖中表示的粉絲專頁上執行 CREATE_CONTENT 任務，並為您的應用程式授予以下權限：

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

如果您在 API 要求中使用企業系統用戶，也需要 business_management 權限。

影音素材需求

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

相片規格

影片規格

限制

• 為限時動態上傳的相片或影片不能已經用於先前發佈的貼文
• 影片限時動態不能超過 60 秒
• 若要在 GET 要求中包含已典藏的限時動態以查看限時動態清單，您必須開啟 Facebook 限時動態典藏功能

最佳作法

本文件中的程式碼範例採用方便閱讀的格式。請將粗體、斜體值（例如 page_id）換成您的值。

影片限時動態

若要在 Facebook 粉絲專頁上發佈影片限時動態，您需要與 Meta 伺服器初始化影片上傳連線階段、將影片上傳到 Meta 伺服器，然後發佈影片限時動態。

步驟 1：初始化連線階段

若要初始化上傳連線階段，請傳送 POST 要求至 /page_id/video_stories 端點（其中 page_id 為您的 Facebook 粉絲專頁編號），並將 upload_phase 參數設為 start。

要求範例

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

成功後，您的應用程式會收到 JSON 回應，其中包含影片編號以及影片上傳的 Facebook 網址。

回應範例

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

步驟 2：上傳影片

您已經將上傳連線階段初始化並收到上傳網址，現在可以上傳影片了。您可以上傳：

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

上傳託管檔案

若要上傳託管檔案，請傳送 POST 要求至您在初始化步驟中收到的 upload_url 端點，並使用下列參數：

• file_url 設為影片檔案的網址

要求範例

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

上傳本機檔案

若要上傳本機檔案，請傳送 POST 要求至您在初始化步驟中收到的 upload_url 端點，並使用下列參數：

• offset 設為 0
• file_size 設為所要上傳影片的總位元數大小

要求範例

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

上傳成功後，您的應用程式會收到 success 設為 true 的 JSON 回應。

上傳回應範例

{
    "success": true
}  

上傳中斷

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

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

取得上傳狀態

若要在上傳或發佈期間檢查影片的狀態，請傳送 GET 要求至 /video_id 端點，並使用下列參數：

• fields 設為 status

要求範例

curl -X GET "https://graph.facebook.com/v21.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：發佈影片限時動態

若要發佈影片限時動態至您的粉絲專頁，請傳送 POST 至 /page_id/video_stories 端點，並使用下列參數：

• video_id 設為所上傳影片的編號
• upload_phase 設為 finish

要求範例

curl -X POST "https://graph.facebook.com/v21.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：發佈相片限時動態

若要發佈相片限時動態至您的粉絲專頁，請傳送 POST 至 /page_id/photo_stories 端點，並使用下列參數：

• photo_id 設為所上傳相片的編號

要求範例

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

成功後，您的應用程式會收到包含下列鍵值組的 JSON 回應：

• success 設為 true
• post_id 設為限時動態貼文的編號

回應範例

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

取得限時動態

若要取得粉絲專頁的所有限時動態清單以及每個限時動態的相關資料，請傳送 GET 要求至 /page_id/stories 端點，其中 page_id 是您要查看之粉絲專頁的編號。

要求範例

    
curl -i -X GET "https://graph.facebook.com/v21.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 登入
• 圖形 API – 使用 since 和 until 的分頁結果

端點參考資料

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