Estender uma definição OpenAPI para um conector personalizado

Uma das formas de criar conectores personalizados para Aplicativos Lógicos do Azure, Microsoft Power Automate ou Microsoft Power Apps é fornecer um arquivo de definição OpenAPI, que é um documento legível por computador independente de linguagem e que descreve as operações e os parâmetros da API. Além da funcionalidade pronta para uso da OpenAPI, você também pode incluir as seguintes extensões OpenAPI ao criar conectores personalizados para os Aplicativos Lógicos e o 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 primeira letra da frase em 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: Use primeira letra do título em 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

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

Aplica-se a: operações, parâmetros, esquema de resposta
Recomendado: Use primeira letra da frase em 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.

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

• Operações e parâmetros important são sempre exibidos para o usuário primeiro.
• Operações e parâmetros advanced estão ocultos em um menu adicional.
• Operações e parâmetros internal estão ocultos para o usuário.

Observação

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 ocultam operações e parâmetros advanced.

"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

Usado 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

Usado para simular o acionamento de um gatilho para habilitar o teste de 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 usado no nível do conector, essa é uma visão geral dos recursos oferecidos pelo conector, incluindo operações específicas.

Aplica-se a: conectores

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

Quando usado no nível de operação, é usado para identificar que a operação dá suporte ao carregamento de agrupamento e/ou tamanho de parte estática, e pode ser fornecido pelo usuário.

Aplica-se a: operações

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

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

x-ms-trigger

Identifica se a operação atual é um gatilho que produz um único evento. A ausência desse campo significa que esta é uma operação action.

Aplica-se a: operações

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

"x-ms-trigger": "batch"

x-ms-trigger-hint

Uma descrição de 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. Este é o esquema para um conteúdo de webhook postado por serviços externos para a URL de notificação.

Aplica-se a: recursos

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

x-ms-notification-url

Identifica em um valor booliano se uma URL de notificação de webhook deve ser colocada nesse parâmetro/campo para uma operação de registro de webhook.

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

"x-ms-notification-url": true

x-ms-url-encoding

Identifica se o parâmetro de caminho atual deve ser codificado por URL dupla double ou por URL única single. A ausência desse campo indica codificação single.

Aplica-se a: parâmetros de caminho

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

Usar valores dinâmicos

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

Observação

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

Há duas maneiras de definir valores dinâmicos:

1. Usar o x-ms-dynamic-values

   Nome	Obrigatória	Descrição
   operationId	Sim	A operação que retorna os valores.
   parâmetros	Sim	Um objeto que fornece os parâmetros de entrada necessários para invocar uma operação dynamic-values.
   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>"
           }
       }
   }  
   

   Observação

   É possível ter referências de parâmetro ambíguas ao usar valores dinâmicos. Por exemplo, na definição a seguir de uma operação, os valores dinâmicos referenciam o 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 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-list junto com x-ms-dynamic-values. Além disso, se a sua extensão dinâmica fizer referências a propriedades em parâmetros, adicione 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 no qual cada propriedade de entrada da operação dinâmica que está sendo chamada é definida 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 abaixo.

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

     Observação

     Se você quiser fazer referência a qualquer propriedade que esteja 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 do parameterReference. O valor padrão da lista não será usado se for definido pelo parameterReference.

     Nome	Obrigatória	Descrição
     operationId	Sim	A operação que retorna 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 caracteres de caminho que avalia uma matriz de objetos no conteúdo da resposta. Se  itemsPath  não for especificado, a resposta será avaliada como uma matriz.
     itemTitlePath	Não	Uma cadeia de caracteres de caminho no objeto dentro de  itemsPath  que se refere à descrição do valor.
     itemValuePath	Não	Uma cadeia de caracteres de caminho no objeto no itemsPath que refere-se ao valor do item.

     Com x-ms-dynamic-list, use referências de parâmetro com a cadeia de caracteres de caminho da propriedade referenciada. Use essas referências de parâmetro para a chave e o valor da referência de 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."
         }
       }
     } 
     

Usar esquema dinâmico

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

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

Esta imagem mostra como as saídas mudam, 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

Observação

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

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

1. x-ms-dynamic-schema:

   Nome	Obrigatória	Descrição
   operationId	Sim	A operação que retorna o esquema.
   parâmetros	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 não for especificada, a resposta é assumida 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"
         }
       }
     }
   

   Observação

   Pode haver referências ambíguas nos parâmetros. Por exemplo, na definição a seguir de uma operação, o esquema dinâmico faz referência a um campo denominado query, que não pode ser reconhecido de forma determinística a partir da definição — se faz referência ao objeto de parâmetro query ou à propriedade da cadeia de caracteres 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 de código aberto

   Conector	Cenário	Link
   Emissão de tíquetes	Obtenha o esquema para detalhes de um evento selecionado	Emissão de tíquetes

2. x-ms-dynamic-properties:

   Não há como referenciar parâmetros sem ambiguidade. Esse recurso poderá ser fornecido no futuro. Se desejar 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 a sua extensão dinâmica fizer referências a propriedades em parâmetros, adicione 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 no qual cada propriedade de entrada da operação dinâmica que está sendo chamada é definida 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 abaixo.

   • 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

     Se você quiser fazer referência a qualquer propriedade que esteja 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 do 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.
     parâmetros	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.

     Com x-ms-dynamic-properties, referências de parâmetro 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 do 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

Confira também

Visão geral de conectores personalizados

Enviar 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.