Tworzenie łącznika niestandardowego na podstawie rozszerzenia interfejsu OpenAPI

Artykuł
04/24/2024

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”

„summary” dla każdej operacji.

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

„x-ms-summary” dla każdej encji.

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

dla rozszerzenia „opis” każdej operacji lub encji.

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

Rozszerzenie „x-ms-visibility” do pokazywania lub ukrywania operacji i parametrów.

"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 

Dynamic-values do pokazywania list.

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:

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

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:

Formularz zmieni się w zależności od wyboru dokonanego przez użytkownika.

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:

Użytkownik wybiera samochody.

W tej wersji użytkownik wybiera element Jedzenie:

Użytkownik wybiera jedzenie.

Jak uzywać schematów dynamicznych

Uwaga

Istnieją dwa sposoby definiowania schematów dynamicznych:

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

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

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.

Udostępnij za pośrednictwem

Tworzenie łącznika niestandardowego na podstawie rozszerzenia interfejsu OpenAPI

Podsumowanie

x-ms-summary

opis

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

Używanie wartości dynamicznych

Jak uzywać wartości dynamicznych

Użyj schematu dynamicznego

Jak uzywać schematów dynamicznych

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

Następny krok

Przekazywanie opinii

Dodatkowe zasoby

Udostępnij za pośrednictwem

Tworzenie łącznika niestandardowego na podstawie rozszerzenia interfejsu OpenAPI

Podsumowanie

x-ms-summary

opis

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

Używanie wartości dynamicznych

Jak uzywać wartości dynamicznych

Użyj schematu dynamicznego

Jak uzywać schematów dynamicznych

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

Następny krok

Informacje pokrewne

Przekazywanie opinii

Dodatkowe zasoby