Implementare la connessione di test

La connessione di test è un semplice punto di ingresso che è possibile definire per l'uso di un connettore con App per la logica di Azure, Power Automate o Power Apps. Esponendo un'operazione per la connessione di test, il connettore può fornire la convalida dei parametri della connessione in fase di progettazione e di esecuzione.

Prerequisiti

• Esperienza di base per la creazione delle app per la logica o dei flussi e dei connettori personalizzati.
• Conoscenza di base della specifica OpenAPI (precedentemente nota come Swagger).
• Un account GitHub.
• La definizione OpenAPI di esempio per questa esercitazione.

Aggiungere una nuova operazione per la connessione di test

L'aggiunta di un'operazione per TestConnection è un processo molto semplice. È possibile scegliere di usare qualsiasi operazione esistente come mezzo per testare la connessione oppure aggiungerne una specifica il cui unico scopo è testare i parametri. L'operazione deve essere di tipo "get" e deve supportare una chiamata senza parametri o con parametri hardcoded.

L'aggiunta di una nuova operazione a questo scopo potrebbe essere simile alla seguente nella specifica OpenAPI:

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

Importante

Nota che questa operazione è contrassegnata come internal. Se aggiungi un nuovo punto di ingresso a questo scopo, è consigliabile nascondere questa operazione all'utente contrassegnando la visibilità come tale.

L'endpoint destinato a essere usato come connessione di test deve essere identificato con l'aggiunta di un'estensione al livello superiore dell'API, come segue:

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

Per essere valido, il valore di operationId specificato in questo attributo deve esistere all'interno della stessa specifica OpenAPI.

Riutilizzare un'operazione esistente per la connessione di test

Spesso è più semplice e più gestibile identificare un'operazione esistente in grado di convalidare la fattibilità della connessione senza incorrere in latenza o costi elevati. Questo risultato si può ottenere senza aggiungere una nuova operazione, ma semplicemente indicando quale usare e quali eventuali parametri passare.

Nell'esempio seguente viene usata un'operazione "get" esistente denominata GetTables che dovrebbe riuscire se la connessione è valida e i parametri sono corretti. Per assicurati che l'operazione della connessione di test venga eseguita il più rapidamente possibile, viene anche aggiunto un parametro alla chiamata per specificare che deve essere restituita solo la prima riga.

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

Implementare una connessione di test

Se è necessario implementare la connessione di test e nessun'altra operazione esistente è appropriata a questo scopo, è possibile eseguire una chiamata semplice al back-end. L'operazione non deve accettare parametri né restituire contenuto. Anche il percorso URL può essere selezionato in base alle proprie preferenze, perché non è importante. L'unica misura del successo di una chiamata alla connessione di test è una risposta di operazione riuscita (ad esempio 200) della chiamata HTTP. All'interno dell'operazione della connessione di test, il contratto richiede che il connettore convalidi il contesto di autenticazione e i parametri di connessione.

A questo scopo esegui una query sul back-end per trovare qualcosa di semplice, per cui verranno usati i parametri di autenticazione ed eventuali database o ambiti che potrebbero essere coinvolti. Un esempio valido di approccio alla connessione di test è l'esecuzione di una query sulla prima riga di una tabella semplice.

Inviare commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.