使用郵遞員進行 API 請求

在本主題中,您將學習如何設置流行的Postman HTTP客戶端以向Brightcove RESTful API發出請求。雖然您可以在命令行上使用 curl 語句來發出請求,但有幾個應用程序可以為您提供 UI 和功能,以簡化此過程。本文檔將向您展示如何使用一種此類工具Postman應用程序。注意:本教程是為 Postman 9.6.2 編寫的 - 如果您發現與當前版本存在差異,請使用下方右側的反饋鏈接告訴我們。

安裝Postman

Postman從那裡得到postman.com。您可以使用在線版本,但我們建議您安裝桌面應用程序。

獲取客戶憑證

要使用Brightcove API,您將需要客戶端憑證來使用您想要使用的帳戶和API。按照以下說明獲取Studio中的客戶端憑據管理API身份驗證憑據。在以下步驟中,我們將使用 CMS API 請求Postman,因此您的憑據至少應具有以下權限:

  • Video: Read/Write

您可以根據需要添加任意數量的其他權限,以獲得可用於更廣泛的API請求的憑據。另請注意,如果您願意,您可以獲得適用於多個帳戶的憑證。

您可以使用這個在線應用若你寧可。如果這樣做,則需要至少指定video-cloud/video/all權限。

獲取 OpenAPI 規範

雖然不是必需的,但您可以大大簡化的設置Postman是導入要使用的 API 的 OpenAPI 規範。您可以對任何 Brightcove 平台 API 執行此操作,但對於本教程,我們將使用 CMS API。

要獲取 OpenAPI 規範,只需轉到 CMS API 參考 並單擊 下載 按鈕:

下載 OpenAPI 規範
下載 OpenAPI 規範

下載的文件將被調用openapi.yaml

導入 OpenAPI 規範

下一步是啟動 Postman 應用程序,然後導入您下載的 OpenAPI 規範:

打開收藏

當 API 被導入時,Postman 將生成一個請求集合。

  1. 單擊 集合
  2. 選擇新的 CMS API 集合:
  3. 展開集合併單擊 視頻 文件夾並選擇 獲取視頻 請求。
    內容管理系統 API 集合
    內容管理系統 API 集合
    請求詳細信息
    請求詳細信息

請注意,Postman 已從 API 參考中為您設置了大部分詳細信息,包括請求本身和可以添加到其中的參數。它還提供參數的文檔,讓您編輯值,並取消選中您不希望隨請求發送的參數。

但是,您仍然需要提供一些您自己的信息,包括帳戶 ID 和身份驗證信息。您可以逐個請求執行此操作,但更好的方法是為請求創建一個 環境 ,您可以在其中將常用信息存儲為變量。我們將在下一節中這樣做。

創建環境

以下步驟將指導您為 CMS API 請求設置環境

  1. 單擊 Environment Quick Look 圖標,然後 單擊 Add
    創造環境
    創造環境
  2. 編輯環境名稱,將其更改為“Brightcove API”(您也可以將此環境用於其他 Brightcove API,並根據需要向其中添加新變量)。
    編輯環境名稱
    編輯環境名稱
  3. 單擊文本“添加新變量”,鍵入account_id , 然後點擊初始值字段並輸入您的視頻雲帳戶 ID(然後對當前值執行相同操作):
    輸入變量
    輸入變量
  4. 重複上一步以添加其他變量:
    環境變量
    變數 初始值
    client_id (您的客戶 ID - 請參閱上面的 獲取客戶憑證
    client_secret (您的客戶機密 - 請參閱上面的 獲取客戶憑證
    access_token_url https://oauth.brightcove.com/v4/access_token
  5. 點擊 保存 保存環境:
    拯救環境
    拯救環境
  6. 返回 Brightcove CMS API 集合併從環境選擇器中選擇您創建的環境:
    環境選擇器
    環境選擇器

可以通過將環境變量括在雙花括號中來引用環境變量 - 例如:{{client_id}}。當您鍵入“{{...”時,Postman 會幫助您自動完成。您可以返回「取得視訊」要求,並開始在路徑變數的「值」欄位中輸入「{{a」來嘗試此操作account_id

變量自動補全
變量自動補全

啟用請求

現在您已經設置了環境,您可以使用變量來測試請求。我們將首先查看獲取視頻請求。

  1. 如果您尚未這麼做,請輸入 {{account_id}} 做為「account_id路徑變數」的值
  2. 單擊請求的 授權 選項卡:
    授權標籤
    授權標籤
  3. Configuration Options下,將 Grant Type 更改為 Client-Credentials
    授權授權類型
    授權授權類型
  4. 在相應字段中輸入您環境中的以下變量:
    • 訪問令牌URL:{{access_token_url}}
    • 用戶端識別碼:{{client_id}}
    • 用戶端密碼:{{client_secret}}
  5. 請點擊獲取新的訪問令牌
    授權設置
    授權設置
  6. 授權完成後,您可以單擊 繼續 或等待令牌出現。然後點擊 使用令牌
    管理訪問令牌
    管理訪問令牌

請注意,Brightcove 訪問令牌會在五分鐘後過期。根據您正在做的事情和速度,您可以多次使用相同的訪問令牌。當它過期時,CMS API 將返回未經授權的錯誤:

[
	{
			"error_code": "UNAUTHORIZED",
			"message": "Permission denied."
	}
]

(消息的確切形式可能因其他 API 而異,但會相似。)

發生這種情況時,只需返回 授權選項 卡並請求新令牌即可。您還應該刪除任何過期的令牌以避免混淆,因為它們沒有進一步的價值。

刪除過期的令牌
刪除過期的令牌

提出要求

您現在可以發出獲取視頻請求了。

  1. 返回 Params 選項卡並取消選中所有 Query Params(當然,您可以使用它們並更改值,但我們將只使用默認值進行第一次測試)。
  2. 按一下「傳送」。
  3. 您應該會在下面的響應區域中看到 JSON 代碼(視頻元數據對像數組):
    響應數據
    響應數據
  4. 現在我們將嘗試寫入請求(創建視頻)。在集合中選擇該請求:
    創建視頻請求
    創建視頻請求
  5. 您將再次需要輸入 對於 帳戶 ID 路徑變量。您 不需要 重複上一節中的步驟來設置授權,因為 Postman 會將這些設置傳輸到集合中的其他請求。但是, 您仍然需要生成一個新的訪問令牌
  6. 接下來,轉到 Body 選項卡,您將在其中看到 API 參考中的示例請求正文:
    樣本請求正文
    樣本請求正文
  7. 此 JSON 是可編輯的。創建視頻請求的唯一必填字段是name,因此請將該值更改為「測試視頻」並刪除 JSON 的其餘部分,以便您的請求正文是:
    {
    	"name": "Test video"
    }
  8. 現在單擊發送(如果需要,獲取新的訪問令牌),您應該會看到新視頻的元數據對像出現在響應區域中。