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

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

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

souhrn

Určuje název akce (operace).

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

"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čeno: Použijte velké písmeno na začátku věty pro x-ms-summary.
Příklad: ID kalendáře, předmět, popis události

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

Popis

Poskytuje podrobné vysvětlení funkcí operace nebo formátu a funkce entity.

Platí pro: Operace, parametry, schéma odpovědi
Doporučeno: Použijte velké písmeno na začátku věty pro description.
Příklad: "Tato operace se aktivuje při přidání nové události do kalendáře", "Zadejte předmět e-mailu".

"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

• Uživatel vždy nejprve uvidí important operace a parametry.
• Uživatel vidí operace a parametry advanced jenom v případech, kdy používá další nabídku.
• Uživatel nevidí internal operace a parametry.

Poznámka:

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

Příklad: Nabídka Zobrazit dalšímožnosti a Zobrazit upřesňující možnosti skryjí advanced 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

Slouží ke správě verzí a správy ž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

Pomocí této vlastnosti můžete simulovat aktivaci triggeru, abyste mohli otestovat tok závislý na triggeru.

Platí pro: operace

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

x-ms-capabilities

Když tuto vlastnost použijete na úrovni konektoru, poskytuje přehled možností, které konektor nabízí, včetně konkrétních operací.

Vztahuje se na: konektory

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

Pokud tuto vlastnost použijete na úrovni operace, zjistí, že operace podporuje nahrávání bloků dat a statickou velikost bloku, kterou může uživatel poskytnout.

Platí pro: operace

• chunkTransfer– Logická hodnota, která označuje, jestli je podporovaný přenos bloků dat.

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

x-ms-trigger

Určuje, zda je aktuální operace spouštěč, který vyvolá jednu událost. Pokud toto pole chybí, operace je action.

Platí pro: operace

• single – odpověď objektu
• batch – odpověď v podobě pole

"x-ms-trigger": "batch"

x-ms-trigger-hint

Popisuje, jak vyvolat událost pro operaci spouště.

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 požadavek na notifikaci webhooku. Toto schéma definuje datovou část webhooku, kterou externí služby publikují na adresu URL oznámení.

Platí pro: Zdroje

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

x-ms-notification-url

Pomocí logické hodnoty určete, jestli se má do tohoto parametru nebo pole pro operaci registrace webhooku zahrnout adresa URL oznámení webhooku.

Platí pro: Parametry a vstupní pole

"x-ms-notification-url": true

x-ms-url-encoding

Určete, jestli má aktuální parametr cesty používat dvojité kódování URL (double) nebo kódování s jednou adresou URL (single). Pokud toto pole chybí, ve výchozím nastavení se použije kódování single.

Platí pro: parametry cesty

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

x-ms-dynamic-values

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

Platí pro: parametry

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 můžete definovat dvěma způsoby:

• Použijte x-ms-dynamic-values

  Název	Povinné	Popis
  operationId	Ano	Operace, která vrací hodnoty.
  parameters	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:

Použití dynamických hodnot může vést k nejednoznačným odkazům na parametry. Například v následující definici operace dynamické hodnoty odkazují na ID pole. Definice neujasní, zda je odkaz na ID parametru nebo 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."
        }
    }
}

• Použijte x-ms-dynamic-list

  Nemůžete jednoznačně odkazovat na parametry. Tato funkce může být poskytnuta v budoucnosti. Pokud chcete, aby vaše operace využila jakékoli nové aktualizace, přidejte nové rozšíření x-ms-dynamic-list spolu s x-ms-dynamic-values. Pokud vaše dynamické rozšíření odkazuje na vlastnosti v rámci parametrů, musíte přidat nové rozšíření x-ms-dynamic-list spolu s x-ms-dynamic-values. 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 definujete každou vstupní vlastnost dynamické operace, která se volá, buď pomocí pole statické hodnoty nebo dynamického odkazu na vlastnost zdrojové operace. Obě tyto možnosti jsou definovány v následující části.

  • value– Toto je hodnota literálu, která se má použít 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 úplná cesta odkazu na parametr počínaje názvem parametru následovaným řetězcem cesty vlastnosti, 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 označenou jako interní s výchozí hodnotou, použijte výchozí hodnotu jako statickou hodnotu v definici, nikoli parameterReference. Výchozí hodnota ze seznamu se nepoužije, pokud je definovaná s využitím parameterReference.

Název	Povinné	Popis
operationId	Ano	Operace, která vrací seznam.
parameters	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 itemsPath není zadáno, 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."
    }
  }
} 

x-ms-dynamic-schema

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

Následující obrázek ukazuje, jak se změní vstupní formulář na základě položky, kterou uživatel vybere ze seznamu:

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

V této verzi uživatel vybral 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 můžete definovat dvěma způsoby:

• x-ms-dynamic-schema:

  Název	Povinné	Popis
  operationId	Ano	Operace, která vrací schéma.
  parameters	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 tuto vlastnost nezadáte, předpokládá se, že odpověď bude obsahovat 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:

Parametry můžou obsahovat 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
Správa tiketů	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žila jakékoli nové aktualizace, přidejte nové rozšíření x-ms-dynamic-properties spolu s x-ms-dynamic-schema. Pokud vaše dynamické rozšíření odkazuje na vlastnosti v rámci parametrů, musíte přidat nové rozšíření x-ms-dynamic-properties spolu s x-ms-dynamic-schema. 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 definujete každou vstupní vlastnost dynamické operace, která se volá, buď pomocí pole statické hodnoty nebo dynamického odkazu na vlastnost zdrojové operace. Obě tyto možnosti jsou definovány v následující části.

  • value– Toto je hodnota literálu, která se má použít 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 označenou jako interní s výchozí hodnotou, použijte výchozí hodnotu jako statickou hodnotu v definici, nikoli parameterReference. Výchozí hodnota ze schématu se nepoužije, pokud je definovaná s využitím parameterReference.

  Název	Povinné	Popis
  operationId	Ano	Operace, která vrací schéma.
  parameters	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.

  Pomocí x-ms-dynamic-properties můžete použít odkazy na parametry 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

Související informace

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.