Implementar Ligação de Teste

A Ligação de Teste é um ponto de entrada simples que pode ser definido para um conector para utilização com o Azure Logic Apps, o Power Automate ou o Power Apps. Ao expor uma operação à ligação de teste, o conector pode fornecer a validação de runtime e de "design-time" dos respetivos parâmetros.

Pré-requisitos

• Experiência básica na construção de aplicações lógicas ou fluxos e conectores personalizados.
• Noções básicas sobre a Especificação de OpenAPI (anteriormente conhecida como Swagger).
• Uma conta GitHub.
• A definição de OpenAPI de amostra para este tutorial.

Adicionar uma operação de ligação de teste nova

A adição de uma operação para TestConnection é um processo muito simples. Tem a opção de utilizar qualquer operação já existente como forma de testar a ligação ou de adicionar uma operação específica cuja tarefa é apenas testar os parâmetros da ligação. A operação tem de ser "get" e de suportar uma chamada sem parâmetros ou com parâmetros codificados.

A adição de uma operação nova para este fim poderá ter o seguinte aspeto na especificação OpenAPI:

    "/diagnostics/testconnection": {
      "get": {
        "tags": [ "Diagnostics" ],
        "operationId": "TestMyAPIConnection",
        "consumes": [],
        "produces": [],
        "responses": {
          "200": { "description": "OK" },
          "default": { "description": "Operation Failed." }
        },
        "x-ms-visibility": "internal"
      }
    }

Importante

Repare que esta operação está marcada como internal. Se adicionar um ponto de entrada novo para este fim, encoraja-se vivamente que esta operação seja ocultada do utilizador ao definir a visibilidade como tal.

O ponto final destinado a ser utilizado como ligação de teste tem de ser identificado mediante a adição de uma extensão à API no nível superior, desta forma:

 "x-ms-capabilities": {
    "testConnection": {
      "operationId": "TestMyAPIConnection",
      "parameters": {}
    }
  }

O operationId especificado neste atributo tem de existir dentro desta especificação de OpenAPI, de modo a ser válido.

Reutilizar uma operação já existente para a ligação de teste

Muitas vezes, é mais simples e fácil de gerir identificar uma operação já existente que possa validar a viabilidade da ligação sem incorrer em muitos custos ou latência. Esta validação pode ser obtida sem adicionar uma operação nova, mas ao simplesmente indicar que operação utilizar e que parâmetros transmitir (se os houver).

O exemplo seguinte utiliza uma operação "get" já existente, chamada GetTables, que deverá ser bem-sucedida se a ligação for válida e os parâmetros estiverem certos. Para garantir que a operação de ligação de teste é executada o mais depressa possível, o exemplo também adiciona um parâmetro à chamada para especificar que só deve ser devolvida a primeira linha.

 "x-ms-capabilities": {
    "testConnection": {
      "operationId": "GetTables",
      "parameters": {
        "$top": 1
      }
    }
  }

Implementar ligação de teste

Se precisar de implementar a ligação de teste e mais nenhuma operação já existente for adequada para esse fim, pode fazê-lo com uma chamada para o back-end simples. A operação não necessita de tomar quaisquer parâmetros nem de devolver conteúdo. O caminho do URL também não é importante e pode ser selecionado de acordo com a sua preferência. A única medida de sucesso de uma chamada de ligação de teste é uma resposta bem-sucedida (por exemplo, 200) da chamada HTTP. No âmbito da operação de ligação, o contrato pede que o conector valide o contexto de autenticação e os parâmetros da ligação.

Para que isso aconteça, consulte algo simples no back-end, que utilizará os parâmetros da autenticação e qualquer base de dados ou âmbito que possam estar implícitos. Um bom exemplo de uma abordagem à ligação de teste é consultar a primeira linha de uma tabela simples.

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.