Expandir uma definição de OpenAPI para um conector personalizado

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:

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

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

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

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

"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 

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:

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:

Nesta versã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

Consulte também

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.