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

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

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

摘要

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

適用於:作業
建議:對 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」

每個實體的「x-ms-summary」。

"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

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

可能值:importantadvancedinternal
適用於:作業、參數、結構描述

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

注意

參數若是 internalrequired,您必須提供預設值。

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

"x-ms-visibility",用於顯示或隱藏作業和參數。

"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-listx-ms-dynamic-values。 此外,如果您的動態擴充功能參考參數中的屬性,則必須新增擴充功能 x-ms-dynamic-listx-ms-dynamic-values。 指向屬性的參數參考必須表示為路徑字串。

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

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

      {
          "operationId": "GetDynamicList",
          "parameters": {
            "version": {
              "value": "2.0"
            }
          }
      }
      
    • parameterReference — 這是完整的參數參考路徑,開頭是參數名稱,其後是要參考的屬性路徑字串。 例如,名為 property1GetDynamicList 作業輸入屬性 (位於參數 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-propertiesx-ms-dynamic-schema。 此外,如果您的動態擴充功能參考參數中的屬性,則必須新增擴充功能 x-ms-dynamic-propertiesx-ms-dynamic-schema。 指向屬性的參數參考必須表示為路徑字串。

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

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

      {
          "operationId": "GetDynamicSchema",
          "parameters": {
            "version": {
              "value": "2.0"
            }
          }
      }
      
    • parameterReference — 這是完整的參數參考路徑,開頭是參數名稱,其後是要參考的屬性路徑字串。 例如,名為 property1GetDynamicSchema 作業輸入屬性 (位於參數 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 定義建立自訂連接器

自訂連接器概觀

提供意見反應

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