Vytvořte vlastní konektor s rozšířením OpenAPI

Článek
04/24/2024

Jedním ze způsobů, jak vytvořit vlastní konektory pro Azure Logic Apps, Microsoft Power Automate nebo Microsoft Power Apps, je zadat soubor definice OpenAPI, což je jazykově nezávislý a strojově čitelný dokument popisující operace a parametry vašeho rozhraní API. Kromě předem připravených funkcí rozhraní OpenAPI můžete při vytváření vlastních konektorů pro Logic Apps a Power Automate zahrnout také následující rozšíření 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

Tato rozšíření jsou popsána v následujících částech.

Souhrn

Určuje název akce (operace).

Platí pro: operace
Doporučení: Pro summary použijte velké písmeno na začátku věty.
Příklad: „Po přidání události do kalendáře“ nebo „Poslat e-mail“

Objekt „summary“ pro každou operaci.

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

x-ms-summary

Určuje název entity.

Platí pro: parametry, schéma odpovědi
Doporučení: Pro x-ms-summary použijte velké písmeno na začátku názvu.
Příklad: „ID kalendáře“, „Předmět“, „Popis události“

Objekt „x-ms-summary“ pro každou entitu.

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

Popis

Určuje podrobné vysvětlení fungování operace nebo formátu a funkce entity.

Platí pro: operace, parametry, schéma odpovědi
Doporučení: Pro description použijte velké písmeno na začátku věty.
Příklad: „Tato operace se spustí po přidání nové události do kalendáře“, „Zadejte předmět e-mailu“

Objekt „Popis“ pro každou operaci nebo entitu.

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

x-ms-visibility

Určuje viditelnost entity pro uživatele.

Možné hodnoty: important, advanced a internal
Platí pro: operace, parametry, schémata

Operace a parametry important se uživateli vždy zobrazují jako první.
Operace a parametry advanced jsou skryté pod nabídkou Další.
Operace a parametry internal jsou uživateli skryté.

Poznámka

U parametrů, které mají vlastnosti internal a required, musíte zadat jejich výchozí hodnoty.

Příklad: Nabídka Zobrazit více a nabídka Zobrazit pokročilé možnosti mají skryté operace a parametry advanced.

Objekt „x-ms-visibility“ zobrazí nebo skryje operace a parametry.

"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

Používá se pro správu verzí a životního cyklu operace.

Platí pro: operace

family— řetězec popisující složku řady operací.
revision — Celé číslo udávající číslo revize.
replacement — objekt obsahující operace a informace náhradního rozhraní API.

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

x-ms-operation-context

Slouží k simulaci aktivace triggeru a umožňuje testování toku závislého na tomto triggeru.

Platí pro: operace

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

x-ms-capabilities

Při použití na úrovni konektoru jde o přehled možností, které tento konektor nabízí, včetně konkrétních operací.

Vztahuje se na: konektory

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

Při použití na úrovni operace se používá k určení, že operace podporuje blokové načítání nebo statickou velikost bloku a dá se zadat uživatelsky.

Platí pro: operace

chunkTransfer—Logická hodnota udávající, jestli se podporuje přenos bloků.

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

x-ms-trigger

Určuje, jestli aktuální operace je trigger, jehož výsledkem je jedna událost. Absence tohoto pole znamená, že jde o operaci action.

Platí pro: operace

single—odezva v podobě objektu
batch—odezva v podobě pole

"x-ms-trigger": "batch"

x-ms-trigger-hint

Popis, jak aktivovat událost pro operaci triggeru

Platí pro: operace

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

x-ms-notification-content

Obsahuje definici schématu pro žádost o oznámení webhooku. Jde o schéma pro datovou část webhooku zveřejněné externími službami pro adresu URL oznámení.

Platí pro: Zdroje

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

x-ms-notification-url

Pomocí logické hodnoty určuje, jestli se adresa URL oznámení webhooku má umístit do tohoto parametru/pole pro operaci registrace webhooku.

Platí pro: Parametr/vstupní pole

"x-ms-notification-url": true

x-ms-url-encoding

Určuje, jestli aktuální parametr cesty používá dvojité kódování pro adresu URL (double) nebo jednoduché kódování (single). Absence tohoto pole znamená kódování single.

Platí pro: parametry Cesta

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

Použití dynamických hodnot

Dynamické hodnoty jsou seznamem možností pro výběr vstupních parametrů pro operaci. 

Platí pro: parametry 

Dynamic-values pro zobrazení seznamů.

Použití dynamických hodnot

Poznámka

Řetězec cesty je ukazatel JSON, který neobsahuje úvodní lomítko. Toto je ukazatel JSON: /property/childProperty a toto je řetězec cesty: property/childProperty.

Dynamické hodnoty lze definovat dvěma způsoby:

Použití x-ms-dynamic-values

Název	Povinní účastníci	Popis
operationId	Ano	Operace, která vrací hodnoty.
parametry	Ano	Objekt, který poskytuje vstupní parametry potřebné k volání operace dynamic-values.
value-collection	Ne	Řetězec cesty, který se vyhodnocuje do pole objektů v datové části odpovědi. Pokud není hodnota value-collection zadaná, vyhodnotí se odpověď jako pole.
value-title	Ne	Řetězec cesty v objektu uvnitř kolekce hodnot odkazující na popis hodnoty
value-path	Ne	Řetězec cesty v objektu uvnitř kolekce hodnot odkazující na hodnotu parametru.

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

Poznámka

Při použití dynamických hodnot je možné mít nejednoznačné odkazy na parametry. Například v následující definici operace odkazují dynamické hodnoty na pole id, což je z definice nejednoznačné, protože není jasné, zda odkazuje na parametr idnebo vlastnost 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

Neexistuje způsob jednoznačného odkazu na parametry. Tato funkce může být poskytnuta v budoucnosti. Pokud chcete, aby vaše operace využívala výhod nejnovějších aktualizací, pro nové rozšíření přidejte kromě x-ms-dynamic-values také x-ms-dynamic-list. Také pokud vaše dynamické rozšíření odkazuje na vlastnosti uvnitř parametrů, pro nové rozšíření musíte kromě x-ms-dynamic-values přidat také x-ms-dynamic-list. Odkazy na parametry ukazující na vlastnosti musí být vyjádřeny jako řetězce cest.

parameters—Tato vlastnost je objekt, ve kterém je definovaná každá vstupní vlastnost volané dynamické operace, a to buď jako pole statické hodnoty, nebo jako dynamický odkaz na vlastnost zdrojové operace. Obě tyto možnosti jsou definovány níže.
value—Toto je literálová hodnota, která se použije pro vstupní parametr. Například vstupní parametr operace GetDynamicList nazvaný verze je v následujícím příkladu definovaný se statickou hodnotou 2.0.
```
{
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference—Toto je kompletní cesta odkazu na parametr, která začíná názvem parametru, za kterým následuje řetězec cesty pro vlastnost, na kterou se má odkazovat. Vstupní vlastnost operace GetDynamicList nazvaná property1, která je pod parametrem destinationInputParam1, je například definována jako dynamický odkaz na vlastnost nazvanou property1 pod parametrem sourceInputParam1 zdrojové operace.

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

Poznámka

Pokud chcete odkazovat na libovolnou vlastnost, která je označená jako interní s výchozí hodnotou, musíte tady tuto výchozí hodnotu použít jako statickou hodnotu (místo parameterReference). Výchozí hodnota ze seznamu se nepoužije, pokud je definovaná s využitím parameterReference.

Name	Požadováno	Popis
operationId	Ano	Operace, která vrací seznam.
parametry	Ano	Objekt, který poskytuje vstupní parametry potřebné k volání operace dynamického seznamu.
itemsPath	Ne	Řetězec cesty, který se vyhodnocuje do pole objektů v datové části odpovědi. Pokud se `itemsPath` nezadá, odpověď se vyhodnotí jako pole.
itemTitlePath	Ne	Řetězec cesty v objektu uvnitř `itemsPath`, který odkazuje na popis hodnoty.
itemValuePath	Ne	Řetězec cesty v objektu uvnitř `itemsPath` odkazující na hodnotu položky.

U x-ms-dynamic-list použijte odkazy na parametry s řetězcem cesty pro vlastnost, na kterou odkazujete. Tyto odkazy na parametry použijte jak pro klíč, tak pro hodnotu odkazu na dynamické provozní parametry.

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

Použít dynamické schéma

Dynamické schéma určuje, že schéma aktuálního parametru nebo odpovědi je dynamické. Tento objekt volá operaci definovanou hodnotou tohoto pole, dynamicky zjišťuje schéma a zobrazuje příslušné uživatelské rozhraní pro sběr uživatelských vstupů nebo zobrazení dostupných polí.

Platí pro: parametry, odpovědi

Na tomto obrázku vidíte změnu vstupního formuláře na základě položky, kterou uživatel vybere v rozevíracím seznamu:

Formulář se mění na základě výběru uživatele.

Tento obrázek ukazuje, jak se mění výstupy na základě položky, kterou uživatel vybere v rozevíracím seznamu. V této verzi uživatel vybral Auta:

Uživatel vybere auta.

V této verzi uživatel vybral Jídlo:

Uživatel vybere jídlo.

Použití dynamického schématu

Poznámka

Řetězec cesty je ukazatel JSON, který neobsahuje úvodní lomítko. Toto je ukazatel JSON: /property/childProperty a toto je řetězec cesty: property/childProperty.

Dynamické schéma lze definovat dvěma způsoby:

x-ms-dynamic-schema:

Název	Povinní účastníci	Popis
operationId	Ano	Operace, která vrací schéma.
parametry	Ano	Objekt, který poskytuje vstupní parametry potřebné k volání operace dynamic-schema.
value-path	Ne	Řetězec cesty, který odkazuje na vlastnost obsahující schéma. Pokud není zadaný, předpokládá se, že odpověď obsahuje schéma ve vlastnostech kořenového objektu. Pokud je uvedeno, musí úspěšná odpověď obsahovat vlastnost. Pro prázdné nebo nedefinované schéma by měla být jeho hodnota 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"
      }
    }
  }

Poznámka

V parametrech mohou být nejednoznačné odkazy. Například v následující definici operace dynamické schéma odkazuje na pole query, u kterého z definice nejde zjistit—jestli odkazuje na objekt parametru query, nebo na řetězcovou vlastnost query/query.

{

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

Příklady z konektorů Open Source

Konektor	Scénář	Odkaz
Ticketing	Získejte schéma pro podrobnosti o vybrané události	Ticketing

x-ms-dynamic-properties:

Neexistuje způsob jednoznačného odkazu na parametry. Tato funkce může být poskytnuta v budoucnosti. Pokud chcete, aby vaše operace využívala výhod nejnovějších aktualizací, pro nové rozšíření přidejte kromě x-ms-dynamic-schema také x-ms-dynamic-properties. Také pokud vaše dynamické rozšíření odkazuje na vlastnosti uvnitř parametrů, pro nové rozšíření musíte kromě x-ms-dynamic-schema přidat také x-ms-dynamic-properties. Odkazy na parametry ukazující na vlastnosti musí být vyjádřeny jako řetězce cest.

parameters—Tato vlastnost je objekt, ve kterém je definovaná každá vstupní vlastnost volané dynamické operace, a to buď jako pole statické hodnoty, nebo jako dynamický odkaz na vlastnost zdrojové operace. Obě tyto možnosti jsou definovány níže.
value—Toto je literálová hodnota, která se použije pro vstupní parametr. Například vstupní parametr operace GetDynamicSchema nazvaný version je v následujícím příkladu definovaný se statickou hodnotou 2.0.
```
{
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference—Toto je kompletní cesta odkazu na parametr, která začíná názvem parametru, za kterým následuje řetězec cesty pro vlastnost, na kterou se má odkazovat. Vstupní vlastnost operace GetDynamicSchema nazvaná property1, která je pod parametrem destinationInputParam1, je například definována jako dynamický odkaz na vlastnost nazvanou property1 pod parametrem sourceInputParam1 zdrojové operace.

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

Poznámka

Pokud chcete odkazovat na libovolnou vlastnost, která je označená jako interní s výchozí hodnotou, musíte tady tuto výchozí hodnotu použít jako statickou hodnotu (místo parameterReference). Výchozí hodnota ze schématu se nepoužije, pokud je definovaná s využitím parameterReference.

Name	Požadováno	Popis
operationId	Ano	Operace, která vrací schéma.
parametry	Ano	Objekt, který poskytuje vstupní parametry potřebné k volání operace dynamic-schema.
itemValuePath	Ne	Řetězec cesty, který odkazuje na vlastnost obsahující schéma. Pokud není zadaný, předpokládá se, že odpověď obsahuje schéma v kořenovém objektu. Pokud je uvedeno, musí úspěšná odpověď obsahovat vlastnost. Pro prázdné nebo nedefinované schéma by měla být jeho hodnota null.

U x-ms-dynamic-properties se odkazy na parametry dají použít s řetězcem cesty pro vlastnost, na kterou se má odkazovat, a to pro klíč i hodnotu odkazu na parametr dynamické operace.

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

Další krok

Vytvoření vlastního konektoru z definice OpenAPI

Přehled vlastních konektorů

Poskytnutí názorů

Velmi si vážíme vašich názorů na problémy s naší platformou konektorů nebo nových nápadů na funkce. Chcete-li poskytnout zpětnou vazbu, přejděte do části Odeslat problémy nebo získat pomoc s konektory a vyberte typ zpětné vazby.

Sdílet prostřednictvím

Vytvořte vlastní konektor s rozšířením OpenAPI

Souhrn

x-ms-summary

Popis

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

Použití dynamických hodnot

Použití dynamických hodnot

Použít dynamické schéma

Použití dynamického schématu

Příklady z konektorů Open Source

Další krok

Poskytnutí názorů

Další materiály

Sdílet prostřednictvím

Vytvořte vlastní konektor s rozšířením OpenAPI

Souhrn

x-ms-summary

Popis

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

Použití dynamických hodnot

Použití dynamických hodnot

Použít dynamické schéma

Použití dynamického schématu

Příklady z konektorů Open Source

Další krok

Související informace

Poskytnutí názorů

Další materiály