Postman Tutorial: Disqus REST API #1

Postman 教學: Disqus REST API 案例研究(1) – 列取討論串的詳細信息

甚麼是 Postman

Postman 圖標

Postman 是在嘗試測試 RESTful API 時一個很好的工具,它提供人性化的 GUI 界面,讓您能輕易地傳送用於測試 API 功能的 HTML 請求,使您不需煩惱怎樣編寫程式碼。您只需做將 API 端點的 URL 複製到地址欄,在左側的下拉框中選擇 HTTP 請求方法,再於快速編輯表格中或以 JSON 格式填入查詢參數。之後點擊發送,Postman 就會以 JSON 格式整潔地顯示將 API 回應數據。有了 Postman,API 測試程序就這麼簡單!

因此,它可說是必備的物聯網(IoT)項目開發工具。在 IoT 裝置與 Web 應用程序之間的連接,經常會用上各式各樣的 APIs,甚至會構建專用的。例如,獲取設備與伺服器的狀態,以及向電腦及智能手機發送消息的管道。 您可以利用 Postman 來測試發送及接收往來 API 的數據。

接下來,讓我們開始做一些練習,體驗如何使用 Postman 從公開的 API 服務中獲取數據。在下文的部份中,將會有以 Disqus REST API 為例的練習,讓您試探怎樣通過 API 進行溝通,獲取在 Disqus 留評系統上存儲的數據。如果您是 Postman 的初學者,可觀看下方的官方教學影片系列,首先學習它的基礎知識及使用技巧。

[ 返回目錄 ]


使用 Postman 訪問 Disqus REST API

Disqus 是供讀者對線上內容進行討論的留評系統,而在網頁上的評論堆疊被稱為討論串 (thread)。Disqus 上的評論是可用於趨勢統計和自然語言分析的數據源。您可以構建應用程序,通過從 API 來獲取數據,再從數據中消化出有趣的信息。

使用 Postman,您可以快速測試 API 端點與參數,然後匯出成應用程序的代碼。本文包含兩個初學者程度的練習,第一個練習如何列取指定 Disqus 留言板的討論串,第二個則是嘗試分別通過討論串 ID,識別號或來源網址來查詢討論串的詳細信息。

在此之前,您需要進行以下的準備工作:

  1. 獲取您的 Disqus API 密鑰
  2. 在 Postman 中創建新的個人工作區
  3. 在 Postman 中創建新作業環境以存儲變數

事前準備

獲取您的 Disqus API 密鑰

Disqus API 是通過 HTTP 協議操作的,它同時支援伺服器端的 secret key 方法,以及以 Public key 和 HTTP 參照位址檢查加密的公開 JavaScript API。當您傳送公開的 API 請求時,需要以 api_key 參數附上公共密鑰。因此,您必須在此頁面上註冊,以獲取您的應用程序密 (https://disqus.com/api/applications/)。

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 1
  1. 點擊 Register new application (註冊新應用程式) 按鈕。
Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 2
  1. 在註冊表格中,填寫您的應用程序的名稱與說明,以及您的組織和網站。
Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 3
  1. Application Settings (應用程序設置) 中, 滾動到 Authentication (驗證) 部分,選擇 Disqus API 的 scope (訪問範圍
    )。
Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 4
  1. 移至 Settings (設置) > Domains (網域),添加將可通過安全檢查訪能夠問 API 的域名。

之後,您可以在 Details (詳細信息) 頁面中找到已註冊應用程序的 API 密鑰。

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 5

在 Postman 中創建新的個人工作區

在您的電腦開啟 Postman。我建議首先創建一個新的工作區 (workspace)。這樣,可以將各項目隔離,即使您不熟悉 Postman,則可防止覆寫參數記錄。您可以創建無限的個人工作區。要創建新的工作區,請選擇 Postman 頂部中間的下拉菜單,然後點擊 Create New (新建),輸入名稱 (例如 Disqus API) 以標識您的工作空間。

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 6
創建一個新的工作區

在 Postman 中創建新作業環境以存儲 API 密鑰

當訪問 API 時,通常會包含一些敏感數據,例如 API 密鑰和憑據。通過設置作業環境 (environment),您可以將數值存儲為環境變數,以防止意外共享您的資料。就以 Disqus API 為例,添加一個變數名為 api_key,然後在值欄位上貼上您的公鑰。

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 7
Disqus Env 的 Postman 作業環境設置

[ 返回目錄 ]


練習 1 – 使用 Disqus API 端點列取討論串

forum/listThreads

說明文件: https://disqus.com/api/docs/forums/listThreads/

訪問 forum/listThreads 端點能夠取得指定論壇中的討論串 列表 (按創建日期排序)。訪問它並不需要驗證,僅需要 api_keyforum 兩個參數。又或者,您可使用 threads/list 端點以 forumcategoryauthor 及其他參數來搜尋討論串,此兩個端點所回傳數據為相同結構。訪問 forum/listThreads 端點的設置如下:

方法GET
網址https://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
存儲在您作業環境中的公鑰
forumDisqus 留言板的短名稱

執行前,請確認選擇的作業環境,以保證呼叫正確的環境變數。該 API 請求應如以下截圖所示:

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 8
回應
JSON
{
  "cursor": {
    "prev": null,
    "hasNext": true,
    "next": "1591067876042540:0:0",
    "hasPrev": false,
    "total": null,
    "id": "1591067876042540:0:0",
    "more": true
  },
  "code": 0,
  "response": [
    {
      "feed": "https://shortname.disqus.com/pond_race_juegalo_juegos_gratis_online/latest.rss",
      "clean_title": "pond race | Juegalo - juegos gratis online",
      "dislikes": 0,
      "likes": 0,
      "message": "",
      "ratingsEnabled": false,
      "isSpam": false,
      "isDeleted": false,
      "category": "40878",
      "adsDisabled": false,
      "author": "99012",
      "userScore": 0,
      "id": "8090350709",
      "signedLink": "https://https-www-juegalo-com-co.disqus.com/",
      "createdAt": "2020-06-22T21:59:23",
      "hasStreaming": false,
      "raw_message": "",
      "isClosed": false,
      "link": "https://https-www-juegalo-com-co.disqus.com/",
      "slug": "pond_race_juegalo_juegos_gratis_online",
      "forum": "shortname",
      "identifiers": [],
      "posts": 0,
      "userSubscription": false,
      "validateAllPosts": false,
      "title": "pond race | Juegalo - juegos gratis online",
      "highlightedPost": null
    }
  ]
}

上面的 JSON 數據是 forum/listThreads 端點回應的例子,因為添加了參數 limit = 1 來限制結果數,所以僅回傳了一個討論串的資料。要加載更多結果,從回應中複制 cursor.next 的值,然後在查詢中添加 cursor 參數進行分頁

[ 返回目錄 ]


練習 2 – 獲取 Disque 討論串的詳細信息

threads/details

說明文件: https://disqus.com/api/docs/threads/details/

訪問 threads/details 能夠取得某一個指定討論串的資料,它包含三種查詢方式:

按 ID 來尋找討論串

方法GET
網址https://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
在您作業環境中的公鑰
threadDisqus 討論串 ID

identifier (識別號) 及留言板的短名稱來尋找討論串

方法GET
網址https://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
存儲在您作業環境中的公鑰
thread:identDisqus 討論串的識別號
forumDisqus 留言板的短名稱

按來源網址及留言板的短名稱來尋找討論串

方法GET
網址https://disqus.com/api/3.0/forums/listThreads.json
api_key{{api_key}}
存儲在您作業環境中的公鑰
thread:link來源網址
forumDisqus 留言板的短名稱
回應
JSON
{
  "code": 0,
  "response": {
    "feed": "https://shortname.disqus.com/pond_race_juegalo_juegos_gratis_online/latest.rss",
    "canModerate": false,
    "clean_title": "pond race | Juegalo - juegos gratis online",
    "dislikes": 0,
    "likes": 0,
    "message": "",
    "ratingsEnabled": false,
    "isSpam": false,
    "isDeleted": false,
    "category": "40878",
    "adsDisabled": false,
    "author": "99012",
    "userScore": 0,
    "id": "8090350709",
    "signedLink": "https://https-www-juegalo-com-co.disqus.com/",
    "createdAt": "2020-06-22T21:59:23",
    "hasStreaming": false,
    "raw_message": "",
    "isClosed": false,
    "link": "https://https-www-juegalo-com-co.disqus.com/",
    "slug": "pond_race_juegalo_juegos_gratis_online",
    "forum": "shortname",
    "identifiers": [],
    "posts": 0,
    "userSubscription": false,
    "validateAllPosts": false,
    "title": "pond race | Juegalo - juegos gratis online",
    "canPost": true,
    "highlightedPost": null
  }
}

[ 返回目錄 ]


使用 Postman 生成 Python Requests 程式碼

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 9
點擊 “Code” 生成程式碼

您可以使用 Postman 生成在其他平台呼叫 API 請求的程式碼。在測試好 API 請求之後,點擊在 Send 和 Save 按鈕下方的 “Code” 字,就會彈出一個對話框供您選擇編程語言並預覽生成的程式碼。以下截圖是 Python 的代碼片段示例。

Postman教學: Disqus REST API 案例研究(1) - 列取討論串的詳細信息 10

要測試 Python 代碼,您可以在 Google Colab 上打開一個 Jupyter 筆記本。將代碼複製到筆記本中,然後按 Ctrl + Enter 運行,應當回傳與 Postman 中相同的 API 回應。


了解更多

注意:本文包含會向本人發放小額佣金之推廣連結,並不會在您購買商品時產生任何額外費用。


小結

跟蹤此案例研究,您應該了解到如何使用 Postman 從 Disqus REST API 訪問其公開數據。第 1 步,在 Disqus 上註冊應用程序獲取您的 API 密鑰。第 2 步,在 Postman 中為您的項目創建一個工作區和作業環境。第 3 步,使用 Postman GUI 構建與發送 GET 請求(如:根據 Disqus API 文檔輸入端點 URL 和查詢參數)。您可以將此應用於探索和跟踪熱門話題。

繼續閱讀

如果您喜歡這篇文章,請分享到您的 Facebook 和 Twitter。您也可以通過 Ko-fi 捐款支持本站。

Scroll to Top