From 35149f92a39b0eddbd7d139a81d1ee5d562571cd Mon Sep 17 00:00:00 2001 From: VP Date: Tue, 9 Feb 2021 22:53:15 +0100 Subject: [PATCH] Add README.md --- v2/HlidacStatu.Api.V2.Dataset/README.md | 202 ++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 v2/HlidacStatu.Api.V2.Dataset/README.md diff --git a/v2/HlidacStatu.Api.V2.Dataset/README.md b/v2/HlidacStatu.Api.V2.Dataset/README.md new file mode 100644 index 0000000..06f5a49 --- /dev/null +++ b/v2/HlidacStatu.Api.V2.Dataset/README.md @@ -0,0 +1,202 @@ +# Knihovna Dataset (nástupce knihovny DatasetConnector) + +[![NuGet](https://img.shields.io/nuget/dt/HlidacStatu.Api.V2.Dataset.svg)](https://www.nuget.org/packages/HlidacStatu.Api.V2.Dataset) +[![NuGet](https://img.shields.io/nuget/v/HlidacStatu.Api.V2.Dataset.svg)](https://www.nuget.org/packages/HlidacStatu.Api.V2.Dataset) + +Knihovna pro .NET Framework napsaná ve .NET Standardu 2.0, .NET Framework 4.7.2 a .NET Framework 4.8 umožňující snadnou práci s datasety Hlídače státu. Dostupná také jako [NuGet balíček](https://www.nuget.org/packages/HlidacStatu.Api.V2.Dataset). + +## Použití knihovny + + +### Příprava datasetu +Pro přípravu datasetu je potřeba: + +- znát váš `ApiToken`, který lze získat po přihlášení na stránkách [Hlídače Státu - API pro vývojáře](https://www.hlidacstatu.cz/api/v1/Index) +```csharp +string apiToken = "Token 0000000a00b000000c00000"; +``` + +- je možno si zvolit jedinečný identifikátor datasetu, pokud nebude zvolen, Hlídač státu jej automaticky odvodí z názvu datasetu +```csharp +string dataSetId = "osoby-kontrolovane-nku"; +``` + +- vytvořit třídu reprezentující jednotlivý záznam (řádek) datasetu, tato třída musí obsahovat vlastnost (property) pojmenovanou `Id` + +```csharp + class DataSetItem + { + // musí být + public string Id { get; set; } + + // další nepovinné vlastnosti + public string KontrolovanaOsoba { get; set; } + public string ICO { get; set; } + } +``` + +- vytvořit instanci dvourozměrného pole `string[,]`, které slouží pro nastavení možností řazení zobrazených záznamů z datasetu +```csharp + orderList = new string[,] { + { "Kontrolovaná osoba", "KontrolovanaOsoba.keyword" }, + { "Ico", "ICO.keyword" }, + { "Okres", "Okres.keyword" }, + { "Kontrolní akce", "KontrolniAkce.keyword"}, + }; +``` +- vytvořit instanci třídy `ClassicSearchResultTemplate`, která slouží jako šablona pro zobrazení více záznamů z datasetu (tabulkové zobrazení) +```csharp +searchTemplate = new ClassicTemplate.ClassicSearchResultTemplate() + .AddColumn("Detail", @"Detail") + .AddColumn("Kontrolovaná osoba dle NKÚ", "{{item.KontrolovanaOsoba}}") + .AddColumn("Kontrolovaná osoba dle obchodního rejstříku", "{{fn_RenderCompanyWithLink(item.ICO)}}") + .AddColumn("IČ", "{{item.ICO}}") + .AddColumn("Okres", "{{item.Okres}}"); +``` +- vytvořit instanci třídy `ClassicDetailTemplate`, která slouží jako šablona pro detailní zobrazení jednoho záznamu z datasetu +```csharp +detailTemplate = new ClassicTemplate.ClassicDetailTemplate() + .AddColumn("Kontrolovaná osoba dle NKÚ", "{{item.KontrolovanaOsoba}}") + .AddColumn("Kontrolovaná osoba dle obchodního rejstříku", "{{fn_RenderCompanyWithLink(item.ICO)}}") + .AddColumn("IČ", "{{item.ICO}}") + .AddColumn("Okres", "{{item.Okres}}") + .AddColumn("Kontrolní akce", @"{{item.KontrolniAkce}}"); +``` +- vytvořit instanci třídy `Registration`, která slouží pro nastavení parametrů datasetu, není nutno ji vytvářet, pokud se využije přetížení konstruktoru, + které má podobné možnosti, ale chybí možnost nastavení výchozího řazení zobrazených záznamů z datasetu (vlastnost `DefaultOrderBy`) + a také je potřeba nastavit vlastnost `JsonSchema` +```csharp +registration = new Registration() + { + Name = "Osoby kontrolované NKÚ", + + // pokud není vyplněno, Hlídač státu Id automaticky odvodí z názvu datasetu + DatasetId = dataSetId, + OrigUrl = @"https://data.nku.cz/download/kontrolovane-osoby/kontrolovane_osoby.csv", + Description = "Osoby kontrolované NKÚ", + SourcecodeUrl = string.Empty, + Betaversion = true, + AllowWriteAccess = false, + OrderList = orderList, + SearchResultTemplate = searchTemplate, + DetailTemplate = detailTemplate, + Hidden = false, + DefaultOrderBy = "KontrolovanaOsoba.keyword asc", + + // je také nutno nastavit, dataset tuto vlastnost nenastaví automaticky + JsonSchema = new JSchemaGenerator().Generate(typeof(DataSetItem)).ToString() + }; +``` + + +### Založení datasetu na serveru + +Založení datasetu na serveru se provede zavoláním statické metody `CreateDataset` třídy [Dataset](v2/HlidacStatu.Api.V2.Dataset/Typed/Dataset.cs) +a předáním potřebných parametrů z předchozí přípravy datasetu. Generickým parametrem je vaše třída reprezentující jednotlivý záznam vytvořená v prvním kroku. + +```csharp +Dataset dataSetInstance = Dataset.CreateDataset(apiToken, registration); +``` +Pokud již vytvářený dataset existuje, je vyvolána výjimka `ApiException`. + +### Ověření existence datasetu na serveru + +Ověření existence datasetu je možné zachycením výjimky např. +```csharp + public Dataset GetDataSetInstance() + { + Dataset dataSetInstance; + try + { + dataSetInstance = Dataset.OpenDataset(apiToken, dataSetId); + } + catch (ApiException) + { + Console.WriteLine($"Dataset s požadovaným ID {dataSetId} neexistuje, vytvářím nový"); + dataSetInstance = Dataset.CreateDataset(apiToken, registration); + Console.WriteLine($"Dataset vytvořen, přidělené ID datasetu: {dataSetInstance.DatasetId}"); + } + return dataSetInstance; + } +``` + +### Otevření přístupu k datasetu, který již existuje na serveru + +Pro přístup k datasetu potřebujeme instanci datasetu, kterou získáme zavoláním statické metody `OpenDataset` třídy [Dataset](v2/HlidacStatu.Api.V2.Dataset/Typed/Dataset.cs) +a předáním potřebných parametrů. Generickým parametrem je vaše třída reprezentující jednotlivý záznam z prvního kroku. + +```csharp +Dataset dataSetInstance = Dataset.OpenDataset(apiToken, dataSetId); +``` + + +### Změna definice datasetu na serveru + +Existující dataset lze upravit kromě hodnot `DatasetId` a `JsonSchema` (pro jejich změnu je nutné nejprve dataset smazat a následně vytvořit nový). Úprava datasetu se provede voláním instanční metody `UpdateRegistration`, která jako parametr přijímá registraci datasetu. + +```csharp +dataSetInstance.UpdateRegistration(registration); +``` + +Pokud upravovaný dataset neexistuje, je vyvolána výjimka. + + +### Přidání jednotlivého záznamu, nebo změna jednotlivého záznamu v datasetu na serveru + +Záznam je možno přidat voláním instanční metody `AddOrUpdateItem`, které se jako parametr předá přidávaný záznam +a nastavení jaká akce se vyvolá, pokud již záznam v datasetu existuje: + +* `skip` - pokud záznam existuje, nic se na něm nezmění, přidávaný záznam bude přeskočen +* `merge` - snaží se spojit data z obou záznamů +* `rewrite` - záznam v datasetu bude přepsán + +V případě úspěšného přidání záznamu je vráceno `Id` záznamu, jinak je vyvolána výjimka. +```csharp +var recordId = dataSetInstance.AddOrUpdateItem(dataSetItem, ItemInsertMode.rewrite); +``` + +### Přidání většího množství záznamů, nebo změna většího množství záznamů v datasetu na serveru + +Větší množství záznamů je možno přidat voláním instanční metody `AddOrRewriteItems`, které se jako parametr předají přidávané záznamy. +Pokud záznam s daným Id již existuje bude přepsán. +V případě úspěšného přidání záznamů jsou vrácena `Id` záznamů, jinak je vyvolána výjimka. + +```csharp +var recordId = dataSetInstance.AddOrRewriteItems(dataSetItems); +``` + +### Ověření přítomnosti záznamu v datasetu na serveru + +Ověření se provede voláním instanční metody `ItemExists`, které se jako parametr předá identifikátor záznamu. Vrací `true/false`. + +```csharp +bool exists = dataSetInstance.ItemExists(itemId); +``` + +### Získání záznamu z datasetu na serveru + +Získání záznamu z datasetu se provede voláním instanční metody `GetItem`, které se jako parametr předá identifikátor záznamu. +V případě úspěchu je navrácen požadovaný záznam, jinak je vyvolána výjimka `ApiException`. + +```csharp +var item = dataSetInstance.GetItem(itemId); +``` + +### Bezpečné získání záznamu z datasetu na serveru + +Získání záznamu z datasetu se provede voláním instanční metody `GetItemSafe`, které se jako parametr předá identifikátor záznamu. +V případě úspěchu je navrácen požadovaný záznam, jinak je vráceno `null`. + +```csharp +var item = dataSetInstance.GetItemSafe(itemId); +``` + +### Vyhledávání v datasetu na serveru + +V datasetu je možno vyhledávat voláním instanční metody `Search`, které se jako parametr předá vyhledávaná položka, stránka výsledků a volitelné parametry týkající se řazení záznamů . +V případě úspěchu je navrácen požadovaný záznam, jinak prázdná kolekce; + +```csharp +var item = dataSetInstance.Search("Praha",1); +``` +