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

文章
04/24/2024

為 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」

每個實體的「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

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

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

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

注意

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

範例：查看更多和顯示進階選項功能表是隱藏的 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。

定義動態值有兩種方法：

使用 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."
        }
    }
}

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。

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

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."
        }
    }
}

開放原始碼連接器範例

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

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 定義建立自訂連接器

自訂連接器概觀

提供意見反應

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

分享方式：

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

摘要

x-ms-summary

描述

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

使用動態值

如何使用動態值

使用動態結構描述

如何使用動態結構描述

開放原始碼連接器範例

下一個步驟

提供意見反應

更多資源

分享方式：

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

摘要

x-ms-summary

描述

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

使用動態值

如何使用動態值

使用動態結構描述

如何使用動態結構描述

開放原始碼連接器範例

下一個步驟

相關資訊

提供意見反應

更多資源