IoT Studio創建公開API

開發內容

公開API由IoT Studio的服務編排創建，以HTTP請求與HTTP返回的方式提供調用端口。與直接創建的“HTTP請求/返回”對相比，公開API不需要鑑權的AppKey與AppSecret，支持公網訪問。

開發過程

STEP1 使用模板創建

在IoT Studio的項目管理頁面中，選擇從模板新建業務服務，如圖下圖所示。

如下圖所示，右上角單擊展開更多模板，找到最後一個模板：公開API。

業務邏輯名稱隨意，模板信息中可以看到，使用該模板創建的業務服務包含三個節點：HTTP請求、腳本節點和HTTP返回。單擊使用該模板新建。

STEP2 配置節點

創建完成後會自動跳轉到服務編輯器頁面。依次對節點進行配置。

HTTP請求節點：

節點配置如下圖所示，配置Action參數為：public_api

Node.js腳本節點：

節點配置如下圖所示，將返回的payload內容修改為："hello Saxon"

HTTP返回節點不需要進行修改，保持默認配置即可。
單擊右上角的保存後部署併發布業務服務。

STEP3 獲取API域名

在服務列表中右鍵單擊新建的服務，選擇服務調用幫助。

彈出服務詳情頁面如下圖所示：

API Path即調用API的域名，單擊行末的複製。

注意

在發佈->域名管理頁面下也可以找到一個域名地址，如下圖所示。

顯示為默認API訪問域名，但這個域名並不是調用API的域名！

筆者就是誤認為這個域名是調用API的域名，測試的請求結果為400，浪費了很久的時間。

STEP4 獲取參數

在STEP2 配置節點中，我們沒有對HTTP請求節點進行添加入參的操作，但這並不意味著對這個API的請求不需要參數。
向下滾動服務詳情頁面，找到請求示例，這裡提供了調用的API的示例代碼。切換比較直觀的Python版本，如下圖所示：

代碼中bodyMap和Headers的聲明，分別代表了請求主體信息和請求頭信息。

bodyMap的內容如下：

{
    'id': str(uuid.uuid4()),
    'version': "1.0",
    'request': {
        'iotToken': "xxxx",
        'apiVer': "1.0.0"
    },
    'params': {
        # 接口參數
        
        'action':"public_api",
    }
}

其中uuid模塊用於根據使用的網卡和時間信息生成一個隨機的字符串。此處我們要根據樣例代碼獲知需要提供的參數信息，所以可以以隨機字符串代替。去除換行符與註釋，整理如下：
{'id':'random_id','version': "1.0",'request': {'iotToken': "xxxx",'apiVer': "1.0.0"},'params': {'action':"public_api"}}

header的內容如下：

{
    'accept': 'application/json'
}

也就是說，我們要在頭信息中添加一條這樣的鍵值： 'accept': 'application/json'。

另一種參數

根據幫助文檔：公開API，與貔閣同學提供的參考截圖：
截圖.png

我們需要在HTTP請求的Body中加入參數如下：

{'params':{'action':'public_api'},'request':{'apiVer':'1.0.0'},'version':'1.0','id': 12}

並且要在請求頭信息中註明主體信息的編碼方式為application/json

STEP5 使用POSTMAN測試請求

一切準備就緒，下面可以使用POSTMAN來實際測試API了。
啟動POSTMAN，新建HTTP請求如下圖所示：

請求方式為POST，域名使用STEP3中獲取的域名。由於貔閣提供的請求參數有成功的前車之鑑，先來測試他的方法：

貔閣的請求參數

在Header中添加body內容格式的信息，如下圖所示：

由於application/json不屬於POSTMAN預設的主體信息格式。body選項卡中，選擇信息的格式為raw，並粘貼STEP4中獲取的參數到主體信息中。如下圖所示。

一切準備就緒，單擊Send，返回結果如下圖：

返回的數據為"hello Saxon"，與我們在服務開發中節點配置的內容一致。請求成功。

請求示例的參數

同樣的步驟，新建一條請求如圖：

這次Header中鍵名輸入accept，鍵值不變。

填寫body內容如圖所示：

單擊Send，返回成功信息如下圖所示：

以上，兩種參數填寫方法都是可行的。

非公開API

前面的內容，我們基於公開API模板進行的服務創建。下面來探討，如果是不使用模板，搭建完全相同的節點。會有什麼不同。
項目下直接新建業務服務如圖：

參考公開API模板，添加節點：HTTP請求、Node.js腳本、HTTP返回。將三者連接並配置HTTP請求如下圖所示：

Action參數為：api_test

同理，複製模板中Node.js腳本的代碼，配置節點如圖：

HTTP返回節點不需要修改，保持默認。
保存，部署併發布服務。打開服務調用幫助，這裡的頁面出現了區別：

相比公開API模板創建的服務，這裡多出了項目AppKey與AppSecret。

向下滾動頁面，查看Python的示例代碼：

這裡也出現了不同，需要在客戶端初始化時進行鑑權過程。
所以這裡創建的並不是公開API，公網可以訪問，但是要經過鑑權。

猜想

注意到bodyMap中包含了iotToken項，鍵值為無意義的xxxx。而iotToken常用於物聯網設備HTTP連接的鑑權。猜想在非公開API的調用過程中，sdk根據appKey與appSecret建立連接得到iotToken。接著替換bodyMap中的對應項，在實際API調用過程中，起到鑑權作用的只是iotToken。換言之，如果得到了正確的iotToken，僅使用POSTMAN也可以完成非公開API的調用。
測試內容待補充。

Saxon
2020-3-8 15:25

IoT Studio 公開API 攻略