Partilhar via

Criar um conector personalizado com uma extensão OpenAPI

Uma maneira de criar conectores personalizados para Microsoft Copilot Studio os Aplicativos Lógicos Microsoft Power Automate do Azure ou Microsoft Power Apps é fornecer um OpenAPI arquivo de definição, que é um documento legível por máquina e independente de linguagem que descreve as operações e os parâmetros da sua API. Juntamente com a funcionalidade pronta a utilizar do OpenAPI, também pode incluir as seguintes extensões OpenAPI quando criar conectores personalizados para Logic Apps e Power Automate:

As seguintes secções descrevem estas extensões.

resumo

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

Aplica-se a: Operações Recomendadas: Use maiúsculas e minúsculas
para summary.
Exemplo: "Quando um evento é adicionado ao calendário" ou "Enviar um e-mail"

"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: Use caso de título 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

Especifica uma explicação detalhada da funcionalidade da operação ou do formato e função de uma entidade.

Aplica-se a: Operações, parâmetros, esquema
de resposta Recomendado: Use maiúsculas e minúsculas para description.
Exemplo: "Esta operação é acionada quando um novo evento é adicionado ao calendário", "Especifique o assunto do e-mail"

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

x-ms-visibility

Determina a visibilidade da entidade para o utilizador.

Valores possíveis: important, advanced e internal
Aplica-se a: Operações, parâmetros, esquemas

  • important As operações e os parâmetros são sempre mostrados ao utilizador primeiro.
  • advanced As operações e os parâmetros ficam ocultos em um menu adicional.
  • internal operações e parâmetros são ocultos do utilizador.

Nota

Para parâmetros que são internal e required, você deve fornecer valores padrão.

Exemplo: Os menus Ver mais e Mostrar opções avançadas estão a ocultar 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

Utilizado para controlo de versões e gestão do 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 número inteiro indicando o número da revisão.
  • replacement—Um objeto que contém as informações e operações da API de substituição.
"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Utilizado para simular a ativação do acionador para permitir o teste de um fluxo dependente do acionador.

Aplica-se a: operações

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

x-ms-capabilities

Quando utilizado a nível do conector, trata-se de uma descrição geral das capacidades oferecidas pelo conector, incluindo operações específicas.

Aplica-se a: Conectores

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

Quando utilizado a nível da operação, é utilizado para identificar se a operação suporta o tamanho do segmento de carregamento e/ou estático e pode ser fornecida pelo utilizador.

Aplica-se a: operações

  • chunkTransfer—Um valor booleano para indicar se a transferência de partes é suportada.
"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Identifica se a operação atual é um acionador que produz um único evento. A ausência deste campo significa que se trata de uma action operação.

Aplica-se a: operações

  • single—Resposta do objeto
  • batch—Resposta do array
"x-ms-trigger": "batch"

x-ms-trigger-hint

Uma descrição de como acionar um evento para uma operação de acionador.

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 um pedido de notificação de webhook. Trata-se do esquema para uma payload de webhook publicada por serviços externos no URL de notificação.

Aplica-se a: Recursos

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

x-ms-notification-url

Identificado num valor Booleano se um URL de notificação de webhook deve ser colocado neste parâmetro/campo para uma operação de registo de webhook.

Aplica-se a: campos de Parâmetros/entrada

"x-ms-notification-url": true

x-ms-url-encoding

Identifica se o parâmetro path atual deve ser codificado double por URL duplo ou por URL single único. A ausência deste campo indica single codificação.

Aplica-se a: Parâmetros de caminho

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

Utilizar valores dinâmicos

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

Aplica-se a: Parâmetros

Valores dinâmicos para mostrar listas.

Como utilizar valores dinâmicos

Nota

Uma cadeia de caracteres de caminho é um ponteiro JSON que não contém a barra à esquerda. Portanto, este é um ponteiro JSON: /property/childProperty, e este é um caminho string: property/childProperty.

Há duas maneiras de definir valore dinâmicos:

  1. Utilização x-ms-dynamic-values

    Nome Necessária Descrição
    operationId Sim A operação que devolve os valores.
    parâmetros 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 caminho que é avaliada como uma matriz de objetos no payload de resposta. Se value-collection não for especificado, a resposta será avaliada como uma matriz.
    value-title Não Uma cadeia de caminho no objeto dentro de value-collection que referencia a descrição do valor.
    value-path Não Uma cadeia de caminho no objeto dentro de value-collection que referencia o 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>"
        }
    }
}

    Nota

    É possível ter referências a parâmetros ambíguos ao utilizar valores dinâmicos. Por exemplo, na seguinte definição de uma operação, os valores dinâmicos fazem referência ao campo id, que é ambíguo da definição porque não está claro se ele faz referência ao parâmetro id ou à propriedade 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

    Não existe uma forma de referenciar parâmetros de forma não ambígua. Esta funcionalidade poderá ser fornecida 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ê terá que adicionar a nova extensão x-ms-dynamic-list junto com x-ms-dynamic-values. As referências a parâmetros que apontam para propriedades têm de ser expressas como cadeias de caminho.

    • parameters—Esta propriedade é um objeto onde cada propriedade de entrada da operação dinâmica que está a ser chamada é definida com um campo de valor estático ou uma referência dinâmica à propriedade da operação de origem. Estas duas opções são definidas no seguinte.

    • value—Este é 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 operação chamada version é definido usando um valor estático de 2.0.

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

    • parameterReference—Este é o caminho de referência de parâmetro completo, começando com o nome do parâmetro seguido pela cadeia de caracteres do caminho da propriedade a ser referenciada. Por exemplo, a propriedade input da operação GetDynamicList named property1 , que está sob o parâmetrodestinationInputParam1 , é definida como uma referência dinâmica a uma propriedade chamadaproperty1 sob o parâmetro sourceInputParam1 da operação de origem.

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

      Nota

      Se você quiser fazer referência a qualquer propriedade marcada como interna com um valor padrão, será necessário usar o valor padrão como um valor estático na definição aqui, em vez de parameterReference. O valor padrão da lista não será usado se for definido usando parameterReference.

      Nome Necessária Descrição
      operationId Sim A operação que devolve a lista.
      parâmetros Sim Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação de lista dinâmica.
      itemsPath Não Uma cadeia de caminho que é avaliada como uma matriz de objetos no payload de resposta. Se itemsPath não for fornecida, a resposta será avaliada como uma matriz.
      itemTitlePath Não Uma cadeia de caracteres de caminho no objeto interno itemsPath que se refere à descrição do valor.
      itemValuePath Não Uma cadeia de caracteres de caminho no objeto dentro itemsPath que se refere ao valor do item.

      Com x-ms-dynamic-list, use referências de parâmetro com a cadeia de caracteres de caminho da propriedade que você está a referenciar. Utilize estas referências a parâmetros para a chave e o valor da referência 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."
    }
  }
}

Utilizar esquema dinâmico

O esquema dinâmico indica que o esquema do parâmetro ou resposta atual é dinâmico. Este objeto invoca uma operação que é definida pelo valor neste campo, deteta dinamicamente o esquema e apresenta a interface de utilizador adequada para a recolha da entrada do utilizador ou mostra os campos disponíveis.

Aplica-se a: Parâmetros, respostas

Esta imagem mostra como o formulário de entrada é alterado, com base no item que o utilizador seleciona na lista:

O formulário é alterado com base na seleção feita pelo utilizador.

A imagem mostra como as entradas são alteradas, com base no item que o utilizador seleciona na lista pendente. Nesta versão, o utilizador seleciona Carros:

O utilizador seleciona Automóveis

Nesta versão, o utilizador seleciona Food:

O utilizador seleciona Alimentação

Como utilizar o esquema dinâmico

Nota

Uma cadeia de caracteres de caminho é um ponteiro JSON que não contém a barra à esquerda. Portanto, este é um ponteiro JSON: /property/childProperty, e este é um caminho string: property/childProperty.

Há duas maneiras de definir um esquema dinâmico:

  1. x-ms-dynamic-schema:

    Nome Necessária Descrição
    operationId Sim A operação que devolve o esquema.
    parâmetros Sim Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação de esquema dinâmico.
    value-path Não Uma cadeia de caminho que se refere à propriedade que tem o esquema. Se não for especificado, presume-se que a resposta contenha o esquema nas propriedades do objeto raiz. Se especificado, 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"
      }
    }
  }

    Nota

    Poderão existir referências ambíguas nos parâmetros. Por exemplo, na seguinte definição de uma operação, o esquema dinâmico faz referência a um campo chamado query, que não pode ser compreendido deterministicamente a partir da definição, seja fazendo referência à consulta de objeto de parâmetro ou à consulta/consulta de propriedadede cadeia de caracteres.

    {

    "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 open source
    Conector Cenário Associar
    Emissão de Pedidos Obtenha esquema para detalhes de um evento selecionado Emissão de bilhetes

  2. x-ms-dynamic-properties:

    Não existe uma forma de referenciar parâmetros de forma não ambígua. Esta funcionalidade poderá ser fornecida 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ê terá que adicionar a nova extensão x-ms-dynamic-properties junto com x-ms-dynamic-schema. As referências a parâmetros que apontam para propriedades têm de ser expressas como cadeias de caminho.

    • parameters—Esta propriedade é um objeto onde cada propriedade de entrada da operação dinâmica que está a ser chamada é definida com um campo de valor estático ou uma referência dinâmica à propriedade da operação de origem. Estas duas opções são definidas no seguinte.

    • value—Este é 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 chamada version é definido com um valor estático de 2.0.

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

    • parameterReference—Este é o caminho de referência de parâmetro completo, começando com o nome do parâmetro seguido pela cadeia de caracteres do caminho da propriedade a ser referenciada. Por exemplo, a propriedade input da operação GetDynamicSchema chamada property1 , que está sob o parâmetrodestinationInputParam1 , é definida como uma referência dinâmica a uma propriedade chamadaproperty1 sob o parâmetro sourceInputParam1 da operação de origem.

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

      Nota

      Se você quiser fazer referência a qualquer propriedade marcada como interna com um valor padrão, será necessário usar 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 pelo uso parameterReference.

      Nome Necessária Descrição
      operationId Sim A operação que devolve o esquema.
      parâmetros Sim Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação de esquema dinâmico.
      itemValuePath Não Uma cadeia de caminho que se refere à propriedade que tem o esquema. Se não for especificado, presume-se que a resposta contenha o esquema no objeto raiz. Se especificado, a resposta bem sucedida deve conter a propriedade. Para um esquema vazio ou indefinido, este valor deve ser nulo.

      Com x-ms-dynamic-properties, as referências de parâmetros podem ser usadas com a cadeia de caracteres 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óximo passo

Criar um conector personalizado a partir de uma OpenAPI definição

Visão geral dos conectores personalizados

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.

  • Last updated on