Cvičení – čtení dat se vstupními vazbami

20 min

Představte si, že chcete vytvořit vyhledávací službu záložek. Zpočátku je vaše služba určená jen pro čtení. Pokud uživatelé chtějí najít položku, odešlou požadavek s ID položky a naše funkce vrátí adresu URL. Následující vývojový diagram znázorňuje logický tok.

Když uživatel odešle požadavek s textem, funkce najít záložku se pokusí najít položku v databázi, která obsahuje záložku s textem jako klíč nebo ID. Systém vrátí výsledek, který určuje, jestli jste položku našli.

Když funkce Azure obdrží požadavek s ID záložky, nejprve zkontroluje, jestli je požadavek platný. Pokud ne, vygeneruje se chybová odpověď. Pokud je požadavek platný, funkce zkontroluje, jestli v databázi Azure Cosmos DB existuje ID záložky. Pokud neexistuje, vygeneruje se chybová odpověď. Pokud je ID záložky nalezeno, vygeneruje se úspěšná odpověď.

Přitom potřebujete někam ukládat data. V předchozím vývojovém diagramu je úložiště dat instancí služby Azure Cosmos DB. Jak se ale připojíte k databázi z funkce a načtete data? Ve světě funkcí pro tento účel nakonfigurujete vstupní vazbu. Konfigurace vstupní vazby prostřednictvím webu Azure Portal je jednoduchá. Jak vidíte krátce, nemusíte psát kód ani otevírat připojení k úložišti. O tyto věci se za vás postará modul runtime a vazby Azure Functions.

Vytvoření účtu služby Azure Cosmos DB

Poznámka:

Toto cvičení není určeno jako kurz ve službě Azure Cosmos DB. Pokud se chcete dozvědět více, podívejte se na úplný studijní program o službě Azure Cosmos DB na konci tohoto modulu.

Vytvoření účtu databáze

Účet databáze je kontejner pro správu jedné nebo více databází. Než budeme moct vytvořit databázi, musíme nejprve vytvořit účet databáze.

V nabídce prostředků webu Azure Portal nebo na domovské stránce vyberte Vytvořit prostředek. Zobrazí se podokno Vytvořit prostředek .
V nabídce Vytvořit prostředek vyberte Databáze a pak vyhledejte a vyberte Azure Cosmos DB. Zobrazí se podokno, které rozhraní API nejlépe vyhovuje vašim úlohám?
V možnosti Azure Cosmos DB for NoSQL vyberte Vytvořit , abychom mohli vytvořit trigger Služby Cosmos DB a vstupní a výstupní vazby. Zobrazí se podokno Vytvořit účet služby Azure Cosmos DB – Azure Cosmos DB for NoSQL .

Na kartě Základy zadejte pro každé nastavení následující hodnoty.

Nastavení	Hodnota	Popis
Podrobnosti projektu
Předplatné	Předplatné Concierge	Předplatné Azure, které funguje s prostředky v sandboxu.
Skupina prostředků	V rozevíracím seznamu vyberte [název skupiny prostředků sandboxu]	Skupina prostředků pro váš sandbox.
Podrobnosti o instanci
Název účtu	`globally unique name`	Zadejte jedinečný, ale identifikovatelný název účtu služby Azure Cosmos DB. `documents.azure.com` je připojen k zadanému názvu. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Umístění	`region`	Vyberte nejbližší oblast.

Přijměte výchozí hodnoty pro zbývající nastavení a výběrem možnosti Zkontrolovat a vytvořit ověřte svůj vstup. Zobrazí se oznámení o úspěšném ověření.
Výběrem možnosti Vytvořit zřídíte a nasadíte účet databáze.
Nasazení může chvíli trvat. Než budete pokračovat, počkejte na úspěšnou zprávu nasazení v centru oznámení.
Výběrem možnosti Přejít k prostředku přejděte na databázový účet na portálu. Zobrazí se podokno Rychlý start pro účet služby Azure Cosmos DB.

Dále přidáme kontejner a pak přidáme databázi do účtu služby Azure Cosmos DB.

Přidání kontejneru

Ve službě Azure Cosmos DB se kontejner používá k ukládání různých uživatelem generovaných entit, označovaných také jako položky. Vytvoříme kontejner s názvem Záložky.

K vytvoření databáze a kontejneru použijeme nástroj Průzkumník dat.

V nabídce účtu služby Azure Cosmos DB vyberte Průzkumník dat. Zobrazí se podokno Průzkumník dat pro váš účet Cosmos DB.
Vyberte pole Nový kontejner . Zobrazí se podokno Nový kontejner . Možná ho budete muset posunout, abyste ho viděli.

Pro každé nastavení zadejte následující hodnoty.

Nastavení	Hodnota	Popis
ID databáze	Vyberte Vytvořit nový a jako ID databáze zadejte func-io-learn-db .	Názvy databází můžou mít délku 1 až 255 znaků a nesmí obsahovat znak /, \, #, ?nebo koncovou mezeru. V tomto modulu můžete zadat cokoli, ale v tomto modulu používáme func-io-learn-db .
Maximální počet RU/s databáze	4000	Přijměte výchozí propustnost 4 000 jednotek žádostí za sekundu (RU/s). Pokud chcete snížit latenci, můžete výkon vertikálně navýšit později.
ID kontejneru	Bookmarks	Pro ID kontejnerů platí stejné požadavky ohledně použitých znaků jako pro názvy databází. V tomto modulu používáme záložky .
Klíč oddílu	/id	Klíč oddílu určuje, jak se mají dokumenty v kolekcích služby Azure Cosmos DB distribuovat napříč logickými oddíly dat. Nastavení klíče oddílu zde používáme jako pohodlí, protože se v tomto modulu nezajímáme o výkon databáze. Další informace o strategiích klíčů oddílů služby Azure Cosmos DB najdete v modulech Microsoft Learn Azure Cosmos DB.

Přijměte výchozí hodnoty pro všechna ostatní nastavení.

Posuňte se do dolní části podokna a vyberte OK. Počkejte několik minut, než se databáze a kontejner sestaví.

Po dokončení zobrazí Průzkumník dat v rozhraní API NOSQL func-io-learn-db.
Vyberte func-io-learn-db a rozbalte ji. Všimněte si, že vaše databáze func-io-learn-db obsahuje několik podřízených členů, včetně škálování a záložek.
Rozbalte kontejner Bookmarks a všimněte si, že je předem vyplněný několika podřízenými členy.

V dalším úkolu přidáte do kontejneru Bookmarks nějaká data, označovaná také jako položky.

Přidání testovacích dat

Chcete přidat data do kontejneru Záložek . Pomocí Průzkumníka dat uložte adresu URL a ID pro každou položku.

Rozbalte databázi func-io-learn-db a kontejner Záložek a pak vyberte Položky. Zobrazí se karta Položky .
Na panelu příkazů vyberte Nová položka.

Nahraďte výchozí kód nové položky následujícím kódem JSON.

{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}

Na panelu příkazů vyberte Uložit.

Všimněte si, že se zobrazí více vlastností než dva řádky, které jsme přidali. Všechny začínají podtržením (_rid, _self, _etag, _attachments, _ts). Tyto vlastnosti popsané v následující tabulce jsou systémem generovány, aby pomohly spravovat položky, které přidáte do kontejneru.

Vlastnost	Popis
`_rid`	ID prostředku je jedinečný identifikátor, který je také hierarchický podle zásobníku prostředků v modelu prostředků. Používá se interně k umístění a navigaci prostředku položky.
`_self`	Jedinečný adresovatelný identifikátor URI prostředku
`_etag`	Požadováno pro řízení optimistické souběžnosti.
`_attachments`	Adresovatelná cesta pro prostředek příloh.
`_ts`	Časové razítko poslední aktualizace tohoto prostředku

Pojďme do kontejneru Bookmarks přidat několik dalších položek. Na panelu příkazů vyberte Nová položka. Vytvořte čtyři další položky s následujícím obsahem. Přidejte položky tak , že vyberete Možnost Nová položka a potom vyberete Uložit po zkopírování a vložení každé nové položky. Všimněte si, jak se jednotlivé položky přidají do seznamu položek.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
Po zadání dat záložek by měl kontejner vypadat jako na následujícím obrázku.

Kontejner Záložek má pět položek. Pokud v tomto scénáři dorazí požadavek s id=docs, vyhledá toto ID v kontejneru Bookmarks a vrátí adresu URL https://learn.microsoft.com/azure. Pojďme vytvořit funkci Azure, která vyhledá hodnoty v kontejneru Bookmarks.

Vytvoření vlastní funkce

Přejděte do aplikace funkcí, kterou jste vytvořili v předchozí lekci. V nabídce prostředků vyberte Domů a v části Poslední prostředky by se měla zobrazit vaše aplikace funkcí (typ rovná se function App). Vyberte svou aplikaci funkcí. Zobrazí se podokno Aplikace funkcí.
Na kartě Funkce na stránce Přehled byste měli mít jednu funkci HttpTrigger1.
Pojďme vytvořit další funkci. Na kartě Funkce vyberte Vytvořit. Zobrazí se podokno Vytvořit funkci se seznamem šablon podporovaných triggerů.
V části Vybrat šablonu vyberte trigger HTTP a pak vyberte Další.
Přijměte všechna výchozí nastavení a výběrem možnosti Vytvořit vytvořte funkci.

Zobrazí se podokno Přehled funkce HttpTrigger2 .

Ověření funkce

To, co jsme zatím udělali, můžete ověřit otestováním nové funkce.

Na panelu příkazů vyberte Získat adresu URL funkce. Zobrazí se dialogové okno Získat adresu URL funkce.
V rozevíracím seznamu vyberte výchozí (funkční klíč) a pak vyberte ikonu Kopírovat do schránky a vyberte OK.
Vložte adresu URL funkce, kterou jste zkopírovali, do adresního řádku nové karty prohlížeče. Připojte hodnotu &name=<your name> řetězce dotazu na konec adresy URL, nahraďte <your name> svým jménem a stiskněte Enter. Funkce Azure by měla v prohlížeči vrátit přizpůsobenou odpověď.

Když teď máme naši funkci kosterní funkce, pojďme se zaměřit na čtení dat z vaší služby Azure Cosmos DB nebo v našem scénáři z kontejneru Záložek .

Přidání vstupní vazby Azure Cosmos DB

Aby bylo možné číst data z databáze, musíte definovat vstupní vazbu. Jak vidíte tady, můžete nakonfigurovat vazbu, která může komunikovat s databází během několika kroků.

Na webu Azure Portal v nabídce funkce HttpTrigger2 na levé straně vyberte Integrace. Zobrazí se podokno Integrace funkce.

Použili jste šablonu, která vytvořila požadavek triggeru HTTP s výstupní vazbou HTTP. Pojďme přidat vstupní vazbu Azure Cosmos DB.
V poli Vstupy vyberte Přidat vstup. Zobrazí se podokno Vytvořit vstup .
V rozevíracím seznamu Typ vazby vyberte Azure Cosmos DB.
V části podrobností služby Azure Cosmos DB v části Nastavení připojení účtu Cosmos DB vyberte odkaz Nový. Zobrazí se dialogové okno Nové připojení ke službě Cosmos DB.

Pokud se zobrazí zpráva s výzvou k instalaci rozšíření Microsoft.Azure.WebJobs.Extensions.CosmosDB, vyberte Nainstalovat a počkejte na dokončení.
Azure ve výchozím nastavení rozpozná účet služby Azure Cosmos DB, který jste vytvořili dříve. Vyberte OK a nastavte připojení k databázi. Je nakonfigurováno nové připojení k databázovému účtu a zobrazí se v poli připojení účtu Cosmos DB.

Chceme vyhledat záložku s konkrétním ID, takže pojďme svázat ID, které dostaneme v řetězci dotazu na vazbu.

Pojďme dokončit nastavení v podokně Vytvořit vstup . Pro každé nastavení zadejte následující hodnoty. Další informace o účelu každého nastavení získáte výběrem ikony informací v tomto poli.

Nastavení	Hodnota	Popis
Název parametru dokumentu	`bookmark`	Název používaný k identifikaci této vazby v kódu.
Název databáze	`func-io-learn-db`	Databáze, se kterou se má pracovat. Tato hodnota je název databáze, který jsme nastavili.
Název kolekce	`Bookmarks`	Kolekce, ze které čteme data. Toto nastavení bylo definováno.
ID dokumentu	`id`	Přidejte ID dokumentu, které jsme definovali při vytváření kontejneru Azure Cosmos DB bookmarks .
Klíč oddílu	`/id`	Přidejte klíč oddílu, který jste definovali při vytváření kolekce Azure Cosmos DB Bookmarks . Klíč, který zde zadáte (uvedený ve formátu vstupní vazby `<key>`), se musí shodovat s klíčem v kolekci.
Dotaz SQL (nepovinný)	prázdné	Načítáte jenom jeden dokument najednou na základě ID. Filtrování pomocí nastavení ID dokumentu je tedy lepší než použití dotazu SQL v této instanci. Mohli byste sestavit dotaz SQL, který by vrátil jednu položku (`SELECT * from b where b.ID = id`). Tento dotaz by sice vrátil vždy jeden dokument, ale vrátil by ho v kolekci dokumentů. Kód by také musel zbytečně pracovat s kolekcí. Přístup založený na dotazu SQL použijte, když budete chtít načíst více dokumentů.

Abychom si vysvětlili, proč tato nastavení používáme, chceme vyhledat záložku s určitým ID, takže jsme svázali ID dokumentu, které naše funkce přijímá v řetězci dotazu na vstupní vazbu. Této syntaxi říkáme vazbový výraz. Funkce je aktivována požadavkem HTTP, který používá řetězec dotazu k určení ID, které se má vyhledat. Vzhledem k tomu, že ID jsou v naší kolekci jedinečná, vrátí vazba buď 0 (nenalezena), nebo 1 (nalezené) dokumenty.

Chcete-li uložit tuto konfiguraci vstupní vazby, vyberte OK.

Aktualizace implementace funkce

Teď, když je vaše vazba definovaná, můžete ji použít ve své funkci. K implementaci vazby, kterou jste vytvořili, musíte provést dvě změny:

Upravte kód implementace specifické pro vaši funkci. Musí určit, jestli byl v databázi nalezen dokument, který odpovídá ID předané funkci.
Upravte kód implementace JSON vaší funkce tak, aby přijímal parametr předaný v řetězci dotazu.

Úprava kódu implementace JavaScriptu vaší funkce

V nabídce Funkce pro funkci HttpTrigger2 vyberte Code + Test. Zobrazí se podokno Code + Test pro vaši funkci HttpTrigger2 .

Nahraďte veškerý kód v souboru index.js následujícím kódem.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

Na panelu příkazů vyberte Uložit. V rozevíracím seznamu v horní části podokna protokolů vyberte protokoly systému souborů (ve výchozím nastavení se zobrazí protokoly Přehledy aplikací). Zobrazí se podokno Protokoly se zobrazenými informacemi Connected!

Pojďme se podívat, co tento kód dělá.

Příchozí požadavek HTTP aktivuje funkci a parametr dotazu id je předán vstupní vazbě Azure Cosmos DB.
Pokud databáze najde dokument, který odpovídá tomuto ID, bookmark nastaví se parametr na umístěný dokument.

V tomto příkladu kód vytvoří odpověď, která obsahuje hodnotu ADRESY URL, která se nachází v odpovídajícím dokumentu databáze.
Pokud se nenajde žádný dokument odpovídající tomuto klíči, požadavek odpoví datovou částí a stavovým kódem, který uživateli řekne špatné zprávy.

Úprava kódu implementace JSON vaší funkce

V rozevíracím seznamu v <functionapp> \ HttpTrigger2 \ cestě vyberte function.json.

Upravte hodnoty tak idpartitionKey, aby přijímaly parametr .{id} Kód function.json by měl vypadat podobně jako v následujícím příkladu, kde your-database se nahradí názvem vaší databáze Cosmos DB.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "connection": "your-database_DOCUMENTDB",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

Na panelu příkazů vyberte Uložit.

Úprava kódu implementace PowerShellu vaší funkce

V nabídce Funkce pro funkci HttpTrigger2 vyberte Code + Test. Zobrazí se podokno Kód + Test pro vaši funkci HttpTrigger2 zobrazující run.ps1 soubor.

Nahraďte veškerý kód v run.ps1 souboru následujícím kódem.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
})

Na panelu příkazů vyberte Uložit. V rozevíracím seznamu v horní části podokna protokolů vyberte protokoly systému souborů (ve výchozím nastavení se zobrazí protokoly Přehledy aplikací). Zobrazí se podokno Protokoly se zobrazenými informacemi Connected!

Pojďme se podívat, co tento kód dělá.

Příchozí požadavek HTTP aktivuje funkci a parametr dotazu id je předán vstupní vazbě Azure Cosmos DB.
Pokud databáze najde dokument, který odpovídá tomuto ID, bookmark nastaví se parametr na umístěný dokument.

V tomto příkladu kód vytvoří odpověď, která obsahuje hodnotu ADRESY URL, která se nachází v odpovídajícím dokumentu databáze.
Pokud se nenajde žádný dokument odpovídající tomuto klíči, požadavek odpoví datovou částí a stavovým kódem, který uživateli řekne špatné zprávy.

Úprava kódu implementace JSON vaší funkce

V rozevíracím seznamu v <functionapp> \ HttpTrigger2 \ cestě vyberte function.json.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

Na panelu příkazů vyberte Uložit.

Vyzkoušejte si to.

Už byste měli být v podokně Code + Test pro funkci HttpTrigger2 .
Na panelu příkazů vyberte Získat adresu URL funkce. Zobrazí se dialogové okno Získat adresu URL funkce.
V rozevíracím seznamu Klíč vyberte výchozí hodnotu v části Funkční klíč a pak na konci adresy URL vyberte ikonu Kopírovat do schránky .
Vložte klíč funkce, který jste zkopírovali do adresního řádku nové karty prohlížeče, a pak na konec adresy URL přidejte hodnotu &id=docs řetězce dotazu. Výsledná adresa URL by měla vypadat podobně jako v následujícím příkladu:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Stisknutím klávesy Enter žádost spusťte. Odpověď vrácená vaší funkcí by měla vypadat podobně jako v následujícím příkladu.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Nahraďte &id=docs stisknutím klávesy &id=missingEnter a sledujte odpověď. Definovali jsme pět záložek a vytvořili smysluplnou chybovou odpověď, pokud požadovaná záložka neexistuje.

V této lekci jste ručně vytvořili první vstupní vazbu na čtení z databáze Azure Cosmos DB. Rozsah kódu, který jste museli napsat pro vyhledání v databázi a čtení dat, byl díky využití vazeb minimální. Většinu práce jste provedli deklarativní konfigurací vazby a platforma se postarala o zbytek.

V další lekci přidáte do kolekce záložek další data prostřednictvím výstupní vazby Azure Cosmos DB.

Pokračovat

Cvičení – čtení dat se vstupními vazbami

Vytvoření účtu služby Azure Cosmos DB

Vytvoření účtu databáze

Přidání kontejneru

Přidání testovacích dat

Vytvoření vlastní funkce

Ověření funkce

Přidání vstupní vazby Azure Cosmos DB

Aktualizace implementace funkce

Úprava kódu implementace JavaScriptu vaší funkce

Úprava kódu implementace JSON vaší funkce

Úprava kódu implementace PowerShellu vaší funkce

Úprava kódu implementace JSON vaší funkce

Vyzkoušejte si to.

Váš názor