사용자 지정 커넥터에 대한 OpenAPI 정의 확장

아티클
06/23/2023

Azure Logic Apps, Microsoft Power Automate 또는 Microsoft Power Apps에 대한 사용자 지정 커넥터를 만드는 한 가지 방법은 API의 작업 및 매개 변수를 설명하는 언어에 구애받지 않고 컴퓨터에서 읽을 수 있는 문서인 OpenAPI 정의 파일을 제공하는 것입니다. 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에 대소문자를 사용합니다.
예시: "달력에 새 이벤트를 추가하면" 또는 "이메일 보내기"

각 작업에 대한 "요약".

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

x-ms-summary

엔터티에 대한 제목을 지정합니다.

적용 대상: 매개 변수, 응답 스키마
권장: x-ms-summary의 경우 제목을 사용합니다.
예시: "달력 ID", "제목", "이벤트 설명"

각 엔터티의 "x-ms-summary".

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

설명

작업의 기능 또는 엔터티의 형식 및 기능에 대한 자세한 설명을 지정합니다.

적용 대상: 작업, 매개 변수, 응답 스키마
권장: description에 대소문자를 사용합니다.
예시: "달력에 새 이벤트를 추가하면 이 작업을 트리거합니다", "메일의 제목을 지정합니다"

각 작업 또는 엔터티의 "설명".

"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

웹후크 알림 요청에 대한 스키마 정의를 포함합니다. 이는 외부 서비스에서 알림 URL에 게시한 웹후크 페이로드에 대한 스키마입니다.

적용 대상: 리소스

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

x-ms-notification-url

웹후크 등록 작업을 위해 웹후크 알림 URL을 이 매개 변수/필드에 배치해야 하는지 여부를 부울 값으로 식별합니다.

적용 대상: 매개 변수/입력 필드

"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-title	아니요	값의 설명을 의미하는 "값-컬렉션" 내의 개체에 있는 경로 문자열입니다.
value-path	아니요	매개 변수 값을 의미하는 "값-컬렉션" 내의 개체에 있는 경로 문자열입니다.

"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를 참조합니다. 이는 매개변수 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-values와 함께 새 x-ms-dynamic-list 확장을 추가합니다. 또한 동적 확장이 매개 변수 내의 속성을 참조하는 경우 x-ms-dynamic-values와 함께 새 x-ms-dynamic-list 확장을 추가해야 합니다. 속성을 가리키는 매개 변수 참조는 경로 문자열로 표현되어야 합니다.

parameters — 이 속성은 호출되는 동적 작업의 각 입력 속성이 정적 값 필드 또는 원본 작업의 속성에 대한 동적 참조를 사용하여 정의되는 개체입니다. 이 두 옵션은 모두 다음에서 정의됩니다.
value — 입력 매개 변수에 사용할 리터럴 값입니다. 다음 예시에서 GetDynamicList 작업의 version이라는 입력 매개 변수는 다음 예제에서 2.0 정적 값을 사용하여 정의됩니다.
```
{
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference — 매개 변수 이름으로 시작하여 참조할 속성의 경로 문자열이 뒤따르는 전체 매개변수 참조 경로입니다. 예를 들어, destinationInputParam1 매개 변수 아래에 있는 property1이라는 GetDynamicList 작업의 입력 특성은 소스 작업의 sourceInputParam1 매개 변수 아래에 property1이라는 특성에 대한 동적 참조로 정의됩니다.

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

참고

기본값을 사용하는 internal로 표시된 속성을 참조하려면 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."
    }
  }
}

동적 스키마 사용

동적 스키마는 현재 매개 변수 또는 응답에 대한 스키마가 동적임을 나타냅니다. 이 개체는 이 필드의 값으로 정의된 작업을 호출하고 스키마를 동적으로 검색하며 사용자 입력을 수집하기 위한 적절한 사용자 인터페이스를 표시하거나 사용 가능한 필드를 표시합니다.

적용 대상: 매개 변수, 응답

이 이미지는 사용자가 목록에서 선택한 항목에 따라 입력 양식을 변경하는 방법을 보여줍니다.

사용자가 선택한 내용에 따라 양식이 변경됩니다.

또한 이 이미지는 사용자가 드롭다운 목록에서 선택한 항목에 따라 출력을 변경하는 방법을 보여줍니다. 이 버전에서 사용자는 자동차를 선택합니다.

사용자는 자동차를 선택합니다

이 버전에서 사용자는 음식을 선택합니다.

사용자는 음식을 선택합니다

동적 스키마를 사용하는 방법

참고

동적 스키마를 정의하는 방법은 두 가지가 있습니다.

x-ms-dynamic-schema:

이름	필수 참석자	설명
operationId	예	스키마를 반환하는 작업입니다.
매개 변수	예	동적-스키마 작업을 호출하는 데 필요한 입력 매개 변수를 제공하는 개체입니다.
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-schema와 함께 새 x-ms-dynamic-properties 확장을 추가합니다. 또한 동적 확장이 매개 변수 내의 속성을 참조하는 경우 x-ms-dynamic-schema와 함께 새 x-ms-dynamic-properties 확장을 추가해야 합니다. 속성을 가리키는 매개 변수 참조는 경로 문자열로 표현되어야 합니다.

parameters — 이 속성은 호출되는 동적 작업의 각 입력 속성이 정적 값 필드 또는 원본 작업의 속성에 대한 동적 참조를 사용하여 정의되는 개체입니다. 이 두 옵션은 모두 다음에서 정의됩니다.
value — 입력 매개 변수에 사용할 리터럴 값입니다. 다음 예시에서 GetDynamicSchema 작업의 version이라는 입력 매개 변수는 2.0 정적 값으로 정의됩니다.
```
{
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference — 매개 변수 이름으로 시작하여 참조할 속성의 경로 문자열이 뒤따르는 전체 매개변수 참조 경로입니다. 예를 들어, destinationInputParam1 매개 변수 아래에 있는 property1이라는 GetDynamicSchema 작업의 입력 특성은 소스 작업의 sourceInputParam1 매개 변수 아래에 property1이라는 특성에 대한 동적 참조로 정의됩니다.

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

참고

기본값을 사용하는 internal로 표시된 속성을 참조하려면 parameterReference 대신 여기의 정의에서 기본값을 정적 값으로 사용해야 합니다. parameterReference를 사용하여 정의된 경우 스키마의 기본값이 사용되지 않습니다.

이름	필수	설명
operationId	네	스키마를 반환하는 작업입니다.
매개 변수	예	동적-스키마 작업을 호출하는 데 필요한 입력 매개 변수를 제공하는 개체입니다.
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

동적 값 사용

동적 값을 사용하는 방법

동적 스키마 사용

동적 스키마를 사용하는 방법

오픈 소스 커넥터의 예시

다음 단계

참조 항목

피드백 제공

추가 리소스