使用 OpenAPI 擴充功能建立自訂連接器

為 Azure Logic Apps、Microsoft Power Automate 或 Microsoft Power Apps 建立自訂連接器的其中一個方法是提供 OpenAPI 定義檔，這是一個非特定語言專屬的機器可讀文件，用來描述 API 作業與參數。 除了 OpenAPI 的現成功能外，您也可以在建立 Logic Apps 和 Power Automate 的自訂連接器時包含以下 OpenAPI 擴充：

• summary
• x-ms-summary
• description
• x-ms-visibility
• x-ms-api-annotation
• x-ms-operation-context
• x-ms-capabilities
• x-ms-trigger
• x-ms-trigger-hint
• x-ms-notification-content
• x-ms-notification-url
• x-ms-url-encoding
• x-ms-dynamic-values and x-ms-dynamic-list
• x-ms-dynamic-schema and x-ms-dynamic-properties

下列各節會描述這些擴充。

摘要

指定動作 (作業) 的標題。

適用於：作業
建議：對 summary 使用句首大寫。
範例：「When an event is added to calendar」或「Send an email」

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

指定實體的標題。

適用於：參數、回應結構描述
建議：對 x-ms-summary 使用字首大寫。
範例：「Calendar ID」、「Subject」、「Event Description」

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            /// Other parameters here...
            "x-ms-summary": "Subject",
            /// Other parameters here...
        }]
    }
},

描述

指定作業功能或實體格式和功能的詳細說明。

適用於：作業、參數、回應結構描述
建議：對 description 使用句首大寫。
範例："This operation triggers when a new event is added to the calendar"、"Specify the subject of the mail"

"actions" {
    "Send_an_email": {
        "description": "Specify the subject of the mail",
        /// Other action properties here...
    }
},

x-ms-visibility

指定實體面對使用者的顯示性。

可能值：important、advanced 和 internal
適用於：作業、參數、結構描述

• important 作業和參數一律先顯示給使用者。
• advanced 作業和參數隱藏在其他功能表之下。
• internal 作業和參數會隱藏起來，不讓使用者看見。

注意

參數若是 internal 和 required，您必須提供預設值。

範例：查看更多和顯示進階選項功能表是隱藏的 advanced 作業和參數。

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            "name": "Subject",
            "type": "string",
            "description": "Specify the subject of the mail",
            "x-ms-summary": "Subject",
            "x-ms-visibility": "important",
            /// Other parameter properties here...
        }]
        /// Other action properties here...
    }
},

x-ms-api-annotation

用於作業的版本控制和生命週期管理。

適用於：作業

• family — 表示作業系列資料夾的字串。
• revision— 表示修訂編號的整數。
• replacement — 包含取代 API 資訊和作業的物件。

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

用於模擬引發觸發程式，以啟用觸發程式相依流程的測試。

適用於：作業

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

在連接器層級使用時，這會概述連接器所提供的功能，包括特定的作業。

適用於：連接器

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

在作業層級使用時，這會用來識別作業是否支援區塊上傳和 (或) 靜態區塊大小，而且是否可以由使用者提供。

適用於：作業

• chunkTransfer — 布林值，指出是否支援區塊轉送。

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

識別目前的作業是否為產生單一事件的觸發程序。 如果此欄位不存在，即表示這是 action 作業。

適用於：作業

• single — 物件回應
• batch — 陣列回應

"x-ms-trigger": "batch"

x-ms-trigger-hint

說明如何引發觸發程序作業的事件。

適用於：作業

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

包含 webhook 通知要求的結構描述定義。 這是外部服務發佈至通知 URL 的 webhook 承載結構描述。

套用至：資源

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

以布林值識別 Webhook 通知 URL 是否應該放在 webhook 註冊作業的這個參數/欄位中。

適用於：參數/輸入欄位

"x-ms-notification-url": true

x-ms-url-encoding

識別目前的路徑參數是否應為雙倍 URL 編碼的 double 或單一 URL 編碼的 single。 缺少此欄位，即表示 single 編碼。

適用於：路徑參數

"x-ms-url-encoding": "double"

使用動態值

動態值是使用者用來選取運算之輸入參數的選項清單。 

適用於：參數 

如何使用動態值

注意

路徑字串是不包含前置正斜線的 JSON 指標。 因此，這是 JSON 指標： /property/childProperty，這是路徑字串：property/childProperty。

定義動態值有兩種方法：

1. 使用 x-ms-dynamic-values

   姓名	出席者	描述
   operationId	是	傳回值的作業。
   參數	是	提供叫用 dynamic-values 作業所需輸入參數的物件。
   value-collection	否	在回應承載中評估為物件陣列的路徑字串。 如果未指定 value-collection，會將回應評估為陣列。
   value-title	否	value-collection" 內物件的路徑字串，指向值的描述。
   value-path	否	value-collection" 內物件的路徑字串，指向參數值。

   "x-ms-dynamic-values": {
       "operationId": "PopulateDropdown",
       "value-path": "name",
       "value-title": "properties/displayName",
       "value-collection": "value",
       "parameters": {
           "staticParameter": "<value>",
           "dynamicParameter": {
               "parameter": "<name of the parameter to be referenced>"
           }
       }
   }  
   

   注意

   使用動態值時，可能會有不明確的參數參考。 例如，在下列作業定義中，動態值會參考欄位識別碼，這在定義上是不明確的，因為它參考參數 id 或屬性 requestBody/id。

   {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicValuesWithAmbiguousReferences",
       "parameters": [{
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
       }, {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "id": {
                       "description": "The request Id",
                       "type": "string"
                   },
                   "model": {
                       "description": "The model",
                       "type": "string",
                       "x-ms-dynamic-values": {
                           "operationId": "GetSupportedModels",
                           "value-path": "name",
                           "value-title": "properties/displayName",
                           "value-collection": "value",
                           "parameters": {
                               "requestId": {
                                   "parameter": "id"
                               }
                           }
                       }
                   }
               }
           }
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "type": "object"
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

2. x-ms-dynamic-list

   目前沒辦法明確地參考參數。 此功能可能會在未來提供。 如果您想要讓作業使用任何新的更新，請新增擴充功能 x-ms-dynamic-list 與 x-ms-dynamic-values。 此外，如果您的動態擴充功能參考參數中的屬性，則必須新增擴充功能 x-ms-dynamic-list 與 x-ms-dynamic-values。 指向屬性的參數參考必須表示為路徑字串。

   • parameters — 此屬性是一個物件，其中所呼叫動態作業的每個輸入屬性，皆使用靜態值欄位或來源作業屬性的動態參考進行定義。 這兩個選項均定義如下。

   • value — 這是輸入參數要使用的常值。 在下列範例中，GetDynamicList 作業名為 version 的輸入參數會以靜態值 2.0 定義。

     {
         "operationId": "GetDynamicList",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference — 這是完整的參數參考路徑，開頭是參數名稱，其後是要參考的屬性路徑字串。 例如，名為 property1 的 GetDynamicList 作業輸入屬性 (位於參數 destinationInputParam1 下方) 定義為動態參考來源作業之參數 sourceInputParam1 下名為 property1 的屬性。

     {
         "operationId": "GetDynamicList",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     注意

     如果您想要參考標示為內部的任何屬性 (使用預設值)，您在此處必須使用預設值作為定義中的靜態值，而不是 parameterReference。 如果是使用 parameterReference 定義，則不會使用清單中的預設值。

     名稱	必要	描述
     operationId	是	傳回清單的作業。
     參數	是	提供叫用動態清單作業所需輸入參數的物件。
     itemsPath	否	在回應承載中評估為物件陣列的路徑字串。 如果沒有提供 itemsPath ，就會將回應評估為陣列。
     itemTitlePath	否	itemsPath 內部參考值描述之物件中的路徑字串。
     itemValuePath	否	itemsPath  內部物件中參考項目值的路徑字串。

     透過 x-ms-dynamic-list，將參數參考與您所參考屬性的路徑字串搭配使用。 將這些參數參考同時用於動態作業參數參考的鍵和值。

     {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicListWithAmbiguousReferences",
       "parameters": [
         {
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
         },
         {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
             "description": "Input body to execute the request",
             "type": "object",
             "properties": {
               "id": {
                 "description": "The request id",
                 "type": "string"
               },
               "model": {
                 "description": "The model",
                 "type": "string",
                 "x-ms-dynamic-values": {
                   "operationId": "GetSupportedModels",
                   "value-path": "name",
                   "value-title": "properties/displayName",
                   "value-collection": "cardTypes",
                   "parameters": {
                     "requestId": {
                       "parameter": "id"
                     }
                   }
                 },
                 "x-ms-dynamic-list": {
                   "operationId": "GetSupportedModels",
                   "itemsPath": "cardTypes",
                   "itemValuePath": "name",
                   "itemTitlePath": "properties/displayName",
                   "parameters": {
                     "requestId": {
                       "parameterReference": "requestBody/id"
                     }
                   }
                 }
               }
             }
           }
         }
       ],
       "responses": {
         "200": {
           "description": "OK",
           "schema": {
             "type": "object"
           }
         },
         "default": {
           "description": "Operation Failed."
         }
       }
     } 
     

使用動態結構描述

動態結構描述指出目前參數或回應的結構描述是動態的。 此物件可以叫用此欄位值所定義的作業、動態探索結構描述，以及顯示適當的使用者介面，來收集使用者輸入或顯示可用的欄位。

適用於：參數、回應

此影像顯示輸入表單如何根據使用者從清單中選取的項目而變更：

此影像顯示輸出如何根據使用者從下拉式清單中選取的項目而變更。 在此版本中，使用者選取汽車：

在此版本中，使用者選取食物：

如何使用動態結構描述

注意

路徑字串是不包含前置正斜線的 JSON 指標。 因此，這是 JSON 指標： /property/childProperty，這是路徑字串：property/childProperty。

定義動態結構描述有兩種方法：

1. x-ms-dynamic-schema：

   姓名	出席者	描述
   operationId	是	傳回結構描述的作業。
   參數	是	提供叫用 dynamic-schema 作業所需輸入參數的物件。
   value-path	否	參考具有結構描述之屬性的路徑字串。如果未指定，會假設回應包含根物件屬性中的結構描述。 如果已指定，則成功的回復必須包含此屬性。 如果是空白或未定義的結構描述，其值應為 null。

     {
     "name": "dynamicListSchema",
     "in": "body",
     "description": "Dynamic schema for items in the selected list",
     "schema": {
         "type": "object",
         "x-ms-dynamic-schema": {
             "operationId": "GetListSchema",
             "parameters": {
                 "listID": {
                     "parameter": "listID-dynamic"
                 }
             },
             "value-path": "items"
         }
       }
     }
   

   注意

   參數中可能會有不明確的參考。 例如，在下列作業定義中，動態結構描述會參考名為查詢的欄位，但我們無法從定義中確知此欄位 — 不確定它參考的是查詢參數物件還是查詢/查詢字串屬性。

   {
   
       "summary": "Tests dynamic schema with ambiguous references",
       "description": "Tests dynamic schema with ambiguous references.",
       "operationId": "TestDynamicSchemaWithAmbiguousReferences",
       "parameters": [{
           "name": "query",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "query": {
                       "description": "Query Text",
                       "type": "string"
                   }
               }
           },
           "x-ms-summary": "query text"
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "x-ms-dynamic-schema": {
                       "operationId": "GetDynamicSchema",
                       "parameters": {
                           "query": {
                               "parameter": "query"
                           }
                       },
                       "value-path": "schema/valuePath"
                   }
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

   開放原始碼連接器範例

   連接器	案例	連結
   票證	取得所選事件詳細資料的結構描述	票證

2. x-ms-dynamic-properties：

   目前沒辦法明確地參考參數。 此功能可能會在未來提供。 如果您想要讓作業使用任何新的更新，請新增擴充功能 x-ms-dynamic-properties 與 x-ms-dynamic-schema。 此外，如果您的動態擴充功能參考參數中的屬性，則必須新增擴充功能 x-ms-dynamic-properties 與 x-ms-dynamic-schema。 指向屬性的參數參考必須表示為路徑字串。

   • parameters — 此屬性是一個物件，其中所呼叫動態作業的每個輸入屬性，皆使用靜態值欄位或來源作業屬性的動態參考進行定義。 這兩個選項均定義如下。

   • value — 這是輸入參數要使用的常值。 在下列範例中，GetDynamicSchema 作業的輸入參數 (名為版本) 會以靜態值 2.0 定義。

     {
         "operationId": "GetDynamicSchema",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference — 這是完整的參數參考路徑，開頭是參數名稱，其後是要參考的屬性路徑字串。 例如，名為 property1 的 GetDynamicSchema 作業輸入屬性 (位於參數 destinationInputParam1 下方) 定義為動態參考來源作業之參數 sourceInputParam1 下名為 property1 的屬性。

     {
         "operationId": "GetDynamicSchema",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     注意

     如果您想要參考標示為內部的任何屬性 (使用預設值)，您在此處必須使用預設值作為定義中的靜態值，而不是 parameterReference。 如果是使用 parameterReference 定義，則不會使用結構描述中的預設值。

     名稱	必要	描述
     operationId	是	傳回結構描述的作業。
     參數	是	提供叫用 dynamic-schema 作業所需輸入參數的物件。
     itemValuePath	否	參考具有結構描述之屬性的路徑字串。如果未指定，會假設回應包含根物件中的結構描述。 如果已指定，則成功的回復必須包含此屬性。 如果是空白或未定義的結構描述，其值應為 null。

     透過 x-ms-dynamic-properties，對於動態作業參數參考的索引鍵和值，都可搭配使用參數參考與要參考的屬性路徑字串。

         {
         "summary": "Tests dynamic schema with ambiguous references",
         "description": "Tests dynamic schema with ambiguous references.",
         "operationId": "TestDynamicSchemaWithAmbiguousReferences",
         "parameters": [{
             "name": "query",
             "in": "body",
             "description": "query text.",
             "required": true,
             "schema": {
                 "description": "Input body to execute the request",
                 "type": "object",
                 "properties": {
                     "query": {
                         "description": "Query Text",
                         "type": "string"
                     }
                 }
             },
             "x-ms-summary": "query text"
         }],
         "responses": {
             "200": {
                 "description": "OK",
                 "schema": {
                     "x-ms-dynamic-schema": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": "2.0",
                             "query": {
                                 "parameter": "query"
                             }
                         },
                         "value-path": "schema/valuePath"
                     },
                     "x-ms-dynamic-properties": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": {
                                 "value": "2.0"
                             },
                             "query/query": {
                                 "parameterReference": "query/query"
                             }
                         },
                         "itemValuePath": "schema/valuePath"
                     }
                 }
             },
             "default": {
                 "description": "Operation Failed."
             }
           }
         }
     

下一個步驟

從 OpenAPI 定義建立自訂連接器

相關資訊

自訂連接器概觀

提供意見反應

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