Criar um conector personalizado com uma extensão OpenAPI

  • Artigo

Uma forma de criar conectores personalizados para o Azure Logic Apps, o Microsoft Power Automate ou o Microsoft Power Apps é indicar um ficheiro de definições de OpenAPI, que é um documento legível por computadores e agnóstico em termos 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
Recomendado: utilizar capitalização de frase para summary.
Exemplo: "quando um evento é adicionado ao calendário" ou "Enviar um e-mail"

"resumo" de cada operação.

"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: utilizar capitalização de título para x-ms-summary.
Exemplo: "ID de calendário", "Assunto", "Descrição do Evento"

"x-ms-summary" para cada entidade.

"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: utilizar capitalização de frase para description.
Exemplo: "Esta operação é acionada quando um novo evento é adicionado ao calendário", "Especifique o assunto do e-mail"

"descrição" de cada operação ou entidade.

"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

  • As operações e os parâmetros important são sempre apresentados primeiro ao utilizador.
  • As operações e os parâmetros advanced estão ocultos num menu adicional.
  • As operações e os parâmetros internal estão ocultos do utilizador.

Nota

Para os parâmetros que são internal e required, tem de fornecer valores predefinidos.

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

"x-ms-visibility" para mostrar ou ocultar as operações e os 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 que denota a pasta da família da operação.
  • revision—Um número inteiro que denota 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 é suportada a transferência de segmentos.
"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 esta é uma operação action.

Aplica-se a: operações

  • single—Resposta do objeto
  • batch—Resposta da matriz
"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 do caminho atual deve ser duplo com codificação URL double ou único com codificação URL single. A ausência deste campo indica a codificação single.

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 caminho é um ponteiro JSON que não contém a barra à esquerda. Assim, /property/childProperty é um ponteiro JSON e property/childProperty é uma cadeia de caminho.

Há duas maneiras de definir valore dinâmicos:

  1. Utilizar 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 definição seguinte de uma operação, os valores dinâmicos referenciam o campo id, que é ambíguo a partir da definição, uma vez que não é claro se referencia o parâmetro id ou a 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 quiser que a sua operação tire partido de todas as novas atualizações, adicione a nova extensão x-ms-dynamic-list juntamente com x-ms-dynamic-values. De igual modo, se a sua extensão dinâmica fizer referência a propriedades dentro de parâmetros, terá de adicionar a nova extensão x-ms-dynamic-list juntamente 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 em que cada propriedade de entrada da operação dinâmica que está a ser chamada é definida com um campo de valor estático ou com 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 utilizar no parâmetro de entrada. No seguinte exemplo, o parâmetro de entrada da operação GetDynamicList com o nome version é definido ao utilizar um valor estático de 2.0.

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

    • parameterReference—Este é o caminho completo de referência ao parâmetro, que começa com o nome do parâmetro seguido da cadeia de caminho da propriedade que está a ser referenciada. Por exemplo, a propriedade de entrada da operação GetDynamicList denominada property1, sob o parâmetro destinationInputParam1 é definida como uma referência dinâmica a uma propriedade denominada property1 no parâmetro sourceInputParam1 da operação de origem.

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

      Nota

      Se quiser fazer referência a alguma propriedade que esteja marcada como interna com um valor predefinido, tem de utilizar o valor predefinido como valor estático na definição, em vez de parameterReference. O valor predefinido da lista não é utilizado se for definido através de parameterReference.

      Nome Obrigatório 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 fornecido, a resposta é avaliada como uma matriz.
      itemTitlePath Não Uma cadeia de caminho no objeto dentro de  itemsPath , que se refere à descrição do valor.
      itemValuePath Não Uma cadeia de caminho no objeto dentro de  itemsPath  que faz referência ao valor do item.

      Com x-ms-dynamic-list, utilize referências a parâmetros com a cadeia de caminho da propriedade a que está a fazer referência. 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 Automóveis:

O utilizador seleciona Automóveis

Nesta versão, o utilizador seleciona Alimentação:

O utilizador seleciona Alimentação

Como utilizar o esquema dinâmico

Nota

Uma cadeia de caminho é um ponteiro JSON que não contém a barra à esquerda. Assim, /property/childProperty é um ponteiro JSON e property/childProperty é uma cadeia de caminho.

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, pressupõe-se que a resposta contém o esquema nas propriedades do objeto de 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 com o nome query, o que não pode ser compreendido de forma determinista com base na definição — quer esteja a fazer referência ao objeto de parâmetro query ou à propriedade de cadeia 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."
        }
    }
}
    Exemplos de conectores open source
    Conector Cenário Associar
    Emissão de Pedidos Obtenha esquema para detalhes de um evento selecionado Emissão de Pedidos

  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 quiser que a sua operação tire partido de todas as novas atualizações, adicione a nova extensão x-ms-dynamic-properties juntamente com x-ms-dynamic-schema. De igual modo, se a sua extensão dinâmica fizer referência a propriedades dentro de parâmetros, terá de adicionar a nova extensão x-ms-dynamic-properties juntamente 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 em que cada propriedade de entrada da operação dinâmica que está a ser chamada é definida com um campo de valor estático ou com 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 utilizar no parâmetro de entrada. No exemplo seguinte, o parâmetro de entrada da operação GetDynamicSchema com o nome version é definido com o valor estático 2.0.

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

    • parameterReference—Este é o caminho completo de referência ao parâmetro, que começa com o nome do parâmetro seguido da cadeia de caminho da propriedade que está a ser referenciada. Por exemplo, a propriedade de entrada da operação GetDynamicSchema denominada property1, sob o parâmetro destinationInputParam1 é definida como uma referência dinâmica a uma propriedade denominada property1 no parâmetro sourceInputParam1 da operação de origem.

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

      Nota

      Se quiser fazer referência a alguma propriedade que esteja marcada como interna com um valor predefinido, tem de utilizar o valor predefinido como valor estático na definição, em vez de parameterReference. O valor predefinido do esquema não é utilizado se for definido através de parameterReference.

      Nome Obrigatório 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, pressupõe-se que a resposta contém o esquema no objeto de 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 a parâmetros podem ser utilizadas com a cadeia de caminho da propriedade que está a ser referenciada, tanto para a chave como para o valor da referência ao parâmetro da 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 definição de OpenAPI

Descriçã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 enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.