Creare connettori dati avanzati (anteprima)

[Questo articolo fa parte della documentazione non definitiva, pertanto è soggetto a modifiche.]

Quando i dati da usare con il connettore sono strutturati con tabelle o elenchi, il protocollo del connettore avanzato consente di offrire più facilmente connettori di livello aziendale a prestazioni elevate. I connettori avanzati fungono da potente origine delle conoscenze per gli agenti e consentono di creare facilmente app canvas in Power Apps e comporre la logica usando Power Automate.

Azioni e connettori avanzati

I connettori creati usando endpoint OpenAPI (swagger) sono considerati connettori di azione. OpenAPI offre un formato standardizzato per descrivere le API HTTP di qualsiasi dimensione. Consente di definire in modo esplicito gli endpoint (percorsi), i metodi HTTP supportati e gli schemi di richiesta/risposta. Ogni operazione (una combinazione di percorso e metodo) rappresenta un'azione chiamabile specifica dell'API, adatta alle API che seguono i principi RESTful.

Per le origini dati strutturate , il controllo OpenAPI con granularità fine diventa oneroso perché le origini dati tabulari in genere non sono definite da un endpoint OpenAPI. La definizione OpenAPI non è associata ai metadati che descrivono i dati strutturati, quindi non si adatta alle modifiche che aggiungono nuove tabelle, colonne o relazioni a un'origine dati. Il connettore generato usando la definizione OpenAPI statica non può rappresentare queste modifiche fino a quando non viene rigenerato.

I connettori avanzati richiedono un endpoint che fornisce informazioni che descrivono un set dinamico di tabelle, schemi e funzionalità. Questo articolo descrive un protocollo che è possibile implementare per creare un'API Web ASP.NET Core basata su un protocollo simile a OData anziché OpenAPI. Questo protocollo è progettato per i dati tabulari e usa le funzionalità OData per gestire filtri, ordinamento, paging e relazioni non forniti da OpenAPI.

Dati strutturati

Cosa si intende per dati strutturati? I dati possono essere strutturati usando tabelle di database effettive, ma possono anche usare terminologia diversa, ad esempio "site" anziché "database" e "list" anziché "table". Il punto chiave è che i dati sono strutturati in una gerarchia di risorse simile alla seguente:

• Un set di dati espone una raccolta di tabelle
• Una tabella contiene righe e colonne contenenti dati
• Un elemento rappresenta una riga di una tabella

Connettori che usano questo modello

Di seguito sono riportati alcuni dei connettori avanzati che usano questo modello:

Come funziona

Il protocollo del connettore avanzato include tre parti principali:

• Endpoint delle capacità: Descrivere i set di dati, le tabelle e le colonne a cui il connettore può accedere e le operazioni che possono eseguire.
• Transpiler: converte le richieste di stile GET OData per recuperare dati dalla fonte dati. Queste richieste usano opzioni di query OData come $filter, $select$orderby, $sort, e$top
• Implementazione dell'operazione CUD: descrive come eseguire operazioni di creazione, aggiornamento ed eliminazione sulle risorse per l'origine dati

A livello generale, è necessario implementare il processo seguente:

1. Creare un'API Web di ASP.NET Core che implementa il protocollo del connettore avanzato.
2. Distribuire il progetto API Web di ASP.NET Core nell'ambiente di hosting preferito.
3. Creare il connettore personalizzato usando lo strumento da riga di comando paconn.
4. Configurare l'autenticazione.
5. Condividere e testare il connettore.

Endpoint delle funzionalità

Il protocollo del connettore avanzato dipende dall'implementazione di cinque endpoint che descrivono le funzionalità del servizio. La tabella seguente riepiloga questi endpoint e include collegamenti alle sezioni di questo documento che illustrano come implementarle.

Interfaccia ITableProvider

Le interfacce ITableProviderFactory e ITableProvider seguenti forniscono i metodi previsti per implementare gli endpoint delle capacità del protocollo avanzato del connettore. Aggiungere il codice seguente all'interno della Services cartella del progetto API Web core di ASP.NET.

// Helper to get a provider for a given auth token. 
public interface ITableProviderFactory
{
    ITableProvider Get(IReadOnlyDictionary<string, string> settings);
}

/// <summary>
/// Datasource Provider. Host implements this to provide the RecordTypes for a specific source.
/// </summary>
public interface ITableProvider
{
    // Return list of datasets (logical name, display name)
    public Task<DatasetResponse.Item[]> GetDatasetsAsync(
      CancellationToken cancellationToken = default
      );

    // Provider list of the tables.
    public Task<GetTablesResponse> GetTablesAsync(
      string dataset, 
      CancellationToken cancellationToken = default);

    public Task<RecordType> GetTableAsync(
      string dataset, 
      string tableName, 
      CancellationToken cancellationToken = default);

    public Task<TableValue> GetTableValueAsync(
      string dataset, 
      string tableName, 
      CancellationToken cancellationToken = default);
}

Implementare l'API Web ASP.NET Core con una separazione tra front-end (API REST) e back-end (provider di origine dati). Il back-end viene astratto tramite l'interfaccia ITableProvider , che è possibile implementare per connettersi a qualsiasi origine dati tabulare.

Classi usate

Nell'applicazione API Web principale ASP.NET creata aggiungere i pacchetti NuGet Microsoft.PowerFx.Connectors e Microsoft.PowerFx.Core in modo da avere accesso ai tipi usati in ITableProvider, ad esempio RecordType e TableValue

Alcuni altri tipi necessari non sono attualmente inclusi nei pacchetti NuGet di PowerFx. Trovali all'interno del campione del connettore migliorato Power Fx nella cartella power-fx-enhanced-connector/CdpHelpers/Protocol usando lo stesso spazio dei nomi Microsoft.PowerFx.Connectors. Vedere la tabella che descrive questi tipi.

Restituisce un elenco di set di dati

Questo endpoint nel servizio fornisce un catalogo leggero e in formato JSON di tutti i contenitori di dati di primo livello, come si potrebbe pensare in SQL come in esecuzione SELECT name FROM sys.databases. Recuperando solo i nomi e gli URL di accesso di ogni set di dati, i client possono individuare in modo dinamico le unità logiche (database) esposte dal servizio senza codificare gli identificatori. Questa progettazione non solo guida i flussi di lavoro di un’interfaccia utente o di generazione del codice basati sui metadati—consentendo agli utenti di selezionare un set di dati e quindi di approfondire nelle sue tabelle o viste—ma rispetta anche le regole di autorizzazione visualizzando solo i set di dati che il chiamante è autorizzato a vedere.

Implementare questa route nel controller per fornire dati sui set di dati disponibili:

GET $metadata.json/datasets

Restituire un'istanza datasetMetadata con le proprietà seguenti:

MetadataParameter

Questi metadati descrivono come le applicazioni client devono raccogliere, convalidare e codificare ogni parametro di query quando si chiama l'endpoint del set di dati. Impostando queste proprietà, assicurarsi di:

• Le interfacce utente possono visualizzare etichette chiare e tooltip per ogni parametro.
• I campi obbligatori vengono applicati in fase di progettazione, impedendo gli errori di runtime.
• I valori di input vengono convalidati rispetto al tipo dichiarato (stringa, integer, booleano e così via).
• La codifica URL viene applicata correttamente in modo che i caratteri speciali non interrompano la richiesta.

Impostare la proprietà DatasetMetadata.Parameters con un'istanza MetadataParameter che contiene queste proprietà:

MetadataDynamicValues

Questi metadati indicano alle applicazioni client come recuperare ed eseguire il rendering di un elenco attivo di opzioni valide per uno specifico parametro, abilitando elenchi a discesa, selettori o esperienze di ricerca in tempo reale nell'interfaccia utente. Impostando queste proprietà, assicurarsi di:

• I client conoscono l'endpoint o il percorso da chiamare per recuperare l'elenco corrente di valori
• Il payload della risposta viene analizzato correttamente per estrarre sia i valori sottostanti che i relativi titoli di visualizzazione
• Gli input dei parametri rimangono sincronizzati con le opzioni disponibili del servizio, riducendo gli errori e migliorando l'esperienza utente

Quando si imposta l'insieme DatasetMetadata.Parameters, impostare la proprietà XMsDynamicValues su un'istanza MetadataDynamicValues. Questa classe ha le proprietà stringa seguenti:

MetadataTabular

Questi metadati indicano al codice client come presentare e accedere ai dati tabulari del servizio. Impostando queste proprietà, assicurarsi che le interfacce utente visualizzino la terminologia e generino correttamente gli URL per il back-end specifico. Ad esempio, un servizio basato su SQL usa Table/Tables, mentre un connettore SharePoint usa List/Listse le impostazioni di codifica URL appropriate garantiscono che i percorsi delle risorse vengano compilati correttamente.

Impostare la proprietà DatasetMetadata.Tabular con un'istanza MetadataTabular che contiene queste proprietà stringa:

Restituire i nomi dei set di dati

Implementare questa route nel controller per fornire una raccolta di nomi per ogni set di dati:

GET /datasets

Implementare il metodo ITableProvider.GetDatasetsAsync per restituire un'istanza di DatasetResponse che ha una proprietà value con un array di istanze Item.

Ogni Item ha proprietà stringa Name e DisplayName.

Restituire i nomi delle tabelle

Implementare questa route nel controller per fornire una raccolta di nomi per le tabelle in un set di dati:

GET /datasets/{dataset}/tables

Implementare il ITableProvider.GetTablesAsync metodo per restituire un'istanza getTablesResponse . Questa classe dispone di una Value proprietà che restituisce un oggetto List<RawTablePoco>.

RawTablePoco ha le due proprietà stringa: Name e DisplayName.

Restituire le funzionalità di una tabella

Implementare questa route nel controller per restituire dati sulle funzionalità delle tabelle in un set di dati:

GET $metadata.json/datasets/{dataset}/tables/{tableName}

Implementare il metodo ITableProvider.GetTableAsync per restituire un RecordType e quindi convertire tale valore in GetTableResponse. Il metodo RecordType.ToTableResponse fornisce un esempio che mostra come. È necessario aggiungere il file CdpHelpers/RecordTypeExtensions.cs al progetto per usarlo.

GetTableResponse ha le proprietà seguenti:

Descrivere le funzionalità della tabella

La GetTableResponse.capabilities proprietà descrive le funzionalità di una tabella usando la classe CapabilitiesPoco .

La CapabilitiesPoco classe ha le proprietà seguenti per descrivere le funzionalità di una tabella.

Descrivere le funzionalità delle colonne di tabella

La GetTableResponse.schema proprietà descrive le funzionalità delle colonne di tabella usando la classe TableSchemaPoco .

La TableSchemaPoco classe ha le proprietà seguenti per descrivere le funzionalità di una tabella.

La classe Items ha le proprietà seguenti:

La classe ColumnInfo ha le proprietà seguenti:

La classe ColumnCapabilitiesPoco ha le proprietà seguenti:

Recuperare i valori delle colonne della tabella

Implementare questa route nel controller per restituire i valori delle colonne della tabella:

GET /datasets/{dataset}/tables/{tableName}/items

Implementare il ITableProvider.GetTableValueAsync metodo per restituire un oggetto TableValue e successivamente convertire tale valore in GetItemsResponse

GetItemsResponse ha una sola proprietà value, che è un List<Dictionary<string, object>> contenente le chiavi e i valori per le rispettive proprietà della tabella.

Transpiler

L'API Web di base ASP.NET creata deve consentire agli utenti di specificare parametri facoltativi della stringa di query OData quando viene usata questa route:

GET /datasets/{dataset}/tables/{tableName}/items

Il servizio deve supportare le funzionalità annunciate per la tabella e le colonne.

CdpSampleWebApi/Services/ODataQueryModel.cs è un contenitore di associazione di modelli leggero per un subset di opzioni di query di sistema OData. Il suo scopo:

• Associazione di modelli: ASP.NET popola automaticamente le relative proprietà dai parametri della stringa di query denominati $select, $filter, $tope $orderby grazie agli [FromQuery(Name="...")] attributi . Ad esempio: /entities?$select=id,name&$top=10.

• Solo acquisizione non elaborata: non analizza o convalida le espressioni OData; conserva il testo fornito dal client in modo che il codice downstream (ad esempio, un livello dati o un inoltro a un'altra API) possa decidere come interpretare, convalidare o inoltrarli.

• Creazione di pacchetti condizionali: ToStrDict() converte solo i valori forniti (e $top solo se > 0) in un dizionario, utile per:

  • Ricostruire o inoltrare le stesse opzioni di query OData a un altro servizio.
  • Registrazione/controllo.
  • Compilazione di una stringa di query a livello di codice.

• Scelte di denominazione/maiuscole/minuscole: top e orderby sono minuscole per rispecchiare esattamente senza alterazioni le parole chiave OData (avvisi di stile/analizzatore soppressi all'inizio del file). Selezionare e filtrare utilizzano PascalCase (stile misto), ma l'associazione funziona ancora grazie all'override esplicito del Nome.

• Ambito: omette intenzionalmente altre opzioni OData ($skip, $expand,$count, $searche altre), mantenendo la superficie minima. Potenziali miglioramenti (se necessario):

  • Rendere nullable top (int?) per distinguere tra "absent" e "explicit 0".
  • Aggiungere $skip, $expando altri parametri di query man mano che aumentano i requisiti.
  • Aggiungere la convalida o l'analisi (ad esempio: approvare i campi in $select, analisi delle espressioni per $filter).
  • Normalizzare la denominazione delle proprietà per la coerenza.

In breve, la classe ODataQueryModel è un semplice veicolo pass-through di opzioni di query OData selezionate, consentendo un accesso sicuro, chiaro e verificabile a tali opzioni all'interno delle azioni o dei servizi del controller.

Creare, aggiornare ed eliminare l'implementazione dell'operazione

Come si può notare, il protocollo del connettore avanzato descrive modi specifici per recuperare informazioni sulle funzionalità dei set di dati e recuperare i dati. La fase successiva consiste nel fornire funzionalità per aggiungere, modificare o rimuovere righe di tabella.

Creazione di righe

Il servizio deve usare il POST metodo HTTP con lo stesso percorso di risorsa usato per recuperare i record. Il payload viene inviato con il corpo della richiesta.

POST /datasets/{dataset}/tables/{tableName}/items

Aggiornamento ed eliminazione di righe

L'aggiornamento o l'eliminazione di righe richiede un modo per identificare il record da modificare o rimuovere. Questo dipende dalla natura dell'origine dati, ma è consigliabile usare gli stessi percorsi delle risorse. Per modificare un record, usare PATCH.

PATCH /datasets/{dataset}/tables/{tableName}/items/{primary key}

Per eliminare un record, usare DELETE.

DELETE /datasets/{dataset}/tables/{tableName}/items/{primary key}

Limitazioni

Di seguito sono riportate le aree in cui le funzionalità di dati tabulari comuni non sono abilitate usando il protocollo di connessione dati tabulare.

Relationships

Non è attualmente possibile modellare le relazioni tra tabelle.

I tipi di dati sono limitati

Funzioneranno solo i tipi supportati da Swagger 2.0.

Passaggi successivi

Scopri l'esempio di connettore potenziato.