共用方式為

了解字串欄位的最佳做法

  • 發行項

本文提供 Microsoft Power Automate、Microsoft Power Apps、Microsoft Copilot Studio 和 Azure Logic Apps 的連接器中字串欄位的一般指引。

連線資訊

提供有關連接器的基本資訊非常重要。 若要開始，請遵循此區段中概述的基本準則。 連接器的名稱位於標題欄位中 。 連接器的描述位於 _description_ 欄位中。 這兩個欄位都在 OpenAPI 定義 (apiDefinition.swagger.json 檔案) 的資訊區段中。

下面是連接器標題和描述要遵循的一些最低要求：

  • 連接器標題最多可有 30 個字元。
  • 連接器標題和描述不能包含 API 一字。
  • 連接器標題和描述不能參照 Power Platform 產品，也不能參照您未擁有其後端 API 的產品。

有關認證連接器準則的詳細資訊，請移至認證提交文章。 參考以尋求最佳做法。

營運

OpenAPI 定義中的每個路徑和指令動詞都會對應至某個作業。 使用以下列出的每個字串/標記正確地描述作業，可協助終端使用者正確使用。 以下是作業字串欄位的一些範例：

  • 摘要顯示為作業的名稱。

    • 案例：句子

    • 附註：

      • 名稱中不應有斜線 ('/')。
      • 其不得超過 80 個字元。
      • 其結尾不得為非英數位元，包括標點符號或空格。

  • 描述顯示為選取資訊按鈕時的作業描述。 顯示資訊按鈕的螢幕截圖。 。

    • 案例：句子。
    • 注意：保持簡短以納入文字方塊中。 如果是一個單字，則不需要句號。

  • operationId 是與作業相關的唯一識別碼。

    • 案例：Camel (不含空格或標點)。
    • 注意：請傳達作業的意義，例如 GetContacts 或 CreateContact。

    下圖顯示在建立工作流程時，摘要—傳送電子郵件和描述—此作業會傳送電子郵件訊息欄位會如何顯示。

    顯示摘要與描述欄位如何顯示的螢幕擷取畫面。

觸發程序與動作

觸發程序可啟動工作流程或程序。 舉幾個例子：

  • 每週一淩晨 3 點開始工作流程
  • 建立物件時

請確認觸發程序摘要和描述欄位是可讀取的格式且具有語意意義。 觸發程序摘要的格式通常為：_當 ___________________時。

範例:

觸發程序 綜合
建立​​ 建立工作時
Update 更新工作時
已刪除 刪除工作時

觸發程序描述的格式通常為：此作業會在_______________時觸發。

範例:

  • 此作業會在新增工作時觸發。

動作就是在您的工作流程內完成的工作，例如傳送電子郵件、更新資料列、傳送通知等等。 底下是摘要動作的一些範例：

動作​ 綜合
建立​​ 建立新工作
參閱 依識別碼取得工作
Update 更新物件
已刪除 刪除物件
清單​​ 列出所有物件

參數

每個作業 (不論是觸發程序或動作) 都有使用者當作輸入提供的參數。 參數的某些重要字串欄位是：

  • x-ms-summary 會顯示為參數名稱。

    • 案例：標題
    • 注意：此字串欄位的限制為 80 個字元

  • 描述在輸入方塊中顯示為參數描述。

    • 案例：句子
    • 注意：描述應保持簡短以納入文字方塊中。 如果是一個單字，則不需要句號。

    下圖突出提示的參數是以主旨作為 x-ms-summary 欄位的值，並以指定郵件主旨作為描述。

    顯示介面中 x-ms-summary 及描述參數值的螢幕擷取畫面。

回應

每個作業都有一項回應，該回應稍後可在工作流程中作為後續作業的輸入。 結果結構描述是由多個屬性所組成。 每個屬性的一些重要字串欄位如下：

  • x-ms-summary 顯示為結果屬性名稱。

    • 案例：標題
    • 注意：使用簡短名稱。

  • 描述顯示為結果屬性的描述。

    • 案例：句子
    • 注意：描述應保持簡短，並以句號結尾。

    在下圖中，當您嘗試在工作流程的其中一個後續作業中新增動態內容時，會顯示手動觸發流程作業的結果結構描述。 在這裡，使用者電子郵件是 x-ms-summary，而其下方的文字是手動觸發流程作業回覆中屬性的描述。

回覆

底下是一些摘要/x-ms-summary 和描述欄位要考量的重要注意事項：

  • 摘要和描述文字應不相同。
  • 描述提供其他資訊給使用者，例如輸出格式或屬性相關物件。 例如：摘要：識別碼，描述：使用者的識別碼。
  • 如果物件具有巢狀值，則上層名稱的 x-ms-summary 會附加到下層。

可視性屬性

實體的可見性優先順序是依 x-ms-visibility 指定。 若未指定可見性，則值會被視為一般可見性。 可能的值為重要、進階或內部。 標示為內部的實體不會顯示在使用者介面中。

可見性適用於：

  • 營運
  • 參數
  • 回覆屬性

以下是範例：

在 UI 中，標示為重要的實體會先顯示，標示為進階的項目會隱藏在切換開關 (已醒目提示) 底下，而標示為內部的項目則不會顯示。 下圖顯示預設標示為重要的參數範例。 您也可以看到標記為進階的參數在選取顯示進階選項按鈕後顯示。

顯示進階選項下拉式清單的螢幕擷取畫面。

顯示展開隱藏進階選項的螢幕擷取畫面。

提供意見反應

非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。 若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。