速度測試

Facebook 在全球各地均設有直播視訊嵌入伺服器，可用來播放您的直播影片。透過速度測試，您可以選出最適合自己直播的影片嵌入伺服器。

執行速度測試時，您需要按照一組目的地網址的接收順序，先後傳送二進位檔案至這些網址。每項測試都會評估對特定 Facebook 影片嵌入伺服器的連線能力。伺服器會傳回有關測量網路連線速度、傳送和接收時間以及其他重要因素的詳細資訊。您可在每項連續測試中納入這些結果，以便 Facebook 選擇下一組目的地網址，直到判斷出最適合的嵌入伺服器為止。API 接著會傳回目標權杖。取得目標權杖後，請在建立要播放的直播影片時加入該權杖，API 就會傳回根據您網路連線能力調整後的串流影片網址。

您不一定要使用速度測試 API 來判斷適用在您直播視訊的最佳嵌入伺服器，也可以改用 Facebook Live 嵌入工具。

步驟 1：發起新的測試連線階段

若要發起新的測試連線階段，請傳送要求至下列目標：

GET /traffic_speedtest?fields=target_token,next_tests,upload_bandwidth_estimate_bits_per_second

該端點會傳回一個 JSON 物件，其中包含測試案例清單。每個測試案例都含有目的地網址與位元組計數。

要求範例

curl -i -X GET "https://graph.facebook.com/v3.3/traffic_speedtest \
 ?fields=target_token,next_tests,upload_bandwidth_estimate_bits_per_second \
 &access_token={access-token}"

回應範例

{                        //Formatted for clarity
 "next_tests": [
   {
     "byte_count": 3145728,
     "url": "https://edge-star-kut.xx.fbcdn.net/upload-speed-test-api"
   },
   {
     "byte_count": 3145728,
     "url": "https://edge-star-mad.xx.fbcdn.net/upload-speed-test-api"
   },
   {
     "byte_count": 3145728,
     "url": "https://edge-star-ort.xx.fbcdn.net/upload-speed-test-api"
   },
   {
     "byte_count": 3145728,
     "url": "https://edge-star-eze.xx.fbcdn.net/upload-speed-test-api"
   }
 ]
}

步驟 2：測試每個目的地網址

若要測試每個案例，請將二進位檔案（依據 byte_count 指定大小）上傳至對應的目的地網址。

POST /{destination-url}/upload-speed-test

要求範例

在這個範例中，{binary-file} 是一個包含 3,145,728 個隨機位元組的檔案，而該位元組計數與回應中的位元組計數相符。

curl --data-binary @{binary-file} https://edge-star-kut.xx.fbcdn.net/upload-speed-test-api

回應範例

系統傳回不明確的字串。

eyJzdGFydFRpbWVNUyI6IjE1NjIxMDk4NDg3ODAiLCJydHQiO...   //Truncated for brevity

請建立名為 previous_results 的陣列，其中應包含由下列屬性和數值組成的 JSON 物件：

previous_results=[
 {
   "test_url": "{destination-url}",
   "result_string": "{opaque-string}"
 }
]

注意：您必須將 result_string 視為不明確的字串。請勿嘗試解讀測試端點的回應。如果編碼器無法連上目的地網址，請在 previous_results 清單中刪除該單一項目。

參數	說明
`{destination-url}`	您測試的目的地網址。
`{opaque-string}`	該網址傳回的測試結果字串。

含有單一測試回應的陣列範例

previous_results=[           // JSON formatted for clarity
 {
   "test_url": "https://edge-star-kut.xx.fbcdn.net/upload-speed-test-api",
   "result_string": "eyJzdGFydFRpbWVNUyI6IjE1NjIxMDk4NDg3ODAiLCJydHQiO..."   //Truncated for brevity
 }
]

請將每個目的地網址和測試回應附加至 previous_results 陣列。

注意事項

請依照各項測試的接收順序來執行測試。同時執行測試可能導致結果的準確度下降。
請一律使用每個測試案例中指定的位元組數。有些測試案例可能會要求不同的位元組數。例如，初期測試案例可能會使用較小的上傳檔案來縮小相符位置組合的範圍，而後期測試案例可能會使用較大的上傳檔案來訂定可信度較高的估計值。
請一律使用隨機位元組，才能確保要求無法壓縮。非隨機位元組可能很容易壓縮，而經過壓縮的要求會降低速度測試的準確度。

步驟 3：要求另一組目的地網址

第一組網址測試完畢後，可以要求另一組網址並納入先前的結果。

GET /traffic_speedtest?fields=target_token,next_tests,upload_bandwidth_estimate_bits_per_second&previous_results={previous-results}

請將 {previous-results} 換成您已儲存的測試結果陣列。

要求範例

curl -i -X GET 'https://graph.facebook.com/v3.3/traffic_speedtest \
 ?fields=target_token,next_tests,upload_bandwidth_estimate_bits_per_second \
 &access_token={access-token} \
 &previous_results=[   // JSON formatted for clarity
   { 
     "test_url":"https://edge-star-kut.xx.fbcdn.net/upload-speed-test-api",
     "result_string":
       {
          "eyJzdGFydFRpbWVNUyI6IjE1NjIxMDk4NDg3ODAiLCJydHQiO..."   //Truncated for brevity
       }
   },
   {
     "test_url":"https://edge-star-bru.xx.fbcdn.net/upload-speed-test-api",
     "result_string":
       {
          "eyJzdGFydFRpbWVNUyI6IjE1NjIxMDk4NDg3ODAiLCJydHQiO..."   //Truncated for brevity
       }
   },
   ...  //Truncated for brevity
 ]'

端點會傳回新的測試案例清單或目標權杖。如果端點傳回的是更多案例，請逐一測試這些案例，然後要求另一組網址。請重複執行此操作，直到端點傳回權杖為止。端點傳回權杖即表示測試連線階段已完成。

含有權杖的回應範例

{
 "target_token": "atl",   //Testing is complete
 "upload_bandwidth_estimate_bits_per_second": 173557406  //Suggested bps
}

屬性	說明
`target_token`	使用直播影片 API 時需納入的字串。加入目標權杖後，直播影片 API 就會傳回根據您網路連線能力調整後的串流影片網址。
`upload_bandwidth_estimate_bits_per_second`	從裝置到 Facebook 的上行頻寬估計值。您可以使用此值來設定影片編碼器的最高位元速率。例如，若該值為 10,000,000，則您可將編碼器設定為輸出 8 Mbps 的影片串流。

注意：上傳頻寬只是估計值，可能因網路狀況變更而有大幅變動。例如，若為了管理容量或避免輸入串流之間的共用端點失敗，而將串流傳送至不同位置，則上傳頻寬就有可能變動。

步驟 4：取得最佳的串流影片網址

請按照平常的方式來建立要播放的直播影片，然後查詢直播影片編號並加入目標權杖：

GET /{broadcast-id}?fields=secure_stream_url&target_token={target-token}

端點會傳回根據您網路連線能力調整後的安全串流影片網址。

要求範例

在這個範例中，速度測試所傳回的 target_token 為 atl。

curl -i -X GET \
"https://graph.facebook.com/v3.3/{broadcast-id} \
  ?fields=secure_stream_url&target_token=atl \
  &access_token={access-token}"

回應範例

{
 “secure_stream_url”: “rtmps://...”,  //Optimized stream URL
 “id”: “{broadcast-id}”
}

最佳作法

請按照每個速度測試案例的接收順序逐一執行各項測試，不要同時進行。同時執行多個速度測試案例可能導致傳回的結果不準確。

使用目標權杖取得串流影片網址時，應針對每個要播放的直播影片發起新的速度測試連線階段。請勿重複使用舊的測試結果。測試網址、測試網址回應和目標權杖可能會有變動。

如果出現下列情況，建議您重新執行速度測試：

您的網路連線有變動。例如，從 WiFi 改為有線網路。
應用程式已閒置一段時間。
應用程式偵測到網路狀況有變動。例如，傳送緩衝區已滿，或是您無法以預估頻寬串流影片。
您的網路連線品質有變動。例如，兩個 ISP 之間的連結變得壅塞。

系統傳回新的目標權杖後，請停止使用目前的串流影片網址，然後開始使用新權杖所傳回的新串流影片網址。

如果網路狀況不佳而無法提供可靠的串流系統，則您的應用程式應警告影片發佈商改善網路連線品質。例如，確保沒有其他應用程式占用頻寬、從無線網路換成有線網路、增加網路頻寬，或是請您的網路供應商直接與 Facebook 聯絡。