Cvičení: Zápis dat s výstupními vazbami

15 min

V předchozím cvičení jsme implementovali scénář vyhledávání záložek v databázi Azure Cosmos DB. Nakonfigurovali jsme vstupní vazbu, aby četla data z naší kolekce záložek. Ale můžeme toho udělat více. Pojďme scénář rozvinout, aby zahrnoval i zápis. Podívejme se na následující vývojový diagram:

Diagram rozhodovacího toku znázorňující proces přidání záložky do back-endu služby Azure Cosmos DB a vrácení odpovědi

V tomto scénáři obdržíme žádosti o přidání záložek do naší kolekce. Požadavky předávají požadovaný klíč nebo ID spolu s adresou URL záložky. Jak vidíte v vývojovém diagramu, odpovíme chybou, pokud klíč už v našem back-endu existuje.

Pokud klíč předaný nám nebyl nalezen, přidáme do databáze novou záložku. Tady bychom se mohli zastavit, ale pojďme ještě o kus dál.

Vidíte další krok ve vývojovém diagramu? Zatím jsme s daty, která dostáváme z hlediska zpracování, moc neprovedli. Co nám přijde, prostě zapíšeme do databáze. Ve skutečném řešení bychom ale data pravděpodobně nějakým způsobem zpracovávali. Můžeme provést veškeré zpracování ve stejné funkci, ale v tomto cvičení ukážeme vzor, který přesměruje další zpracování na jinou komponentu nebo část obchodní logiky.

Jaký je dobrý příklad snižování zátěže práce ve scénáři záložek? Co kdybychom odeslali novou záložku do služby generování kódu QR? Tato služba pak vygeneruje kód QR pro adresu URL, uloží obrázek do blob Storage a přidá adresu obrázku QR do položky v naší kolekci záložek. Volání služby pro vygenerování obrázku QR je časově náročné. Takže místo čekání na výsledek předáme úkol funkci a necháme ji dokončit asynchronně.

Stejně jako Azure Functions podporuje vstupní vazby pro různé zdroje integrace, má také sadu šablon pro výstupní vazby, které usnadňují zápis dat do zdrojů dat. Výstupní vazby jsou konfigurovány také v souboru function.json. Jak vidíte v tomto cvičení, můžeme nakonfigurovat naši funkci tak, aby fungovala s více zdroji dat a službami.

Důležité

Toto cvičení vychází z prostředků sandboxu a prostředků, které jste vytvořili v předchozích lekcích; konkrétně databáze Azure Cosmos DB, záložky a vstupní vazby. Pokud jste cvičení v předchozích lekcích nedokončili, nebudete moct toto cvičení dokončit.

Vytvoření funkce aktivované protokolem HTTP

Na webu Azure Portal přejděte do aplikace funkcí, kterou jste vytvořili, výběrem názvu aplikace funkcí v cestě s popisem cesty s popisem cesty v horní části stránky funkce HttpTrigger2 .
Na kartě Funkce na stránce Přehled byste měli mít funkce triggeru HTTP, které jste vytvořili.
Na kartě Funkce vyberte Vytvořit. Zobrazí se podokno Vytvořit funkci.
V části Vybrat šablonu vyberte trigger HTTP a pak vyberte Další. Přijměte výchozí hodnoty na kartě Podrobnosti šablony a vyberte Vytvořit. Zobrazí se podokno Přehled funkce HttpTrigger3 .

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

Pojďme přidat další vstupní vazbu Azure Cosmos DB.

V nabídce Funkce HttpTrigger3 vyberte Integrace. Zobrazí se podokno Integrace .
V poli Vstupy vyberte Přidat vstup. Zobrazí se podokno Vytvořit vstup .
V rozevíracím seznamu Typ vazby vyberte Azure Cosmos DB.
Nastavení připojení účtu služby Cosmos DB by mělo být předem vyplněno připojením, které jste vytvořili v předchozím cvičení.

Pokud se vaše připojení nezobrazuje, vytvořte nové připojení podle těchto kroků.
1. V části podrobností služby Azure Cosmos DB v části Nastavení připojení účtu Cosmos DB vyberte odkaz Nový.
2. Po zobrazení dialogového okna Připojení k nové službě Cosmos DB vyberte OK a vytvořte připojení. Vytvoří se nové připojení účtu Cosmos DB.

Zadejte následující hodnoty pro ostatní nastavení v tomto podokně. Pokud se chcete kdykoli dozvědět více o účelu nastavení, můžete vybrat ikonu informací napravo.

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 dříve v této lekci.
Název kolekce	`Bookmarks`	Název kolekce, ze které se data čtou. Toto nastavení jsme definovali dříve v lekci.
ID dokumentu	`{id}`	Přidejte k použití správného vazbového výrazu a přijměte `{id}` parametr předaný v řetězci dotazu.
Klíč oddílu	`{id}`	Znovu přidejte `{id}` použití správného vazbového výrazu a přijměte parametr předaný v řetězci dotazu.
Dotaz SQL (nepovinný)	prázdné	Načítáme vždy jenom jednu položku na základě ID. Filtrování pomocí nastavení Dokument je tedy lepší než použití dotazu SQL v této instanci. Mohli bychom sestavit dotaz SQL, který vrací jednu položku (`SELECT * from b where b.ID = /id`). Tento dotaz by skutečně vrátil položku, ale vrátil by ji v kolekci položek. Náš kód by musel dále pracovat s kolekcí, což je komplikace, která přitom není nutná. Přístup založený na dotazu SQL použijte, když budete chtít načíst více dokumentů.

Podobně jako vstupní vazba, kterou jsme vytvořili v předchozím cvičení, chceme vyhledat záložku s konkrétním ID, takže jsme svázali ID dokumentu, které naše funkce přijímá v řetězci dotazu na vazbu, což se označuje jako výraz vazby. Trigger funkce je požadavek HTTP, který pomocí řetězce dotazu určuje ID, které se má vyhledat. Vazba vrátí buď 0 (nenalezena), nebo 1 (nalezené) dokumenty.

Vyberte OK a uložte konfiguraci vstupní vazby.

Teď máme vstupní vazbu Azure Cosmos DB. Pojďme přidat výstupní vazbu, abychom mohli do naší kolekce zapsat nové položky.

Přidání výstupní vazby Azure Cosmos DB

V podokně Integrace pro HttpTrigger3 v poli Výstupy vyberte Přidat výstup. Zobrazí se podokno Vytvořit výstup .
V části Typ vazby v rozevíracím seznamu vyberte Azure Cosmos DB.
Nastavení připojení účtu služby Cosmos DB by mělo být předem vyplněno připojením, které jste vytvořili dříve. Pokud ne, rozbalte rozevírací seznam a vyberte připojení, které jste definovali pro vstupní vazbu HttpTrigger3.

Zadejte následující hodnoty pro zbývající nastavení výstupní vazby.

Nastavení	Hodnota	Popis
Název parametru dokumentu	`newbookmark`	Název používaný k identifikaci této vazby v kódu. Tento parametr se používá k zápisu nové položky záložky.
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 dříve v této lekci.
Název kolekce	`Bookmarks`	Název kolekce, ze které se data čtou. Tato hodnota je název kontejneru, který jsme definovali dříve v lekci.
Klíč oddílu	`/id`	Přidejte klíč oddílu, který jsme dříve definovali při vytváření kontejneru Azure Cosmos DB Bookmarks. Zde zadaný klíč (zadaný v konfiguraci `<key>`vstupní vazby) se musí shodovat s klíčem v kontejneru.

Výběrem možnosti OK uložte tuto konfiguraci výstupní vazby.

Teď máme vazbu pro čtení z naší kolekce a vazbu pro zápis do ní.

Přidání výstupní vazby Azure Queue Storage

Azure Queue Storage je služba pro ukládání zpráv, ke které můžete přistupovat odkudkoli na světě. Velikost jedné zprávy může být až 64 kB a fronta může obsahovat miliony zpráv až do celkové kapacity účtu úložiště, ve kterém je definovaná. Následující diagram znázorňuje, jak se v našem scénáři používá fronta na vysoké úrovni.

Obrázek znázorňující frontu úložiště s funkcí nasdílenou a jinou funkcí, která odesílá zprávy

V tomto příkladu vidíte, že funkce s názvem add-bookmark přidá zprávy do fronty a další pojmenovaný gen-qr-code otevře zprávy ze stejné fronty a zpracuje požadavek. Protože do fronty zapisujeme nebo nasdílíme zprávy z add-bookmark, přidáme do vašeho řešení novou výstupní vazbu.

Pojďme vytvořit vazbu prostřednictvím portálu.

V podokně Integrace pro vaši funkci v poli Výstupy vyberte Přidat výstup. Zobrazí se podokno Vytvořit výstup .
V rozevíracím seznamu Typ vazby vyberte Azure Queue Storage.

Pokud se zobrazí zpráva s výzvou Microsoft.Azure.WebJobs.Extensions.Storage k instalaci rozšíření, vyberte nainstalovat a počkejte, až se dokončí.

Dále nastavíme připojení účtu úložiště, kde je naše fronta hostovaná.

V části Připojení účtu úložiště vyberte Nové. Zobrazí se dialogové okno Nové připojení účtu úložiště.
Na začátku tohoto modulu se při vytváření aplikace funkcí vytvořil také účet úložiště. Vyberte ho z rozevíracího seznamu a pak vyberte OK.

Nastavení připojení účtu úložiště se naplní názvem připojení.

I když bychom mohli zachovat výchozí hodnoty, pojďme změnit některá nastavení tak, aby pro zbývající vlastnosti poskytla větší význam.

Dokončete nastavení v podokně Vytvořit výstup nahrazením následujících starých hodnot novými hodnotami:

Nastavení	Stará hodnota	Nová hodnota	Popis
Název parametru zprávy	outputQueueItem	newmessage	Vlastnost vazby, která používáme v kódu.
Název fronty	outqueue	bookmarks-post-process	Název fronty, do které umísťujeme záložky, aby je další funkce dále zpracovávala.

Výběrem možnosti OK uložte výstupní konfiguraci pro Azure Queue Storage.

Aktualizace implementace funkce

Teď máme nastavené všechny vazby. Je načase je ve funkci použít.

Pokud chcete otevřít soubor index.js v editoru kódu, vyberte funkci HttpTrigger3.
V nabídce v části Vývojář vyberte Kód + Test. Pro vaši funkci se zobrazí podokno Kód a testování .

Nahraďte veškerý kód v souboru index.js kódem z následujícího fragmentu kódu a potom na panelu příkazů vyberte Uložit.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Pojďme si podrobně rozebrat, co tento kód dělá:

Protože tato funkce mění naše data, očekáváme, že požadavek HTTP bude POST a data záložky budou součástí textu požadavku.
Naše vstupní vazba Azure Cosmos DB se pokusí načíst dokument nebo záložku pomocí id, které jsme obdrželi. Pokud najde položku, bookmark objekt se nastaví. Podmínka if(bookmark) kontroluje, jestli byla položka nalezena.
Přidání do databáze je jednoduché jako nastavení parametru context.bindings.newbookmark vazby na novou položku záložky, kterou jsme vytvořili jako řetězec JSON.
Odeslání zpráv do naší fronty je také jednoduché: jen se nastaví parametr context.bindings.newmessage.

Poznámka:

Jediná věc, kterou jste museli sami provést, bylo vytvořit vazbu fronty. Samotnou frontu jste nikdy explicitně nevytvořili. Tady na vlastní oči vidíte, co všechno vazby dokážou! Jak uvádí následující oznámení, pokud fronta neexistuje, automaticky se pro vás vytvoří.

Snímek obrazovky se zprávou, že se fronta automaticky vytvoří .

Tak to je vše. Teď se v další části podíváme na naše dílo v akci.

Pokud chcete otevřít soubor run.ps1 v editoru kódu, vyberte funkci HttpTrigger3 v horní části podokna s popisem cesty.
V nabídce Funkce v části Vývojář vyberte Kód + Test. Zobrazí se podokno Kód + Test pro funkci HttpTrigger3 zobrazující výchozí obsah run.ps1.

Obsah v souboru nahraďte následujícím kódem.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

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

Na panelu příkazů vyberte Uložit. Vytvoří se připojení a otevře se relace souboru protokolu.

Pojďme si podrobně rozebrat, co tento kód dělá:

Protože tato funkce mění naše data, očekáváme, že požadavek HTTP bude POST a data záložky budou součástí textu požadavku.
Naše vstupní vazba Azure Cosmos DB se pokouší načíst dokument nebo záložku id pomocí požadavku. Pokud najde položku, bookmark objekt se nastaví. Podmínka if ($bookmark) kontroluje, jestli byla položka nalezena.
Přidání do databáze se zajistí jednoduchým voláním Push-OutputBinding s názvem výstupní vazby Cosmos DB (newbookmark) a hodnotou objektu $newBookmark.
Vystavení zprávy do naší fronty se zajistí jednoduchým voláním Push-OutputBinding s názvem výstupní vazby fronty (newmessage) a hodnotou objektu $newBookmark.

Poznámka:

Snímek obrazovky s popisem nástroje uživatelského rozhraní, který se automaticky vytvoří ve frontě

Tak to je vše. Teď se v další části podíváme na naše dílo v akci.

Vyzkoušejte si to.

Když teď máme několik výstupních vazeb, testování je o něco složitější. V předchozích lekcích jsme obsah testovali odesláním požadavku HTTP s řetězcem dotazu, ale tentokrát chceme provést příspěvek HTTP. Musíme to také zkontrolovat proto, abychom viděli, jestli se zprávy správně přidávají do fronty.

Na panelu příkazů podokna Kód + Test pro funkci HttpTrigger3 vyberte Test/Spustit. Zobrazí se nové podokno s otevřenou kartou Vstup, jak je znázorněno na tomto obrázku:
V rozevíracím seznamu metod HTTP ověřte, zda je vybrána možnost POST .

Obsah textu požadavku nahraďte následujícím objektem JSON:

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

Vyberte Spustit.
Programový průběh se zobrazí v podokně Protokoly . Po dokončení ověřte, že na kartě Výstup se v nastavení obsahu odpovědi HTTP zobrazuje záložka již existuje.

Přidali jste položku záložky v cvičení – čtení dat se vstupními vazbami. Odpověď potvrdí, že javascript var bookmark = context.bindings.bookmark funguje správně a že váš kód PowerShellu vytváří stejné připojení.
Pojďme do databáze publikovat druhou záložku. Vyberte kartu Vstup.
Obsah textu požadavku nahraďte následujícím objektem JSON:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Vyberte Spustit.
Ověřte, že karta Výstup zobrazuje v obsahu odpovědi HTTP přidanou záložku, jak je znázorněno na následujícím snímku obrazovky.

Gratulujeme! Vaše funkce funguje tak, jak je navržena. Ale co operace fronty, kterou jsme přidali do kódu? Pojďme zjistit, jestli bylo něco zapsáno do fronty.

Kontrola zapsání zprávy do fronty

Fronty Azure Queue Storage jsou hostovány v účtu úložiště. Účet úložiště jste nakonfigurovali při vytváření výstupní vazby.

Na panelu globálního vyhledávání na webu Azure Portal zadejte účty úložiště a pak v seznamu výsledků vyberte Účty úložiště. Zobrazí se podokno Účty úložiště.
Vyberte účet úložiště, který jste použili ke konfiguraci výstupní vazby nové zprávy .
V nabídce Účet úložiště v části Úložiště dat vyberte Fronty a vypište fronty hostované tímto účtem úložiště. Ověřte, že je uvedená fronta bookmarks-post-process , jak je znázorněno na následujícím snímku obrazovky.
Výběrem záložek po procesu zobrazíte seznam zpráv, které jsou ve frontě. Pokud šlo všechno podle plánu, fronta obsahuje zprávu, kterou jste publikovali při přidávání záložky do databáze. Mělo by to vypadat následovně.

V tomto příkladu dostala zpráva jedinečné ID a ve sloupci Text zprávy se zobrazí záložka ve formátu JSON. Pro záložku Azure docs , kterou jste se pokusili přidat, neexistuje žádná zpráva, protože už v databázi existovala.
Funkci můžete dále otestovat změnou textu požadavku v testovacím podokně pomocí nových sad ID/URL a spuštěním funkce. Sledujte tuto frontu a uvidíte, jak budou přicházet další zprávy. Můžete se také podívat na databázi a zkontrolovat, že byly nové položky přidány.

V tomto cvičení jsme rozšířili vaše znalosti vazeb na výstupní vazby a zápis dat do služby Azure Cosmos DB. Přidali jsme výstupní vazbu pro odesílání zpráv do fronty Azure. Tento příklad ukazuje skutečnou sílu vazeb, které vám pomůžou tvarovat a přesouvat data z příchozích zdrojů do různých cílů. Nemuseli jsme sami psát žádný databázový kód ani spravovat připojovací řetězec. Místo toho jsme nakonfigurovali vazby deklarativně a nechali platformu, aby se postarala o zabezpečení připojení, škálování naší funkce a škálování připojení.

Pokračovat