了解字串欄位的最佳做法
下列文章包含 Power Automate、Power Apps 和 Azure Logic Apps 的連接器中字串欄位的一般指引。
連線資訊
每個連接器都應該有標題 (也是連接器的名稱) 和描述 (一般來說，用於描述連接器)。 此資訊應在 OpenAPI 定義 (位於 apiDefinition.swagger.json 檔案) 中_資訊_區段底下的_標題_和_描述_欄位中指定。
連接器標題和描述至少應遵循下列指導方針：
- 連接器標題最多可有 30 個字元。
- 連接器標題和描述不能包含
API一字。 - 連接器標題和描述不能參照 Power Platform 產品，也不能參照您未擁有其後端 API 的產品。
可以在這裡找到標題和描述欄位指導方針強加於認證連接器的更高標準，而且應該作為最佳做法使用。
作業
OpenAPI 定義中的每個路徑和指令動詞都會對應至某個作業。 使用以下每個字串/標記正確地描述作業，可協助使用者正確使用它。 作業的某些字串欄位是：
摘要：這會顯示為作業的名稱。
- 案例：句子
- 附註：
- 名稱中不應有斜線 ('/')。
- 其不得超過 80 個字元。
- 其結尾不得為非英數位元，包括標點符號或空格。
描述：選取資訊按鈕時，這將顯示為作業描述
，如下圖所示。- 案例：句子。
- 注意：保持簡短以納入文字方塊中。 如果是一個單字，則不需要句號。
operationId：這是與作業相關聯的唯一識別碼。
- 案例：Camel (不含空格或標點)。
- 附註：用於傳達作業的意義，例如 GetContacts 或 CreateContact。
下圖顯示在建立工作流程時，摘要—傳送電子郵件和_描述_—此作業會傳送電子郵件訊息欄位會如何顯示。
觸發程序與動作
觸發程序可啟動工作流程或程序。 例如，「每星期一上午 3 點啟動工作流程」、「在物件建立時」等等。
觸發程序摘要和描述欄位應該是人類可讀的格式且具有語意意義。 觸發程序_摘要_的格式通常為：「__________________時」。
範例:
| 觸發程序 | 綜合 |
|---|---|
| 建立 | 建立工作時 |
| 更新 | 更新工作時 |
| 已刪除 | 刪除工作時 |
觸發程序_描述_的格式通常為：「此作業會在_______________時觸發」
範例:
- 此作業會在新增工作時觸發。
動作就是在您的工作流程內完成的工作，例如「傳送電子郵件」、「更新資料列」、「傳送通知」等等。 _摘要_動作的一些範例如下：
| 動作 | 綜合 |
|---|---|
| 建立 | 建立新工作 |
| 參閱 | 依識別碼取得工作 |
| 更新 | 更新物件 |
| 已刪除 | 刪除物件 |
| 清單 | 列出所有物件 |
參數
每個作業 (不論是觸發程序或動作) 都有使用者當作輸入提供的參數。 參數的某些重要字串欄位是：
x-ms-summary：這會顯示為參數名稱。
- 案例：標題
- 注意：有 80 個字元的限制
描述：這將在輸入方塊中顯示為參數描述。
- 案例：句子
- 注意：保持簡短以納入文字方塊中。 如果是一個單字，則不需要句號。
在下圖中，醒目提示的參數是以「主旨」作為 x-ms-summary 欄位的值，並以「指定郵件主旨」作為 描述。
回應
每個作業都有一項回應，該回應稍後可在工作流程中作為後續作業的輸入。 結果結構描述是由多個屬性所組成。 每個屬性的一些重要字串欄位如下：
x-ms-summary：這會顯示為結果屬性名稱。
- 案例：標題
- 注意：使用簡短名稱。
描述：這會顯示為結果屬性的描述。
- 案例：句子
- 注意：應簡潔有力，並以句號結尾。
在下圖中，當您嘗試在工作流程的其中一個後續作業中新增動態內容時，「手動觸發流程」作業的結果結構描述會顯示。 在這裡，「使用者電子郵件」是 x-ms-summary，而其下的文字是「手動觸發流程」作業回應中屬性的 描述。
一般而言，摘要/x-ms-summary 和描述欄位所要考量的一些重要注意事項如下：
- 摘要和描述文字應不相同。
- 描述應用來提供其他資訊給使用者，例如輸出格式或屬性相關物件。 例如：摘要：識別碼，描述：使用者的識別碼。
- 如果物件具有巢狀值，則上層名稱的 x-ms-summary 會附加到下層。
x-ms-visibility
決定實體的可見性優先順序。 若未指定可見性，則被視為「一般」可見性。 可能的值為「重要」、「進階」或「內部」。 標示為「內部」的實體不會顯示在使用者介面中。
適用於：
- 作業
- 參數
- 回覆屬性
範例：
在 UI 中，標示為「重要」的實體會先顯示，標示為「進階」的項目會隱藏在切換開關 (已醒目提示) 之下，而標示為「內部」的項目則不會顯示。 下圖是預設顯示標示為「重要」的參數範例。 其還顯示標記為「進階」的參數在選擇顯示進階選項按鈕後顯示。
提供意見反應
非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。 若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。