新增查詢
查詢是唯讀機制，其可查詢服務以取得值清單，且該清單會顯示為下拉清單。查詢可基於表單中已提供資訊的其他項目。若使用查詢，便不需要在配置「動作」或「觸發器」時手動輸入或記住與協力廠商帳戶資源關聯的值。
在動作與觸發器中使用查詢。為顯示許多項目，查詢會使用分頁機制。
查詢支援初始資料篩選。例如，若您在查詢欄位中鍵入文字並按一下箭頭，會顯示包含文字的值清單。
與其他加工品不同，查詢並非在外部版本化。每個查詢呼叫都是查詢加工品中的一個函數。因此，每個連接器有一個查詢加工品。
例如，下圖中有一個查詢動作。該查詢會從 Gmail 擷取使用者的電子郵件，這些值會顯示在「郵件 ID」中作為輸入。之所以會如此可能是因為結構描述指定了查詢可用於此欄位。
您需要電子郵件帳戶的 id，才能實行 get-mail-details 動作。查詢指令集會使用 Gmail 帳戶的驗證來搜尋您帳戶中的所有電子郵件。之後，清單會顯示在「動作」表單中，您可以選取適當 id 作為「查詢」。
欲建立新查詢，請執行下列操作：
1. 從指令提示中，執行下列指令：
a. cd <user project root directory>
b. flow add lookup
查詢名稱就是連接器的名稱，它會在專案目錄中的查詢資料夾中建立。
此指令有下列選項可用。
選項 | 描述 | 資料類型 |
|---|---|---|
--version | 顯示版本編號。 | [布林值] |
--help | 顯示說明 | [布林值] |
--parentDir, -d | 專案的父目錄。 | [預設："."] |
--logLevel, -1 | 設定記錄層級。 | [預設："info"] |
2. 更新 index.js 檔案中的內容。
查詢 JavaScript 應匯出單一 JavaScript 物件。此物件可以包含任意數目的方法。index.js 檔案具有下列結構。
function(input, options, output){
return}
return}
 | 如果外部服務使用「連線」而非 OAuth，程式碼可能會有所不同。 |
選項物件將提供一些查詢中需要使用的公用程式方法。
validateDependencies(input.<property name>) - 檢查輸入中是否包含指定內容。
options.getAccessToken(input.auth, function(err, data) { }): Fetch the access token from the server. input.auth contains a UID that is used to fetch the access token. options.getConnection(input.connection, function(err, data){ }) : Fetch the connection corresponding to the UID contained in the connection property.
如需可在「查詢」中使用之 SDK for API 的相關資訊，請參閱
ThingWorx Flow 連接器 SDK 部份。
下表描述了如何使用引數。
引數 | 使用方式 |
|---|---|
input | 包含針對查詢配置的相依性。 |
options | 提供公用程式方法，可用來擷取驗證機制、「連線」或「存取」權杖，及啟用分頁支援。 |
output | 必須呼叫才能將結果傳回至 ThingWorx Flow 的回撥。它遵循節點的錯誤優先慣例。 結果必須是 JSON 物件的陣列。一般而言，其為 id 和值對。如果新增動態結構描述，則可能會新增其他欄位。如需詳細資訊，請參閱「動態結構描述插入」部份。 必須將結果傳遞至回撥 (輸出函數)，且其必須為包含 id 與值之 JSON 物件的陣列。 結果格式應該如下： { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
動態結構描述插入
如果動作有固定輸入與輸出結構描述，它會在建構功能豐富的動作時建立限制。當載入查詢或從查詢中選取值時，可以根據使用者選擇更新動作的輸入與輸出結構描述。因此，表單會更新以符合保留目前值的已更新輸入結構描述。此外，可用於在下一個動作對應的輸出欄位也會更新，以符合更新的輸出結構描述。
動作輸入與輸出結構描述的更新可在查詢結果處理介面執行。
您可以在傳回查詢結果的同時插入動態結構描述，也可以透過 onSelect 屬性 (針對所選選項) 新增其他函數到查詢。若在載入查詢時插入，動態結構描述插入需要所有查詢值的結構描述。
| | 某些物件也許能夠使用兩個連續查閱執行多層級插入。多層級插入可以附加限制，但無法移除。 |
新增表單顯示之輸入結構描述的方式為，針對 id 與 value 旁邊的查詢，對產生的 JSON 使用 schema、parent 及 append 屬性。同樣，使用 outSchema、outAppend 與 outParent 新增輸出結構描述，當開啟連線動作時，其會顯示為動作的輸出結構描述。一般而言，當將提供的結構描述附加至指示來延伸內容的父項時，append 或 outAppend 與 parent 或 outParent 會搭配使用。如果未使用 append，結構描述會由新增的結構描述所取代。
parent 或 outParent 屬性是對應結構描述之結構描述元素 (必須為 object 類型) 的 id。如果沒有 parent 或 outParent 屬性，更新的預設前後關聯為對應結構描述的根。結構描述更新發生在 parent 或 outParent 物件的範圍內，具體方式為在沒有 append/outAppend 的情況下透過合插入結構描述中提供的內容與現有內容，或將插入結構描述中提供的內容取代為現有內容。
您也可以在插入的輸出結構描述中使用 userSelected 屬性。當您從表單中選取選項時，此功能可用來插入預設結構描述 (值為 false)，並在將其取代為子集 (值為 true)。如果在刪除表單的陣列元素時移除 userSelected = true 屬性，結構描述會恢復為預設值。
例如，對於 OData 連接器，請依下圖所示設定輸入與輸出插入結構描述：
OData 的輸入插入結構描述如下：
"schema": {
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
OData 的輸出插入結構描述如下：
"outSchema": {
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
如上述範例所建議，如需將少數參數固定在以動態方式插入之輸出結構描述中的對應使用者介面上，可依如下所示設定內容：visible = true。
分頁
查詢支援分頁，即能夠產生多頁結果。每個引動過程會產生一頁結果。在使用者介面中，可以透過按一下清單中的 <更多結果> 來擷取頁面。輸入與選項物件包含用於處理分頁的方法和內容。
• options.getNextPage(boolean) - 用於分頁，以返回擷取下一個頁面的 URL。必須在結果物件的 "next_page" 內容中設定此 URL，分頁才能正確運作。如果沒有更多頁面需要傳回，可將此內容設定為 false。
• options.maxResults - 與分頁搭配使用，來取得一次可傳回的最大結果數。
• input.page - 目前的頁碼。
• input.searchById - 依 id 搜尋。
• input.searchByValue - 依值搜尋。
查詢的可供搜尋旗標設定為 true 時，依 Id 搜尋與依值搜尋才可用。有關查詢的範例，請參閱上述部份。這些內容可透過在目標系統中搜尋符合 Id 或值的項目來協助縮小搜尋範圍。
| | Id 與值可能涉及目標系統中的不同欄位。 |