Vytváření vylepšených datových konektorů (Preview)

[Tento článek představuje předběžnou dokumentaci a může se změnit.]

Pokud jsou data, která chcete použít s konektorem, strukturovaná pomocí tabulek nebo seznamů, vylepšený protokol konektoru vám pomůže snadněji poskytovat vysoce výkonný konektor podnikové úrovně. Vylepšené konektory slouží jako výkonný zdroj znalostí pro agenty a umožňují snadno vytvářet plátno aplikace v Power Apps a skládat logiku pomocí Power Automate.

Důležité

  • Toto je funkce ve verzi Preview.
  • Funkce ve verzi Preview nejsou určené pro produkční použití a můžou mít omezené funkce. Tyto funkce podléhají dodatečným podmínkám použití a jsou k dispozici před oficiálním vydáním, aby zákazníci mohli získat přednostní přístup a poskytnout zpětnou vazbu.

Akce a vylepšené konektory

Konektory vytvořené pomocí koncových bodů OpenAPI (swagger) se považují za akční konektory. OpenAPI poskytuje standardizovaný formát pro popis rozhraní HTTP API libovolné velikosti. Umožňuje explicitně definovat koncové body (cesty), podporované metody HTTP a schémata požadavků a odpovědí. Každá operace (kombinace cesty a metody) představuje specifickou volatelnou akci rozhraní API, takže je vhodná pro rozhraní API, která dodržují principy RESTful.

U strukturovaných zdrojů dat se jemně odstupňovaný ovládací prvek OpenAPI stává zátěží, protože tabulkové zdroje dat obvykle nejsou definovány koncovým bodem OpenAPI. Definice OpenAPI není vázána na metadata popisovaná strukturovaná data, takže se nepřizpůsobuje změnám, které přidávají nové tabulky, sloupce nebo relace ke zdroji dat. Konektor vygenerovaný pomocí statické definice OpenAPI nemůže tyto změny reprezentovat, dokud se znovu nevygeneruje.

Rozšířené konektory vyžadují koncový bod, který poskytuje informace, které popisují dynamickou sadu tabulek, schémat a možností. Tento článek popisuje protokol, který můžete implementovat k vytvoření webového rozhraní API ASP.NET Core na základě protokolu podobného protokolu OData místo OpenAPI. Tento protokol je určený pro tabulková data a používá funkce OData ke správě filtrování, řazení, stránkování a relací, které OpenAPI neposkytuje.

Poznámka:

Koncový bod popsaný v tomto článku má určité podobnosti s OData, ale neimplementuje skutečný protokol OData.

Strukturovaná data

Co znamená strukturovaná data? Data mohou být strukturována pomocí skutečných databázových tabulek, ale mohou také používat jinou terminologii, jako například "site" místo "database" a "list" místo "table". Klíčovým bodem je to, že data jsou strukturovaná do hierarchie prostředků takto:

  • Datová sada zveřejňuje kolekci tabulek.
  • Tabulka obsahuje řádky a sloupce, které obsahují data.
  • Položka představuje řádek tabulky.

Konektory používající tento model

Následuje několik vylepšených konektorů, které používají tento vzor:

Amazon Redshift

Apache Impala

Azure AI Search

Azure Data Lake Storage

Azure Database for MySQL

DB2

Dynamics 365 Business Central

Dynamics 365 Customer Insights

Dynamics NAV

Excel Online (pro podnikání)

Fin &Ops Apps (Dynamics 365)

Tabulky Google

Informix

Marketo MA (Preview)

Microsoft Dataverse

MySQL

Oracle Database

PostgreSQL

Datové toky Power Query

SalesForce

SAP OData

Služba SharePoint

Snowflake

SQL Server

Teradata

UserVoice

Zendesk

Jak to funguje

Protokol rozšířeného konektoru má tři hlavní části:

  • Koncové body schopností: Popis datových sad, tabulek a sloupců, ke kterým má konektor přístup a co můžou dělat.
  • Transpilátor: Převede požadavky ve stylu GET OData pro načtení dat pro zdroj dat. Tyto požadavky používají možnosti dotazu OData, jako jsou $filter, $select, $orderby, $sorta $top
  • Implementace operace CUD: Popisuje, jak provádět operace vytvoření, aktualizace a odstranění prostředků pro zdroj dat.

Na vysoké úrovni je potřeba implementovat následující proces:

  1. Vytvořte webové rozhraní API ASP.NET Core, které implementuje protokol rozšířeného konektoru.
  2. Nasaďte projekt webového rozhraní API ASP.NET Core do hostitelského prostředí podle vašeho výběru.
  3. Vytvořte vlastní konektor pomocí nástroje příkazového řádku Paconn.
  4. Nakonfigurujte ověřování.
  5. Sdílejte a otestujte konektor.

Poznámka:

Ukázka rozšířeného konektoru Power Fx je řešení sady Visual Studio publikované na GitHubu. Úložiště můžete naklonovat a použít zadaný projekt webového rozhraní API ASP.NET Core jako výchozí bod pro váš koncový bod.

Koncové body schopností

Vylepšený protokol konektoru závisí na implementaci pěti koncových bodů, které popisují možnosti vaší služby. Následující tabulka shrnuje tyto koncové body a obsahuje odkazy na části tohoto dokumentu, které vysvětlují, jak je implementovat.

Cesta Jak
GET $metadata.json/datasets Návratový seznam datových sad
GET /datasets Vrácení názvů datových sad
GET /datasets/{dataset}/tables Vrácení názvů tabulek
GET $metadata.json/datasets/{dataset}/tables/{tableName} Vrácení možností tabulky
GET /datasets/{dataset}/tables/{tableName}/items Načtení hodnot sloupců tabulky

ITableProvider – rozhraní

Následující rozhraní ITableProviderFactory a ITableProvider poskytují metody pro implementaci koncových bodů vylepšených schopností protokolu konektoru. Do složky projektu webového rozhraní API ASP.NET Core přidejte následující kód Services .

// 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);
}

Implementace webového rozhraní API ASP.NET Core s oddělením mezi front-endem (REST API) a back-endem (zprostředkovatelem zdroje dat). Back-end je abstrahován prostřednictvím ITableProvider rozhraní, které můžete implementovat pro připojení k libovolnému tabulkovému zdroji dat.

Použité třídy

V aplikaci webového rozhraní API ASP.NET Core, kterou vytvoříte, přidejte balíčky NuGet Microsoft.PowerFx.Connectors a Microsoft.PowerFx.Core, abyste měli přístup k typům, které se používají v ITableProvidersouboru RecordType a TableValue.

Některé další typy, které potřebujete, nejsou aktuálně součástí balíčků NuGet PowerFx. Najděte je ve složce Power Fx Enhanced Connector Samplepower-fx-enhanced-connector/CdpHelpers/Protocol při použití stejného Microsoft.PowerFx.Connectors oboru názvů. Podívejte se na tabulku popisující tyto typy.

Návratový seznam datových sad

Tento koncový bod ve službě poskytuje jednoduchý katalog ve formátu JSON, který zahrnuje všechny kontejnery dat nejvyšší úrovně – podobně jako operace v SQL, kterou byste mohli spustit pomocí SELECT name FROM sys.databases. Načtením pouze názvů a přístupových adres URL každé datové sady můžou klienti dynamicky zjišťovat, které logické jednotky (databáze) služba zveřejňuje bez pevného kódování identifikátorů. Tento návrh nejen řídí pracovní postupy uživatelského rozhraní nebo generování kódu, což uživatelům umožňuje vybrat datovou sadu a pak přejít k podrobnostem v tabulkách nebo zobrazeních, ale také respektuje autorizační pravidla tak, že vrátí jenom ty datové sady, které volající může zobrazit.

Implementujte tuto trasu ve vašem kontroleru a poskytněte data o dostupných datových sadách:

GET $metadata.json/datasets

Poznámka:

Tato trasa není součástí ITableProvider rozhraní.

Vrátí instanci DatasetMetadata , která má následující vlastnosti:

Název Typ Description
DatasetFormat String Popisuje formát řetězce datové sady. Například pro SQL může být {server},{database}.
IsDoubleEncoding logický Indikuje, zda je blob metadat kódován dvakrát (například datová část JSON zabalená jako řetězec kódovaný ve formátu JSON), což vyžaduje dva dekódovací kroky k načtení surových metadat.
Parametry IReadOnlyCollection<MetadataParameter> Viz MetadataParameter
Tabulkový MetadataTabular Podívejte se na MetadataTabular

Poznámka:

V ukázce rozšířeného konektoru Power Fx se cdpSampleWebApi/Controllers/CdpController.csDatasetMetadata přejmenuje na DatasetMetadataResponse. Tento název by byl konzistentní s názvy použitými v ITableProvider rozhraní, pokud by byl zahrnut.

MetadataParameter

Tato metadata popisují, jak by klientské aplikace při volání koncového bodu datové sady měly shromažďovat, ověřovat a kódovat každý parametr dotazu. Nastavením těchto vlastností zajistíte následující:

  • Uživatelská rozhraní dokážou zobrazit jasné názvy a nápovědy pro každý parametr.
  • Požadovaná pole se vynucují v době návrhu, což brání chybám za běhu.
  • Vstupní hodnoty se ověřují vůči deklarovanému typu (řetězec, celé číslo, logická hodnota atd.).
  • Kódování adresy URL je použito správně, takže speciální znaky neporuší požadavek.

Nastavte Vlastnost DatasetMetadata.Parameters s instancí MetadataParameter , která obsahuje tyto vlastnosti:

Název Typ Description
Description String Vysvětlení toho, co tento parametr představuje a jak ovlivňuje požadavek datové sady, je čitelné pro člověka. Například: tato hodnota je název serveru nebo název databáze v kontextu SQL.
název String Přesné názvy parametrů musí klienti zahrnout do řetězce dotazu nebo textu požadavku.
Povinné String Určuje, zda klient musí zadat tento parametr. Pokud je hodnota true, vynechání parametru způsobí chybu; Pokud je false, může se použít výchozí nebo náhradní chování.
Type String Datový typ hodnoty parametru, například string, integer, booleankterý klientům říká, jak ověřit a převést vstup před vydáním požadavku.
UrlEncoding String Určuje, jestli má být hodnota parametru zakódovaná jednou (single) nebo dvakrát (double).
XMsDynamicValues MetadataDynamicValues Viz MetadataDynamicValues
XMsSummary String Stručný souhrn použitý v popisech uživatelského rozhraní nebo dokumentaci, které uživatelům pomůžou pochopit účel tohoto parametru na první pohled.

MetadataDynamicValues

Tato metadata sdělují klientským aplikacím, jak načíst a vykreslit živý seznam platných možností pro daný parametr – povolení rozevíracích seznamů, výběrů nebo prostředí pro vyhledávání při psaní v uživatelském rozhraní. Nastavením těchto vlastností zajistíte následující:

  • Klienti vědí, který koncový bod nebo cestu mají volat za účelem načtení aktuálního seznamu hodnot.
  • Datová část odpovědi je správně analyzována, aby byly extrahovány jak základní hodnoty, tak jejich zobrazovatelné názvy.
  • Vstupy parametrů zůstanou synchronizované s dostupnými možnostmi vaší služby, snižují chyby a zlepšují uživatelské prostředí.

Při nastavování kolekce DatasetMetadata.Parameters nastavte vlastnost XMsDynamicValues na instanci MetadataDynamicValues. Tato třída má následující vlastnosti řetězce:

Název Description
Path Relativní adresa URL nebo cesta OData, kterou klienti používají k načtení seznamu dynamických hodnot (například: /datasets/{dataset name}/tables).
ValueCollection Název vlastnosti JSON v datové části odpovědi, která obsahuje pole položek (například: value nebo items).
ValuePath Cesta JSON (vzhledem k každé položce) pro extrahování skutečné hodnoty parametru (například: id nebo name.value).
Název hodnoty Cesta JSON (vzhledem ke každé položce) pro extrahování zobrazovaného textu určeného uživatelem pro každou možnost (například: displayName nebo title).

MetadataTabular

Tato metadata říkají klientskému kódu, jak prezentovat tabulková data vaší služby a přistupovat k němu. Nastavením těchto vlastností zajistíte, aby uživatelská rozhraní zobrazovala terminologii a vygenerovala adresy URL správně pro váš konkrétní back-end. Například služba založená na SQL by používala Table/Tables, zatímco SharePointový konektor by používal List/Lists; správné nastavení kódování adresy URL zaručuje správné sestavení cest k prostředkům.

Nastavte vlastnost DatasetMetadata.Tabular s instancí MetadataTabular, která obsahuje tyto řetězcové vlastnosti:

Název Description
DisplayName Zobrazovaný název datové sady Příklad: Database/WebSite.
Zdroj Může to být mru nebo singleton. Pokud má vaše služba jen jeden logický kontejner dat, stane /datasets se efektivně jediným koncovým bodem. Ve scénáři s více datovými sadami se možná budete chtít vyhnout tomu, abyste klienty zahltili všemi dostupnými datovými sadami najednou. Místo toho sledujete historii využití a vracíte /datasets pouze hlavní N datové sady seřazené podle času posledního přístupu (nebo poslední úpravy). Takto uživatelé nejprve uvidí seznam naposledy použitých položek (MRU), a poté mohou přejít na úplný seznam nebo povolit stránkování, pokud potřebují více podrobností.
TableDisplayName Zobrazovaný název tabulky podobně jako zdroj dat, například 'Tabulka' nebo 'Seznam'.
TablePluralName Název tabulky v množném čísle, podobně jako slovo 'zdroje dat', například 'Tabulky' nebo 'Seznamy'.
UrlEncoding Může být single nebo double.

Vrácení názvů datových sad

Implementujte tuto trasu do kontroleru, abyste mohli poskytnout kolekci názvů pro každou datovou sadu:

GET /datasets

Implementujte metodu ITableProvider.GetDatasetsAsync pro vrácení instance třídy DatasetResponse, která má value vlastnost s polem Item instance.

Každý Item má řetězec Name a DisplayName vlastnosti.

Poznámka:

Konektory nejsou potřeba k poskytování více datových sad. Pokud existuje pouze jedna datová sada, je konvence nastavit vlastnosti Name a DisplayName jedné položky na default.

Vrácení názvů tabulek

Implementujte tuto trasu do kontroleru, abyste mohli poskytnout kolekci názvů tabulek v datové sadě:

GET /datasets/{dataset}/tables

Implementujte metodu ITableProvider.GetTablesAsync pro vrácení GetTablesResponse instance. Tato třída má Value vlastnost, která vrací List<RawTablePoco>.

RawTablePoco má dvě vlastnosti řetězce: Name a DisplayName.

Poznámka:

"POCO" je zkratka pro "Plain Old CLR Objects" (Prosté staré objekty CLR) a slouží jako způsob formátování dat odpovědí v ASP.NET Core Web API.

Vrátit funkce tabulky

Implementujte tuto trasu v kontroleru, která vrací data o možnostech tabulek v datové sadě:

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

Implementujte metodu ITableProvider.GetTableAsync pro vrácení RecordType a pak tuto hodnotu převeďte na GetTableResponse. Metoda RecordType.ToTableResponse poskytuje příklad ukazující, jak. Soubor CdpHelpers/RecordTypeExtensions.cs byste měli přidat do projektu, abyste ho mohli použít.

GetTableResponse má následující vlastnosti:

Název Typ Description
capabilities CapabilitiesPoco Získá nebo nastaví možnosti tabulky, jako je podpora filtrování a řazení. Viz Popis funkcí tabulky
name String Získá nebo nastaví název tabulky.
permissions String Získá nebo nastaví oprávnění pro tabulku (například "read-write").
schema TableSchemaPoco Získá nebo nastaví schéma tabulky. Další informace najdete v tématu Popis možností sloupců tabulky.

Popis funkcí tabulky

Vlastnost GetTableResponse.capabilities popisuje schopnosti tabulky pomocí CapabilitiesPoco třídy.

Třída CapabilitiesPoco má následující vlastnosti, které popisují možnosti tabulky.

Název Typ Description
filterFunctionSupport string[] Získá nebo nastaví podporované funkce filtru (například: eq, and, or).
filterRestrictions Filter Třída Filter má logickou filterable vlastnost, která popisuje, zda tabulka podporuje vůbec jakékoli filtrování. Pokud filterable je hodnota true, nonFilterableProperties vlastnost obsahuje pole názvů sloupců tabulky, které nelze filtrovat.
isOnlyServerPagable bool Získá nebo nastaví hodnotu určující, zda je tabulka pouze stránkovatelná na serveru.
odataVersion int Získá nebo nastaví verzi OData (například: 3).
serverPagingOptions string[] Získá nebo nastaví možnosti stránkování serveru (například: top, skiptoken).
sortRestrictions Sort Třída Sort má logickou sortable vlastnost popisující, zda tabulka podporuje řazení vůbec. Pokud sortable je hodnota true, unsortableProperties vlastnost obsahuje pole názvů sloupců tabulky, které nelze seřadit.

Popis možností sloupců tabulky

Vlastnost GetTableResponse.schema popisuje možnosti sloupců tabulky pomocí Třídy TableSchemaPoco .

Poznámka:

Tato část popisuje sadu tříd, které mají jednoduché a složité vlastnosti. Vlastnosti se složitým typem vytvoří hierarchii, která popisuje možnosti sloupců pro tabulku.

TableSchemaPoco.items
 Items.properties
  ColumnInfo.capabilities
   ColumnCapabilitiesPoco

Třída TableSchemaPoco má následující vlastnosti, které popisují možnosti tabulky.

Název Typ Description
type řetězec Získá nebo nastaví typ schématu (výchozí hodnota je "pole").
items položek Získá nebo nastaví definici položek, která popisuje sloupce tabulky.

Třída Items má následující vlastnosti:

Název Typ Description
type řetězec Získá nebo nastaví typ položek (výchozí je "objekt").
properties Slovník<řetězec, ColumnInfo> Získá nebo nastaví slovník vlastností sloupců, jejichž klíčem je název sloupce.

Třída ColumnInfo má následující vlastnosti:

Název Typ Description
title řetězec Získá nebo nastaví název sloupce.
description řetězec Získá nebo nastaví popis sloupce.
type řetězec Získá nebo nastaví typ sloupce (například: integer, string).
sort řetězec Získá nebo nastaví možnosti řazení pro sloupec (například: asc, desc).
capabilities ColumnCapabilitiesPoco Získá nebo nastaví možnosti filtru pro sloupec.

Třída ColumnCapabilitiesPoco má následující vlastnosti:

Název Typ Description
filterFunctions řetězec[] Získá nebo nastaví podporované funkce filtru pro sloupec (například: eq, and, or).

Načtení hodnot sloupců tabulky

Implementujte tuto trasu v kontroleru, aby se vrátily hodnoty sloupců tabulky:

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

Implementujte metodu ITableProvider.GetTableValueAsync pro vrácení TableValue pak tuto hodnotu převést na GetItemsResponse

GetItemsResponse obsahuje pouze jednu value vlastnost, která obsahuje List<Dictionary<string, object>> klíče a hodnoty pro příslušné vlastnosti tabulky.

Transpilátor

Rozhraní ASP.NET Core Web API, které vytvoříte, musí uživatelům povolit, aby při použití této trasy zadali volitelné parametry řetězce dotazu OData:

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

Služba musí podporovat možnosti inzerované pro tabulku a sloupce.

CdpSampleWebApi/Services/ODataQueryModel.cs je jednoduchý kontejner vazby modelu pro podmnožinu možností systémového dotazu OData. Jeho účel:

  • Vazba modelu: ASP.NET automaticky naplní své vlastnosti z parametrů řetězce dotazu s názvem $select, $filter$top, a $orderby díky atributům[FromQuery(Name="...")]. Například: /entities?$select=id,name&$top=10.

  • Pouze nezpracované zachycení: Neanalybuje ani neověřuje výrazy OData; zachovává text zadaný klientem, takže podřízený kód (například datová vrstva nebo přenos do jiného rozhraní API) může rozhodnout, jak je interpretovat, ověřovat nebo předávat dál.

  • Podmíněné balení: ToStrDict() převede pouze zadané hodnoty (a $top pouze pokud > 0) do slovníku, což je užitečné pro:

    • Rekonstruování nebo předávání stejných možností dotazů OData do jiné služby
    • Protokolování a auditování
    • Vytvoření řetězce dotazu prostřednictvím kódu programu

  • Volby pojmenování a velikosti písmen: 'top' a 'orderby' jsou napsány malými písmeny, aby přesně odpovídaly klíčovým slovům OData (upozornění na styl/analyzátor byla potlačena na začátku souboru). Select a Filter používají PascalCase (smíšený styl), ale vazba stále funguje kvůli výslovnému přepsání Name.

  • Rozsah: Záměrně vynechává jiné možnosti OData ($skip, $expand,$count, $searcha další), přičemž povrch je minimální. Potenciální vylepšení (v případě potřeby):

    • Nastavit hodnotu jako nepřítomnou (int?), aby bylo možné rozlišit mezi "nepřítomný" a "explicitní 0".
    • Přidejte $skip, $expand nebo jiné parametry dotazu s rostoucími požadavky.
    • Přidejte ověření nebo parsování (například: schválení polí v $select, analýza výrazu pro $filter).
    • Normalizuje pojmenování vlastností pro konzistenci.

Stručně řečeno, ODataQueryModel třída je jednoduchý průchozí nosič vybraných možností dotazu OData, který umožňuje bezpečný, explicitní a testovatelný přístup k nim uvnitř akcí kontrolerů nebo služeb.

Vytvoření, aktualizace a odstranění implementace operace

Jak vidíte, vylepšený protokol konektoru popisuje konkrétní způsoby načtení informací o možnostech datových sad a načítání dat. Další fází je poskytnutí možností pro přidání, změnu nebo odebrání řádků tabulky.

Vytváření řádků

Vaše služba by měla používat POST metodu HTTP se stejnou cestou prostředku, která se používá k načtení záznamů. Datová část se odešle s textem požadavku.

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

Aktualizace a odstranění řádků

Aktualizace nebo odstranění řádků vyžaduje nějaký způsob, jak identifikovat záznam, který chcete změnit nebo odebrat. To závisí na povaze vašeho zdroje dat, ale je vhodné použít stejné cesty zdrojů. Chcete-li změnit záznam, použijte PATCH.

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

Pokud chcete odstranit záznam, použijte DELETE.

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

Omezení

Tady jsou oblasti, kde nejsou povolené běžné funkce tabulkových dat pomocí protokolu tabulkového datového připojení.

Relationships

V současné době není možné modelovat relace mezi tabulkami.

Datové typy jsou omezené

Budou fungovat jenom typy podporované Swaggerem 2.0.

Další kroky

Přečtěte si o ukázce rozšířeného konektoru.

Ukázka rozšířeného konektoru

  • Last updated on