針對 API 請求使用失眠

簡介

有些發現curl語句和命令行，用於我們平台API文檔中的許多示例，既困難又令人生畏。對於這些，有許多工具來發送 HTTP 請求到基於 REST 的服務，其中包括大多數 Brightcove API。本文檔將向您展示如何使用一種流行的工具，即Insomnia應用程式。

安裝Insomnia

得到Insomnia從https://insomnia.rest。Insomnia可以安裝在Mac，Linux或Windows系統上。

驗證

Insomnia可用於向Brightcove的任何RESTful API發出請求。大多數 API 使用 OAuth2 進行身份驗證，我們將在本文檔的Insomnia後面看到如何設置。但是，您也可以通過簡單地設置適當的標頭將其用於不使用OAuth的API。

對於使用 Oauth2 以外的身份驗證方法的請求，標頭如下所示：

Playback API

  BCOV-Policy: YOUR_POLICY_KEY

Live API

  X-API-KEY: YOUR_API_KEY

Zencoder API

  Zencoder-Api-Key: YOUR_API_KEY

獲取客戶憑證

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

• 視頻：讀/寫

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

使用Insomnia

一旦你有你的客戶端憑據，你就可以開始使用Insomnia。Insomnia如果您導入 CMS API 的 OpenAPI 規範，我們將為您完成大量的設置工作。以下步驟將引導您完成一些 CMS API請求使用Insomnia。

設定 CMS API 的Insomnia集合

獲取 CMS API 的 OpenAPI 規範

1. 打開 CMS API 參考。
2. 按一下「下載」按鈕，然後將openapi.yaml檔案儲存在可以再次找到檔案的位置：

   

將 OpenAPI 規範導入 Insomnia

1. 啟動Insomnia應用程式。
2. 點擊旁邊的下拉菜單Insomnia並選擇導入/導出

   

3. 在打開的對話框中，單擊 導入數據 並選擇 來自文件：

   

4. 選取您下載的openapi.yaml檔案，然後選擇是將資料匯入目前工作區或建立新工作區。兩者都可以，但我們建議為每個 API 創建一個新的工作區：

   

5. 接下來，系統會詢問您是將數據導入為請求集合還是設計文檔。選擇 請求收集：

   

6. 您將看到一個確認數據已導入的對話框。
7. 單擊左上角的 儀表板 以查看您的工作區。如果您創建了一個新的工作區，您將看到它以適當的名稱顯示：

   

8. 單擊工作區將其打開。
9. 您將看到一個文件夾列表，其中包含對 CMS API 的各種請求組，以及一個新的 OpenAPI 環境：

   

給環境添加變量

這是一個可選步驟，但它將簡化以後為請求設置身份驗證的過程。

1. 單擊 OpenAPI 環境 下拉菜單並選擇 管理環境：

   

2. 您將看到從 OpenAPI 規範中Insomnia創建的環境變量以 JSON 的形式：

   

3. 將這些附加變量添加到 JSON（請參閱獲取客戶端憑證上面的client_id和client_secret ):
   • "account_id": "your_account_id"
   • "client_id": "your_client_id"
   • "client_secret": "your_client_secret"
   • "access_token_url": "https://oauth.brightcove.com/v4/access_token"
4. 完成後，環境 JSON 應類似於以下內容：

   

5. 單擊右下角的 完成 以退出對話框。

設置身份驗證

現在我們準備為 API 請求設置身份驗證。

1. 單擊 “視頻” 文件夾，然後選擇 “獲取視頻” ：

   

2. 請注意，請求的 URL 已經包含兩個變量。如果你點擊這些，你可以看到（和修改）它們的值。base_url是由失眠從 OpenAPI 規範中自動生成的。如果您按一下account_id，您應該會發現該值與您在上一節中輸入的環境變數相符。
3. 單擊 Auth 選項卡和 Auth 下拉 菜單，然後選擇 OAuth 2.0 ：

   

4. 單擊 授予類型 下拉菜單並選擇 客戶端憑據：

   

5. 在訪問令牌 URL 字段中，開始鍵入「access_token_url」-您將看到自動完成菜單，並選擇您的access_token_url環境變量：

   

6. 重複上一步以填充客戶端編號和客戶秘密與你的領域client_id和client_secret變量：

   

7. 向下滾動以查看 獲取令牌 按鈕並單擊它。確保您看到使用令牌填充的訪問令牌字段：

   

8. 請點擊提取令牌確保這有效。您應該看到這樣的響應：

   

9. 轉到 Header 選項卡並刪除 Authorization header（您剛剛設置的身份驗證將處理 head - 這個會破壞它）：

   

發出請求

現在我們準備發出 獲取視頻 請求。

1. 由於這是一個GET請求，因此您所要做的就是單擊「發送」。
2. 您應該會看到 JSON 響應出現在響應區域中：

   

3. 請注意，您可以使用 查詢 參數檢索不同的視頻集。單擊請求的 “查詢”選項 卡，您將看到 Insomnia 已根據 OpenAPI 規範對其進行了填充。只需檢查您要使用的參數並設置值：

   

發送請POST求

現在，我們將發送POST請求一些數據。在這種情況下，我們將使用 CMS API 創建一個新的視頻對象。首先選擇 視頻 文件夾中的 創建視頻 請求。

1. 重複上面 設置身份驗證 部分中的所有步驟，為這個新請求設置身份驗證。
2. 此請求需要請求主體，因此請單擊 JSON 選項卡，然後輸入此 JSON 代碼以替換null：

   {
   	"name": "Insomnia Test"
   }

   

3. 單擊 “發送” ，您應該會看到響應中返回了新的視頻對象。

使用代碼生成器

Insomnia 的另一個不錯的功能是它會生成用於以多種不同語言提出請求的代碼。

1. 將鼠標懸停在下拉菜單上以獲取請求：

   

2. 從菜單中選擇 生成代碼 ：

   

3. 在打開的 “生成客戶端代碼” 對話框中，選擇您要為其編寫代碼的語言：

   

4. 對於許多語言，您還可以選擇更適合您正在創建的應用類型的變體：

   

5. 還有一個方便的按鈕，用於將代碼複製到剪貼板：

   

結論

您現在知道了使用的基礎知識Insomnia向Brightcove API發出請求。請注意，如果您選擇升級免費Insomnia帳戶到團隊帳戶，您還可以同步所有請求和環境，並與其他團隊成員共享。