從 REST API 建立規則

您可以使用 IoT 工具 HTTP REST API 來建立及配置規則。使用這些規則來傳送事件驅動通知以及觸發動作。

附註: 針對 Maximo® Monitor 8.8 以及更新版本所建立的裝置不使用邏輯或實體介面。

若要使用 HTTP REST API，您需要瞭解下列資訊：

您的組織 ID。
當您向 IoT 工具登錄時，會為您提供一個組織 ID ，它是您帳戶的唯一 6 個字元 ID。
您的 API 金鑰和鑑別記號。
您可以使用儀表板來產生 API 金鑰和鑑別記號。如需 API 金鑰和記號的相關資訊，請參閱 API 金鑰連線。
要與 rule.To 尋找邏輯介面 ID ，請使用下列 HTTP REST API: GET /draft/logicalinterfaces

下列範例顯示如何使用 CURL 來擷取邏輯介面的相關資訊：

curl --request GET \
   --url https://yourOrgID.{{site.data.keynote.software_base_url}}/api/v0002/draft/logicalinterfaces \
   --user '{API Key}:{authorization token}'

下列範例顯示 GET 方法的回應：

{
    "results": [
        {
            "id": "5846ed076522050001db0e12",
            "name": "Thermometer Interface",
            "alias": "IThermometer",
            "description": "Thermometer Logical Interface",
            "schemaId": "5846ec826522050001db0e11",
            "version": "draft",
            "created": "2017-06-16T15:41:49Z",
            "createdBy": "a-8x7nmj-9iqt56kfil",
            "updated": "2017-06-16T15:41:49Z",
            "updatedBy": "a-8x7nmj-9iqt56kfil",
            "refs": {
                "schema": "/api/v0002/draft/schemas/5846ec826522050001db0e11",
                "rules": "/api/v0002/draft/logicalinterfaces/5846ed076522050001db0e12/rules"
            }
        }
    ],
    "meta": {
        "total_rows": 1
    }
}

在此範例中，邏輯介面 ID 是 5846ed076522050001db0e12。

配置規則 - 實務範例

此情況顯示如何建立兩個規則，並以情況：配置一般邏輯介面中建立的配置為基礎。

第一個規則稱為 tempRuleMax，當 IoT 工具收到導致裝置狀態的 temperature 內容超過攝氏 44 度的溫度事件時，即會觸發此規則。第二個規則稱為 tempRuleMin，當 IoT 工具收到導致裝置狀態的 temperature 內容低於攝氏 10 度的溫度事件時，即會觸發此規則。

然而，我們不希望將規則條件的溫度臨界值寫在程式中，因為這不容許臨界值隨裝置實例改變。相反地，溫度臨界值在裝置 meta 資料上定義為屬性，規則條件使用 $instance 變數來引用這些屬性。此實物範例使用在實物範例：配置一般邏輯介面中建立的 tSensor 裝置。此裝置會發佈以攝氏度數測量的溫度事件。下列 meta 資料與 tSensor 裝置實例相關聯：

{
    "tempThresholdMax": 44,
    "tempThresholdMin": 10
}

提示：從儀表板的裝置資訊頁面建立裝置實例後，可以將 meta 資料新增或更新至裝置實例。

請完成下列步驟來配置這兩個規則：

選取您要與規則產生關聯的邏輯介面。在此情況中，我們使用 ID 為 5846ed076522050001db0e12 的邏輯介面。
使用下列 API 來檢視與邏輯介面相關聯的現行規則:
GET /draft/logicalinterfaces/5846ed076522050001db0e12/rules
因為目前沒有任何規則與邏輯介面 5846ed076522050001db0e12相關聯，所以會傳回空清單。

使用下列 API 來新增稱為 tempRuleMax 的規則:

POST
/draft/logicalinterfaces/5846ed076522050001db0e12/rules

在要求內文中包括規則名稱、條件參數及通知策略參數:

 {  
     "name" : "tempRuleMax",
     "condition" : "$state.temperature > $instance.metadata.tempThresholdMax",
     "notificationStrategy": {
         "when": "every-time"
     }
 }

下列範例顯示 POST 方法的回應：

 {  
     "name": "tempRuleMax",  
     "id": "5a71991e59080100328710e9",  
     "logicalInterfaceId": "5846ed076522050001db0e12",  
     "condition": "$state.temperature > $instance.metadata.tempThresholdMax",
     "notificationStrategy": {
         "when": "every-time"
     },  
     "version": "draft",  
     "created": "2018-01-31T10:23:26Z",  
     "createdBy": "a-7p9t2v-zsrcacabpa",  
     "updated": "2018-01-31T10:23:26Z",
     "updatedBy": "a-7p9t2v-zsrcacabpa",
     "refs": {  
         "logicalInterface": "/api/v0002/draft/logicalinterfaces/5846ed076522050001db0e12"  
     }
 }

如果裝置狀態上的溫度屬性超出 tSensor 裝置實例的 meta 資料的 tempThresholdMax 屬性中指定的值，則會觸發 tempRuleMax 規則。在我們的範例中，此值是攝氏 44 度。

使用下列 API 來新增稱為 tempRuleMin 的規則:

POST
/draft/logicalinterfaces/5846ed076522050001db0e12/rules

在要求內文中包括規則名稱、條件參數及通知策略參數:

 {  
     "name" : "tempRuleMin",
     "condition" : "$state.temperature < $instance.metadata.tempThresholdMin",
     "notificationStrategy": {
         "when": "every-time"
     }
 }

下列範例顯示 POST 方法的回應：

 {  
     "name": "tempRuleMin",  
     "id": "5a71991e59080100328710e10",  
     "logicalInterfaceId": "5846ed076522050001db0e12",  
     "condition": "$state.temperature < $instance.metadata.tempThresholdMin",
     "notificationStrategy": {
         "when": "every-time"
     },  
     "version": "draft",  
     "created": "2018-01-31T10:23:26Z",  
     "createdBy": "a-7p9t2v-zsrcacabpa",  
     "updated": "2018-01-31T10:23:26Z",  
     "updatedBy": "a-7p9t2v-zsrcacabpa",
     "refs": {  
         "logicalInterface": "/api/v0002/draft/logicalinterfaces/5846ed076522050001db0e12"  
     }
 }

如果裝置狀態上的溫度屬性低於 tSensor 裝置實例的 meta 資料的 tempThresholdMin 屬性中指定的值，則會觸發 tempRuleMin 規則。在我們的範例中，此值是攝氏 10 度。

使用 activate-configuration 作業來驗證及啟動配置。
您必須在新增規則之後啟動配置，因為新增規則的動作會導致對草稿模型的變更。您可以在裝置類型或邏輯介面的草稿版本上執行 activate-configuration 作業。下列範例顯示在裝置類型的草稿版本上執行 activate-configuration 作業的 PATCH 要求：
```
PATCH /draft/device/types/{typeId}
```
其中，PATCH 主體的有效負載包含下列內容：
```
 {
     "operation": "activate-configuration"
 }
```

使用下列 API 來檢視作用中邏輯介面上的現行規則:

GET
/logicalinterfaces/5846ed076522050001db0e12/rules

下列範例顯示 GET 方法的回應:

 [
     {
         "name": "tempRuleMax",  
         "id": "5a71991e59080100328710e9",
         "logicalInterfaceId": "5846ed076522050001db0e12",
         "condition": "$state.temperature > $instance.metadata.tempThresholdMax",
         "notificationStrategy": {
             "when": "every-time"
         },  
         "version": "active",
         "created": "2018-01-31T10:23:26Z",
         "createdBy": "a-7p9t2v-zsrcacabpa",
         "updated": "2018-01-31T10:23:26Z",
         "updatedBy": "a-7p9t2v-zsrcacabpa",
         "refs": {
             "logicalInterface": "/api/v0002/logicalinterfaces/5846ed076522050001db0e12"
         }
     },
     {
         "name": "tempRuleMin",  
         "id": "5a71561e59055500328710e10",
         "logicalInterfaceId": "5846ed076522050001db0e12",
         "condition": "$state.temperature < $instance.metadata.tempThresholdMin",
         "notificationStrategy": {
             "when": "every-time"
         },  
         "version": "active",
         "created": "2018-01-31T10:23:26Z",
         "createdBy": "a-7p9t2v-zsrcacabpa",
         "updated": "2018-01-31T10:23:26Z",
         "updatedBy": "a-7p9t2v-zsrcacabpa",
         "refs": {
             "logicalInterface": "/api/v0002/logicalinterfaces/5846ed076522050001db0e12"
         }
     }
 ]

如需使用 API 的詳細資料，請參閱本端 API 文件中的 [IoT 工具 HTTP REST API。如需存取本端說明文件的相關資訊，請參閱 API。

耗用規則通知。您現在可以設定動作，或將外部應用程式配置成耗用規則的輸出。如需相關資訊，請參閱耗用規則通知。