Rozszerzenie definicji OpenAPI dla niestandardowego łącznika

Jednym ze sposobów tworzenia łączników niestandardowych dla usług Azure Logic Apps, Microsoft Power Automate lub Microsoft Power Apps jest podanie pliku definicji interfejsu OpenAPI, który jest niezależnym od języka i czytelnym dla maszyn dokumentem opisującym parametry i operacje interfejsu API. Oprócz standardowej funkcjonalności OpenAPI, możesz także włączyć te rozszerzenia OpenAPI podczas tworzenia własnych łączników dla Logic Apps i Power Automate:

• 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

Poniższe sekcje opisują te rozszerzenia.

Podsumowanie

Określa tytuł dla akcji (operacji).

Dotyczy: operacji
Zalecane: użyj wielkości liter jak w zdaniu dla summary.
Przykład: „Po dodaniu zdarzenia do kalendarza” lub „Wyślij wiadomość e-mail”

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

x-ms-summary

Określa tytuł dla encji.

Dotyczy: Parametry, schemat odpowiedzi
Zalecane: użyj wielkości liter jak w tytułach dla x-ms-summary.
Przykład: „Identyfikator kalendarza”, „Temat”, „Opis zdarzenia”

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

opis

Określa pełne wyjaśnienie funkcjonalności operacji lub formatu i funkcji encji.

Dotyczy: operacji, parametrów, schematu odpowiedzi
Zalecane: użyj wielkości liter jak w zdaniu dla description.
Przykład: „Ta operacja jest wywoływana po dodaniu nowego zdarzenia do kalendarza”, „Podaj temat wiadomości e-mail"

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

x-ms-visibility

Określa widoczność względem użytkownika dla encji.

Możliwe wartości: important, advanced i internal
Dotyczy: operacji, parametrów, schematów

• Operacje i parametry important są zawsze pokazywane użytkownikowi jako pierwsze.
• Operacje i parametry advanced są ukryte w dodatkowym menu.
• Operacje i parametry internal są ukryte przed użytkownikiem.

Uwaga

W przypadku parametrów, które są internal i required, musisz podać domyślne wartości.

Przykład: menu Zobacz więcej i menu Pokaż opcje zaawansowane ukrywają operacje i parametry 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

Służy do zarządzania obsługą wersji i cyklem życia operacji.

Dotyczy: operacji

• family—Ciąg określający folder rodziny operacji.
• revision—Liczba całkowita oznaczająca numer poprawki.
• replacement—Obiekt zawierający informacje o zastępczym interfejsie API i jego operacje.

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

x-ms-operation-context

Służy do symulowania uruchamiania wyzwalacza, aby umożliwić testowanie przepływu zależnego od wyzwalacza.

Dotyczy: operacji

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

x-ms-capabilities

Na poziomie łącznika jest to przegląd możliwości oferowanych przez łącznik, w tym konkretnych operacji.

Dotyczy: Łączniki

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

Na poziomie operacji służy do wskazywania, że operacja obsługuje dzielenie podczas przekazywania i/lub statyczny rozmiar fragmentu i może zostać podana przez użytkownika.

Dotyczy: operacji

• chunkTransfer—Wartość logiczna określająca, czy jest obsługiwany transfer fragmentów.

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

x-ms-trigger

Określa, czy bieżąca operacja jest wyzwalaczem, który tworzy pojedyncze zdarzenie. Brak tego pola oznacza, że jest to operacja action.

Dotyczy: operacji

• single—Odpowiedź obiektu
• batch—Odpowiedź tablicy

"x-ms-trigger": "batch"

x-ms-trigger-hint

Opis sposobu uruchamiania zdarzenia dla operacji wyzwalacza.

Dotyczy: operacji

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

x-ms-notification-content

Zawiera definicję schematu żądania powiadomienia elementu webhook. Jest to schemat ładunku elementu webhook opublikowany przez usługi zewnętrzne przy użyciu adresu URL powiadomienia.

Ma zastosowanie do: zasoby

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

x-ms-notification-url

Wskazuje w wartości logicznej, czy adres URL powiadomienia elementu webhook powinien być umieszczony w tym parametrze/polu dla operacji rejestracji elementu webhook.

Dotyczy: pola parametr/dane wejściowe

"x-ms-notification-url": true

x-ms-url-encoding

Wskazuje, czy bieżący parametr ścieżki ma być kodowany jako adres URL w sposób podwójny (double), czy pojedynczy (single). Brak tego pola oznacza kodowanie typu single.

Dotyczy: parametrów ścieżki

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

Używanie wartości dynamicznych

Wartości dynamiczne są listą opcji dla użytkownika służących do wybierania parametrów wejściowych dla operacji. 

Dotyczy: parametrów 

Jak uzywać wartości dynamicznych

Uwaga

Ciąg ścieżki jest wskaźnikiem JSON, który nie zawiera wiodących kresek na następny ukośnik. Oznacza to, że jest to wskaźnik JSON: /property/childProperty, który jest łańcuchem ścieżki: property/childProperty.

Istnieją dwa sposoby definiowania wartości dynamicznych:

1. Używanie aplikacji x-ms-dynamic-values

   Nazwisko	Wymagani	Opis
   operationId	Tak	Operacja, która zwraca wartości.
   parametry	Tak	Obiekt, który dostarcza parametry wejściowe wymagane do wywołania operacji rozszerzenia dynamic-values.
   value-collection	Nie	Ciąg ścieżki, który oblicza tablicę obiektów w ładunku odpowiedzi. Jeśli element value-collection nie jest określony, odpowiedź jest obliczana jako tablica.
   value-title	Nie	Ciąg ścieżki w obiekcie wewnątrz właściwości value-collection odwołujący się do opisu wartości.
   value-path	Nie	Ciąg ścieżki w obiekcie wewnątrz właściwości value-collection odwołujący się do parametru wartości.

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

   Uwaga

   W przypadku korzystania z wartości dynamicznych możliwe jest użycie niejednoznacznych odwołań do parametrów. Na przykład w ramach poniższego definiowania operacji wartości dynamiczne odwołują się do identyfikatora pola, który jest niejednoznaczny w definicji, ponieważ nie jest klarowny, jeśli odwołuje się do parametru identyfikatora, lub właściwość 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

   Nie ma sposobu, aby jednoznacznie odwołać się do parametrów. Ta funkcja może być oferowana w przyszłości. Jeśli chcesz, aby operacja korzystała z dowolnych nowych aktualizacji, dodaj nowe rozszerzenie x-ms-dynamic-list wraz z rozszerzeniem x-ms-dynamic-values. Ponadto jeśli rozszerzenie dynamiczne odwołuje się do właściwości w ramach parametrów, należy dodać nowe rozszerzenie x-ms-dynamic-list wraz z rozszerzeniem x-ms-dynamic-values. Odwołania do parametrów wskazujące właściwości muszą być wyrażone jako ciągi ścieżek.

   • parameters — ta właściwość jest obiektem, w którym każda właściwość wejściowa wywołanej operacji dynamicznej jest zdefiniowana z polem wartości statycznej lub dynamicznym odwołaniem do właściwości operacji źródłowej. Obie te opcje zdefiniowano poniżej.

   • value — wartość literału, która ma zostać użyta dla parametru wejściowego. Na przykład parametr wejściowy operacji GetDynamicList o nazwie version jest zdefiniowany przy użyciu wartości statycznej 2.0.

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

   • parameterReference—Jest to pełna ścieżka odwołania do parametru rozpoczynająca się od nazwy parametru; po niej następuje ciąg ścieżki właściwości, do której ma zostać utworzone odwołanie. Na przykład właściwość wejściowa operacji GetDynamicList o nazwie property1, która znajduje się w parametrze destinationInputParam1, jest definiowana jako odwołanie dynamiczne do właściwości o nazwie property1 pod parametrem sourceInputParam1 operacji źródłowej.

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

     Uwaga

     Aby odwołać się do dowolnej właściwości, która jest oznaczona jako wewnętrzna z wartością domyślną, należy w tym miejscu użyć wartości domyślnej jako wartości statycznej w definicji tutaj zamiast we właściwości parameterReference. Wartość domyślna z listy nie jest używana, jeśli jest zdefiniowana za pomocą właściwości parameterReference.

     Imię i nazwisko/nazwa	Wymagania	Opis
     operationId	Tak	Operacja, która zwraca listę.
     parametry	Tak	Obiekt, który dostarcza parametry wejściowe wymagane do wywołania operacji dynamicznej listy.
     itemsPath	Nie	Ciąg ścieżki, który oblicza tablicę obiektów w ładunku odpowiedzi. Jeśli właściwość  itemsPath  nie zostanie podana, odpowiedź będzie obliczana jako tablica.
     itemTitlePath	Nie	Ciąg ścieżki w obiekcie wewnątrz elementu  itemsPath  odwołujący się do opisu parametru.
     itemValuePath	Nie	Ciąg ścieżki w obiekcie wewnątrz właściwości  itemsPath  odwołujący się do wartości elementu.

     Wraz z rozszerzeniem x-ms-dynamic-list użyj odwołań do parametrów z ciągiem ścieżki właściwości, do której się odwołujesz. Te parametry służą zarówno do korzystania z parametru, jak i wartości parametru dotyczącego parametrów operacji dynamicznej.

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

Użyj schematu dynamicznego

Schemat dynamiczny wskazuje, że schemat dla bieżącego parametru lub odpowiedzi jest dynamiczny. Ten obiekt wywołuje operację zdefiniowaną przez wartość tego pola, dynamicznie odnaleźć schemat i wyświetlić odpowiedni interfejs użytkownika, aby pobrać dane wejściowe od użytkownika lub wyświetlić dostępne pola.

Dotyczy: parametrów, odpowiedzi

Ten obraz pokazuje, jak zmienia się formularz wejściowy w zależności od elementu wybieranego przez użytkownika z listy:

Zaś ten obraz pokazuje, jak zmieniają się dane wyjściowe w zależności od wybieranego przez użytkownika elementu z listy rozwijanej. W tej wersji użytkownik wybiera element Samochody:

W tej wersji użytkownik wybiera element Jedzenie:

Jak uzywać schematów dynamicznych

Uwaga

Ciąg ścieżki jest wskaźnikiem JSON, który nie zawiera wiodących kresek na następny ukośnik. Oznacza to, że jest to wskaźnik JSON: /property/childProperty, który jest łańcuchem ścieżki: property/childProperty.

Istnieją dwa sposoby definiowania schematów dynamicznych:

1. x-ms-dynamic-schema:

   Nazwisko	Wymagani	Opis
   operationId	Tak	Operacja, która zwraca schemat.
   parametry	Tak	Obiekt, który dostarcza parametry wejściowe wymagane do wywołania operacji rozszerzenia dynamic-schema.
   value-path	Nie	Ciąg ścieżki odwołujący się do właściwości, w której jest przechowywany schemat. Jeśli nie jest określony, przyjmuje się, że odpowiedź zawiera schemat we właściwościach obiektu głównego. Jeśli ta wartość jest określona, udany element odpowiedzi musi zawierać właściwość. W przypadku pustego lub niezdefiniowanego schematu jego wartość powinna być zerowa.

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

   Uwaga

   Parametr może zawierać niejednoznaczne odwołania. Na przykład w poniższej definicji operacji schemat dynamiczny odwołuje się do pola o nazwie zapytanie, które nie może zostać jednoznacznie zrozumiane na podstawie definicji —bez względu na to, czy odwołuje się do obiektu parametru zapytanie, czy właściwości ciągu zapytanie/zapytanie.

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

   Przykłady z łączników typu open source

   Łącznik	Scenariusz	Łącze
   Obsługa biletów	Pobierz schemat, aby uzyskać szczegółowe informacje o wybranym zdarzeniu	Obsługa biletów

2. x-ms-dynamic-properties:

   Nie ma sposobu, aby jednoznacznie odwołać się do parametrów. Ta funkcja może być oferowana w przyszłości. Jeśli chcesz, aby operacja korzystała z dowolnych nowych aktualizacji, dodaj nowe rozszerzenie x-ms-dynamic-properties wraz z rozszerzeniem x-ms-dynamic-schema. Ponadto jeśli rozszerzenie dynamiczne odwołuje się do właściwości w ramach parametrów, należy dodać nowe rozszerzenie x-ms-dynamic-properties wraz z rozszerzeniem x-ms-dynamic-schema. Odwołania do parametrów wskazujące właściwości muszą być wyrażone jako ciągi ścieżek.

   • parameters — ta właściwość jest obiektem, w którym każda właściwość wejściowa wywołanej operacji dynamicznej jest zdefiniowana z polem wartości statycznej lub dynamicznym odwołaniem do właściwości operacji źródłowej. Obie te opcje zdefiniowano poniżej.

   • value — wartość literału, która ma zostać użyta dla parametru wejściowego. Na przykład parametr wejściowy operacji GetDynamicSchema o nazwie wersja jest zdefiniowany przy użyciu wartości statycznej 2.0 w poniższym przykładzie.

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

   • parameterReference—Jest to pełna ścieżka odwołania do parametru rozpoczynająca się od nazwy parametru; po niej następuje ciąg ścieżki właściwości, do której ma zostać utworzone odwołanie. Na przykład właściwość wejściowa operacji GetDynamicSchema o nazwie Property1, która znajduje się w parametrze destinationInputParam1, jest definiowana jako odwołanie dynamiczne do właściwości o nazwie Property1 pod parametrem sourceInputParam1 operacji źródłowej.

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

     Uwaga

     Aby odwołać się do dowolnej właściwości, która jest oznaczona jako wewnętrzna z wartością domyślną, należy w tym miejscu użyć wartości domyślnej jako wartości statycznej w definicji tutaj zamiast we właściwości parameterReference. Wartość domyślna ze schematu nie jest używana, jeśli jest zdefiniowana za pomocą właściwości parameterReference.

     Imię i nazwisko/nazwa	Wymagania	Opis
     operationId	Tak	Operacja, która zwraca schemat.
     parametry	Tak	Obiekt, który dostarcza parametry wejściowe wymagane do wywołania operacji rozszerzenia dynamic-schema.
     itemValuePath	Nie	Ciąg ścieżki odwołujący się do właściwości, w której jest przechowywany schemat. Jeśli nie jest określony, przyjmuje się, że odpowiedź zawiera schemat w obiekcie głównym. Jeśli ta wartość jest określona, udany element odpowiedzi musi zawierać właściwość. W przypadku pustego lub niezdefiniowanego schematu jego wartość powinna być zerowa.

     Za pomocą właściwości x-ms-dynamic-properties odwołania do parametrów mogą być używane wraz z ciągiem ścieżki właściwości, do której ma zostać utworzone odwołanie, zarówno dla klucza, jak i wartości odwołania do parametru operacji dynamicznej.

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

Następny krok

Tworzenie łącznika niestandardowego na podstawie definicji interfejsu OpenAPI

Zobacz też

Omówienie łączników niestandardowych

Przekazywanie opinii

Jesteśmy wdzięczni za opinie na temat problemów z platformą łączników oraz pomysły na nowe funkcje. Aby przekazać opinię, przejdź na stronę Przesyłanie problemów lub uzyskiwanie pomocy dotyczącej łączników i wybierz typ opinii.