Criar um conector personalizado com uma extensão do OpenAPI

Uma maneira de criar conectores personalizados para Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate ou Microsoft Power Apps é fornecer um arquivo de definição OpenAPI. Um arquivo de definição OpenAPI é um documento independente de linguagem e legível por computador que descreve as operações e os parâmetros da API. Além da funcionalidade pronta para usar do OpenAPI, você também pode incluir as seguintes extensões do OpenAPI ao criar conectores personalizados para Logic Apps e 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

As seções a seguir descrevem essas extensões.

resumo

Especifica o título da ação (operação).

Aplica-se a: operações
. Recomendado: use letra maiúscula para summary.
Exemplo: "Quando um evento é adicionado ao calendário" ou "Enviar um email"

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

x-ms-summary

Especifica o título de uma entidade.

Aplica-se a: parâmetros, esquema de resposta
Recomendado: usar letra maiúscula para x-ms-summary.
Exemplo: ID do calendário, assunto, descrição do evento

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

descrição

Fornece uma explicação detalhada sobre a funcionalidade da operação ou o formato e a função de uma entidade.

Aplica-se a: operações, parâmetros, esquema de resposta
Recomendado: usar letra maiúscula para description.
Exemplo: "Esta operação é disparada quando um novo evento é adicionado ao calendário", "Especifique o assunto do email".

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

x-ms-visibility

Especifica a visibilidade direcionada ao usuário para uma entidade.

Possíveis valores: important, advanced e internal
Aplica-se a: operações, parâmetros, esquemas

• O usuário sempre vê as operações e parâmetros important primeiro.
• O usuário vê advanced operações e parâmetros somente quando usa um menu extra.
• O usuário não vê internal operações e parâmetros.

Exemplo: os menus Ver mais e Mostrar opções avançadas ocultam advanced operações e parâmetros.

"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

Use para controle de versão e gerenciamento de ciclo de vida de uma operação.

Aplica-se a: operações

• family - Uma cadeia de caracteres que indica a pasta da família de operações.
• revision - Um inteiro que indica o número da revisão.
• replacement - Um objeto que contém as informações e as operações da API de substituição.

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

x-ms-operation-context

Use essa propriedade para simular a disparação de um gatilho para que você possa testar um fluxo dependente de gatilho.

Aplica-se a: operações

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

x-ms-capabilities

Quando você usa essa propriedade no nível do conector, ela fornece uma visão geral dos recursos que o conector oferece, incluindo operações específicas.

Aplica-se a: conectores

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

Quando você usa essa propriedade no nível da operação, ela identifica que a operação dá suporte ao carregamento em partes e ao tamanho da parte estática, que o usuário pode fornecer.

Aplica-se a: operações

• chunkTransfer— Um valor booliano que indica se há suporte para transferência de partes.

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

x-ms-trigger

Indica se a operação atual é um gatilho que produz um único evento. Se esse campo estiver ausente, a operação será um action.

Aplica-se a: operações

• single - Resposta do objeto
• batch - Resposta de matriz

"x-ms-trigger": "batch"

x-ms-trigger-hint

Descreve como acionar um evento para uma operação de gatilho.

Aplica-se a: operações

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

x-ms-notification-content

Contém uma definição de esquema de uma solicitação de notificação de webhook. Esse esquema define o conteúdo do webhook que os serviços externos postam na URL de notificação.

Aplica-se a: recursos

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

x-ms-notification-url

Use um valor booliano para especificar se uma URL de notificação de webhook deve ser incluída nesse parâmetro ou campo para uma operação de registro de webhook.

Aplica-se a: parâmetros e campos de entrada

"x-ms-notification-url": true

x-ms-url-encoding

Especifique se o parâmetro de caminho atual deve usar codificação de URL dupla (double) ou codificação de URL única (single). Se esse campo estiver ausente, ele usará como padrão a single codificação.

Aplica-se a: parâmetros de caminho

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

x-ms-dynamic-values

Os valores dinâmicos são uma lista de opções para o usuário selecionar parâmetros de entrada para uma operação. 

Aplica-se a: parâmetros

Como usar valores dinâmicos

Você pode definir valores dinâmicos de duas maneiras:

• Utilize x-ms-dynamic-values

  Nome	Obrigatória	Descrição
  operationId	Sim	A operação que retorna os valores.
  parameters	Sim	Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação de valores dinâmicos.
  value-collection	Não	Uma cadeia de caracteres de caminho que avalia uma matriz de objetos no conteúdo da resposta. Se value-collection não for especificado, a resposta será avaliada como uma matriz.
  value-title	Não	Uma cadeia de caracteres de caminho dentro de value-collection, que se refere à descrição do valor.
  value-path	Não	Uma cadeia de caracteres de caminho dentro de value-collection, que se refere ao valor do parâmetro.

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

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

• Utilize x-ms-dynamic-list

  Não é possível referenciar parâmetros sem ambiguidade. Esse recurso poderá ser fornecido no futuro. Se você quiser que sua operação aproveite as novas atualizações, adicione a nova extensão x-ms-dynamic-list junto com x-ms-dynamic-values. Além disso, se sua extensão dinâmica fizer referência a propriedades dentro de parâmetros, você deverá adicionar a nova extensão x-ms-dynamic-list junto com x-ms-dynamic-values. As referências de parâmetro que apontam para propriedades devem ser expressas como cadeias de caracteres de caminho.

  • parameters— Essa propriedade é um objeto em que você define cada propriedade de entrada da operação dinâmica que está sendo chamada com um campo de valor estático ou uma referência dinâmica à propriedade da operação de origem. Ambas as opções são definidas na seção a seguir.

  • value— Esse é o valor literal a ser usado para o parâmetro de entrada. No exemplo a seguir, o parâmetro de entrada da operação GetDynamicList denominada version é definido por um valor estático 2.0.

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

  • parameterReference— Esse é o caminho de referência de parâmetro completo, começando com o nome do parâmetro seguido pela cadeia de caracteres de caminho da propriedade a ser referenciada. Por exemplo, a propriedade de entrada da operação GetDynamicList chamada property1, que fica sob o parâmetro destinationInputParam1, é definida como uma referência dinâmica a uma propriedade chamada property1 sob o parâmetro sourceInputParam1 da operação de origem.

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

Com x-ms-dynamic-list, use referências de parâmetro com a cadeia de caracteres de caminho da propriedade referenciada. Utilize essas referências de parâmetros tanto para a chave quanto para o valor do parâmetro de operação dinâmica.

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

O esquema dinâmico indica que o esquema para o parâmetro ou resposta atual é dinâmico. Este objeto invoca uma operação que é definida pelo valor do campo, descobre dinamicamente o esquema e exibe a interface do usuário adequada para coletar a entrada do usuário ou mostra os campos disponíveis.

Aplica-se a: parâmetros, respostas

A imagem a seguir mostra como o formulário de entrada é alterado, com base no item selecionado pelo usuário na lista:

A imagem a seguir mostra como as saídas são alteradas, com base no item que o usuário seleciona na lista suspensa. Nesta versão, o usuário seleciona Carros:

Nesta versão, o usuário seleciona Comida:

Como usar o esquema dinâmico

Você pode definir o esquema dinâmico de duas maneiras:

• x-ms-dynamic-schema:

  Nome	Obrigatória	Descrição
  operationId	Sim	A operação que retorna o esquema.
  parameters	Sim	Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação dynamic-schema.
  value-path	Não	Uma cadeia de caracteres de caminho que se refere à propriedade que tem o esquema. Se você não especificar essa propriedade, a resposta será considerada para conter o esquema nas propriedades do objeto raiz. Se especificada, a resposta bem-sucedida deve conter a propriedade. Para um esquema vazio ou indefinido, este valor deve ser nulo.

    {
    "name": "dynamicListSchema",
    "in": "body",
    "description": "Dynamic schema for items in the selected list",
    "schema": {
        "type": "object",
        "x-ms-dynamic-schema": {
            "operationId": "GetListSchema",
            "parameters": {
                "listID": {
                    "parameter": "listID-dynamic"
                }
            },
            "value-path": "items"
        }
      }
    }
  

{

    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}

Exemplos de conectores de open source

• x-ms-dynamic-properties:

  Não há como referenciar parâmetros sem ambiguidade. Esse recurso poderá ser fornecido no futuro. Se você quiser que sua operação aproveite as novas atualizações, adicione a nova extensão x-ms-dynamic-properties junto com x-ms-dynamic-schema. Além disso, se sua extensão dinâmica fizer referência a propriedades dentro de parâmetros, você deverá adicionar a nova extensão x-ms-dynamic-properties junto com x-ms-dynamic-schema. As referências de parâmetro que apontam para propriedades devem ser expressas como cadeias de caracteres de caminho.

  • parameters— Essa propriedade é um objeto em que você define cada propriedade de entrada da operação dinâmica que está sendo chamada com um campo de valor estático ou uma referência dinâmica à propriedade da operação de origem. Ambas as opções são definidas na seção a seguir.

  • value— Esse é o valor literal a ser usado para o parâmetro de entrada. No exemplo a seguir, o parâmetro de entrada da operação GetDynamicSchema denominada version é definido com um valor estático 2.0.

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

  • parameterReference - Esse é o caminho completo de referência do parâmetro, começando pelo nome do parâmetro, seguido da cadeia de caracteres de caminho da propriedade a ser referenciada. Por exemplo, a propriedade de entrada da operação GetDynamicSchema chamada property1, que fica sob o parâmetro destinationInputParam1 é definida como uma referência dinâmica a uma propriedade chamada property1 sob o parâmetro sourceInputParam1 da operação de origem.

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

  Observação

  Para fazer referência a qualquer propriedade marcada como interna com um valor padrão, use o valor padrão como um valor estático na definição aqui, em vez de parameterReference. O valor padrão do esquema não será usado se for definido usando parameterReference.

  Nome	Obrigatória	Descrição
  operationId	Sim	A operação que retorna o esquema.
  parameters	Sim	Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação dynamic-schema.
  itemValuePath	Não	Uma cadeia de caracteres de caminho que se refere à propriedade que tem o esquema. Se não for especificada, a resposta é assumida para conter o esquema no objeto raiz. Se especificada, a resposta bem-sucedida deve conter a propriedade. Para um esquema vazio ou indefinido, este valor deve ser nulo.

  Ao usar x-ms-dynamic-properties, você pode utilizar referências de parâmetro com a string de caminho da propriedade a ser referenciada, tanto para a chave quanto para o valor da referência de parâmetro de operação dinâmica.

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

Próxima etapa

Criar um conector personalizado de uma definição OpenAPI

Informações relacionadas

Visão geral de conectores personalizados

Faça comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.