Gyakorlat – Adatok írása kimeneti kötésekkel

15 perc

Az előző gyakorlatban bevezettünk egy forgatókönyvet, amely könyvjelzőket keres egy Azure Cosmos DB-adatbázisban. Beállítottuk a bemeneti kötést, hogy adatokat tudjunk kiolvasni a könyvjelzőgyűjteményből. Csinálhatunk azonban ennél többet is. Bővítsük ki a forgatókönyvet, hogy az írást is tartalmazza. Tekintse meg a következő folyamatábrát:

Döntési folyamatábra, amely szemlélteti a könyvjelzők Azure Cosmos DB háttérrendszerben való hozzáadásának folyamatát, és választ ad vissza.

Ebben a forgatókönyvben a könyvjelzők gyűjteményhez való hozzáadására vonatkozó kérések érkeznek. A kérések a kívánt kulcshoz vagy azonosítóhoz lesznek átadva a könyvjelző URL-címével együtt. Ahogy a folyamatábra is látható, hibaüzenettel válaszolunk, ha a kulcs már létezik a háttérrendszerünkben.

Ha a nekünk átadott kulcs nem található, hozzáadjuk az új könyvjelzőt az adatbázishoz. Itt akár be is fejezhetnénk, de tegyünk meg még valamit.

Lát még egy lépést a folyamatábrában? Eddig nem sokat tettünk a feldolgozás szempontjából kapott adatokkal. Áthelyezzük a kapott adatokat egy adatbázisba. Egy valós megoldásban azonban valószínűleg valamilyen módon dolgoznánk fel az adatokat. Az összes feldolgozást ugyanabban a függvényben végezhetjük el, de ebben a gyakorlatban egy olyan mintát mutatunk, amely a további feldolgozást egy másik összetevőre vagy üzleti logikára ra bontja.

Mi lehet jó példa a feladatok kiszervezésére a könyvjelzők forgatókönyvében? Mi lenne például, ha QR-kód generáló szolgáltatásnak adnánk át az új könyvjelzőt? Ez a szolgáltatás viszont létrehozna egy QR-kódot az URL-címhez, tárolná a képet a Blob Storage-ban, és hozzáadná a QR-rendszerkép címét a könyvjelzőgyűjtemény bejegyzéséhez. A szolgáltatás meghívása QR-rendszerkép létrehozásához időigényes. Így ahelyett, hogy megvárnánk az eredményt, átadjuk a feladatot egy függvénynek, és hagyjuk, hogy aszinkron módon végezze el ezt a feladatot.

Ahogyan az Azure Functions támogatja a bemeneti kötéseket a különböző integrációs forrásokhoz, a kimeneti kötésekhez is rendelkezik sablonokkal, amelyek megkönnyítik az adatok adatforrásokba való írását. A kimeneti kötéseket szintén a function.json fájlban lehet konfigurálni. Ahogy ebben a gyakorlatban látható, a függvényt úgy konfigurálhatjuk, hogy több adatforrással és szolgáltatással működjön.

Fontos

Ez a gyakorlat az előző egységekben létrehozott tesztkörnyezeti erőforrásokra és erőforrásokra épül; konkrétan az Azure Cosmos DB-adatbázist, könyvjelzőket és bemeneti kötéseket. Ha még nem végezte el a gyakorlatokat az előző leckékben, nem fogja tudni elvégezni ezt a gyakorlatot.

HTTP által indított függvény létrehozása

Az Azure Portalon nyissa meg a létrehozott függvényalkalmazást a HttpTrigger2 függvényoldal tetején található útvonalon lévő függvényalkalmazás nevének kiválasztásával.
Az Áttekintés lap Függvények lapján a létrehozott HTTP-triggerfüggvényekkel kell rendelkeznie.
Válassza a Létrehozás lehetőséget a Függvények lapon. Megjelenik a Függvény létrehozása panel.
A Sablon kiválasztása szakaszban válassza a HTTP-eseményindítót, majd a Tovább gombot. Fogadja el az alapértelmezett beállításokat a Sablon részletei lapon, és válassza a Létrehozás lehetőséget. Megjelenik a HttpTrigger3 függvény Áttekintés panelje.

Azure Cosmos DB bemeneti kötésének hozzáadása

Adjunk hozzá egy másik Azure Cosmos DB bemeneti kötést.

A HttpTrigger3 függvény menüjében válassza az Integráció lehetőséget. Megjelenik az Integráció ablaktábla.
Az Eseményindító és bemenetek mezőben válassza a Bemenet hozzáadása lehetőséget. Megjelenik a Bevitel létrehozása panel.
A Kötéstípus legördülő listában válassza az Azure Cosmos DB-t.
A Cosmos DB-fiók kapcsolatbeállítását előre fel kell tölteni az előző gyakorlatban létrehozott kapcsolattal.

Ha nem látja a kapcsolatot a listában, kövesse az alábbi lépéseket egy új kapcsolat létrehozásához.
1. Az Azure Cosmos DB részletek szakaszában a Cosmos DB-fiók kapcsolatbeállítása alatt válassza az Új hivatkozást.
2. Amikor megjelenik az Új Cosmos DB kapcsolat párbeszédpanel, kattintson az OK gombra a kapcsolat létrehozásához. Létrejön egy új Cosmos DB-fiókkapcsolat.

Adja meg az alábbi értékeket a panel többi beállításához. Bármikor, ha többet szeretne megtudni egy beállítás céljáról, kiválaszthatja a jobb oldali információs ikont.

Beállítás	Érték	Leírás
Dokumentumparaméter neve	`bookmark`	A kötés kódbeli azonosítására szolgáló név.
Adatbázis neve	`func-io-learn-db`	A használandó adatbázis. Ez az érték a lecke során már megadott adatbázisnév.
Gyűjtemény neve	`Bookmarks`	Annak a gyűjteménynek a neve, amelyből az adatok beolvasva lesznek. Ezt a beállítást a lecke korábbi részében definiáltuk.
Dokumentumazonosító	`{id}`	Adja hozzá `{id}` a megfelelő kötési kifejezést, és fogadja el a lekérdezési sztringben átadott paramétert.
Partíciókulcs	`{id}`	Adja hozzá `{id}` ismét a megfelelő kötési kifejezést, és fogadja el a lekérdezési sztringben átadott paramétert.
SQL-lekérdezés (nem kötelező)	Hagyja üresen	Egyszerre csak egy elemet fogunk beolvasni az azonosító alapján. A Dokumentum beállítással végzett szűrés tehát jobb, mint az SQL Query használata ebben a példányban. Egyetlen bejegyzés lekéréséhez (`SELECT * from b where b.ID = /id`) is létrehozhatunk egy SQL-lekérdezést. Ez a lekérdezés valóban egy elemet ad vissza, de egy elemgyűjteményben adja vissza. A kódunknak így feleslegesen kellene manipulálnia a gyűjteményt. SQL-lekérdezést akkor használjon inkább, ha több dokumentumra szeretne keresni.

Az előző gyakorlatban létrehozott bemeneti kötéshez hasonlóan egy adott azonosítóval rendelkező könyvjelzőt szeretnénk megkeresni, így a függvény által kapott dokumentumazonosítót a kötéshez, más néven kötési kifejezéshez kötöttük. A függvény-eseményindító egy HTTP-kérés, amely egy lekérdezési sztring használatával adja meg a keresendő azonosítót. A kötés 0 (nem található) vagy 1 (talált) dokumentumot ad vissza.

Válassza a Hozzáadás lehetőséget a bemeneti kötés konfigurációjának mentéséhez.

Most van egy bemeneti Azure Cosmos DB-kötése. Adjunk hozzá egy kimeneti kötést, hogy új bejegyzéseket tudjunk írni a gyűjteményünkbe.

Kimeneti Azure Cosmos DB-kötés hozzáadása

A HttpTrigger3 integrációs paneljén, a Kimenetek mezőben válassza a Kimenet hozzáadása lehetőséget. Megjelenik a Kimenet létrehozása panel.
A Kötés típusa területen válassza ki az Azure Cosmos DB-t a legördülő listából.
A Cosmos DB-fiók kapcsolati beállítását előre fel kell tölteni a korábban létrehozott kapcsolattal. Ha nem, bontsa ki a legördülő listát, és válassza ki a HttpTrigger3 bemeneti kötéshez megadott kapcsolatot.

Adja meg a kimeneti kötés fennmaradó beállításainak alábbi értékeit.

Beállítás	Érték	Leírás
Dokumentumparaméter neve	`newbookmark`	A kötés kódbeli azonosítására szolgáló név. Ezt a paraméter új könyvjelzőbejegyzés írására használatos.
Adatbázis neve	`func-io-learn-db`	A használandó adatbázis. Ez az érték a lecke során már megadott adatbázisnév.
Gyűjtemény neve	`Bookmarks`	Annak a gyűjteménynek a neve, amelyből az adatok beolvasva lesznek. Ez az érték a lecke korábbi részében definiált tárolónév.
Partíciókulcs	`/id`	Adja hozzá azt a partíciókulcsot, amelyet korábban, a Bookmarks Azure Cosmos DB-tároló létrehozásakor definiáltunk. Az itt megadott kulcsnak (a bemeneti kötés konfigurációjában `<key>`megadva) meg kell egyeznie a tárolóban lévő kulccsal.

A kimeneti kötés konfigurációjának mentéséhez válassza a Hozzáadás lehetőséget.

Most már van egy kötés, amely a gyűjteményből olvasandó, és egy kötés, amely hozzá írható.

Azure Queue Storage-hez tartozó kimeneti kötés hozzáadása

Az Azure Queue Storage szolgáltatás üzenetek tárolására szolgál, amelyek a világon bárhonnan elérhetők. Egyetlen üzenet mérete akár 64 KB is lehet, és az üzenetsorok több millió üzenetet tartalmazhatnak – akár az üzenetsor által definiált tárfiók teljes kapacitására is. Az alábbi diagram magas szinten bemutatja, hogyan használják az üzenetsorokat a forgatókönyvünkben.

Ábra egy tárolási üzenetsorról, amelyben egy függvény leküldése és egy másik függvény jelenik meg.

Ebben a példában láthatja, hogy egy add-bookmark nevű függvény üzeneteket ad hozzá egy üzenetsorhoz, egy másik gen-qr-code pedig ugyanabból az üzenetsorból küld üzeneteket, és feldolgozza a kérést. Mivel üzeneteket írunk vagy leküldünk az üzenetsorba a add-bookmarkből, új kimeneti kötést adunk hozzá a megoldáshoz.

Hozzuk létre a kötést a portálon keresztül.

A függvény Integráció paneljén, a Kimenetek mezőben válassza a Kimenet hozzáadása lehetőséget. Megjelenik a Kimenet létrehozása panel.
A Kötéstípus legördülő listában válassza az Azure Queue Storage lehetőséget.

Ha megjelenik egy üzenet, amely arra kéri, hogy telepítse a bővítményt, válassza a Microsoft.Azure.WebJobs.Extensions.Storage telepítést, és várja meg, amíg befejeződik.

Ezután beállítunk egy tárfiók-kapcsolatot, ahol az üzenetsort üzemeltetjük.

A Tárfiók kapcsolata területen válassza az Új lehetőséget. Megjelenik az Új tárfiók kapcsolat párbeszédpanel.
A modul elején, amikor létrehozta a függvényalkalmazást, egy tárfiók is létre lett hozva Önnek. Jelölje ki a legördülő listából, majd kattintson az OK gombra.

A Storage-fiók kapcsolatbeállítása egy kapcsolat nevével van feltöltve.

Bár megtarthatjuk az alapértelmezett értékeket, módosítsunk néhány beállítást, hogy több értelmet adjunk a fennmaradó tulajdonságoknak.

A Kimenet létrehozása panelen végezze el a beállításokat a következő régi értékek új értékekkel való lecserélésével:

Beállítás	Régi érték	Új érték	Leírás
Üzenet-paraméter neve	outputQueueItem	newmessage	A kódban használt kötési tulajdonság.
Üzenetsor neve	outqueue	bookmarks-post-process	Annak az üzenetsornak a neve, amelyben könyvjelzőket helyezünk el, hogy egy másik függvény tovább tudja őket feldolgozni.

Válassza a Hozzáadás lehetőséget az Azure Queue Storage kimeneti konfigurációjának mentéséhez.

A függvényimplementálás frissítése

Most már minden kötés be van állítva. Ideje, hogy felhasználjuk ezeket a függvényben.

Ha meg szeretné nyitni a index.js fájlt a kódszerkesztőben, válassza ki a HttpTrigger3 függvényt.
A menüben válassza a Kód + Teszt lehetőséget. Megjelenik a Függvény Kód + Teszt panelje.

Cserélje le az index.js fájlban lévő összes kódot a következő kódrészlet kódjára, majd a parancssávon válassza a Mentés lehetőséget.

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

Nézzük részletesen, mit csinál ez a kód:

Mivel a függvény módosítja az adatokat, POST típusú HTTP-kérésre számítunk, a könyvjelző adatoknak pedig a kérelemtörzsben kell lenniük.
Az Azure Cosmos DB bemeneti kötés a beérkező id használatával próbál dokumentumot, könyvjelzőt lekérni. Ha talál egy bejegyzést, az bookmark objektum be van állítva. A(z) if(bookmark) feltétel ellenőrzi, hogy a rendszer talált-e bejegyzést.
Az adatbázis hozzáadása olyan egyszerű, mint a context.bindings.newbookmark kötési paraméter beállítása az új könyvjelzőbejegyzésre, amelyet JSON-sztringként hoztunk létre.
Üzenet küldése az üzenetsorunkba csak annyiból áll, hogy beállítjuk a context.bindings.newmessage paramétert.

Feljegyzés

Mindössze az üzenetsor-kötést hoztuk létre. Magát az üzenetsort nem hoztuk létre külön. Így láthatja, mi mindenre lehet képes a kötések használatával! Ahogy a következő értesítésen is látható, a rendszer automatikusan létrehozza az üzenetsort, ha még nem létezik.

Képernyőkép az üzenetsor automatikus létrehozását jelző üzenetről. .

Válassza function.json az elérési út legördülő listájából<functionapp> \ HttpTrigger3 \, és végezze el a következő módosításokat:
1. Módosítsa az összes példányt a "collectionName" értékre "containerName".
2. Módosítsa az összes példányt a "connectionStringSetting" értékre "connection".
3. Törölje a hivatkozásokat a következőre "methods": []: .

Az utolsó function.json fájlnak ehhez a kódhoz kell hasonlítania.

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

A parancssávon válassza a Mentés lehetőséget.

Ennyi az egész. A következő szakaszban megnézzük munkánk eredményét működés közben is.

Ha meg szeretné nyitni a run.ps1 fájlt a kódszerkesztőben, válassza ki a HttpTrigger3 függvényt a panel tetején található zsengerből.
A Függvény menü Fejlesztőeszközök területén válassza a Kód + Teszt lehetőséget. Megjelenik a HttpTrigger3 függvény Kód + Teszt panelje, amely megjeleníti a run.ps1 alapértelmezett tartalmát.

Cserélje le a fájl tartalmát a következő kódra.

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"
})

Válassza a Mentés lehetőséget a parancssávon. Létre lett hozva egy kapcsolat, és megnyílik egy naplófájl-munkamenet.

Nézzük részletesen, mit csinál ez a kód:

Mivel a függvény módosítja az adatokat, POST típusú HTTP-kérésre számítunk, a könyvjelző adatoknak pedig a kérelemtörzsben kell lenniük.
Az Azure Cosmos DB bemeneti kötése megkísérli lekérni a dokumentumot vagy könyvjelzőt a id kérés használatával. Ha talál egy bejegyzést, az bookmark objektum be van állítva. A(z) if ($bookmark) feltétel ellenőrzi, hogy a rendszer talált-e bejegyzést.
Az adatbázis bővítése egyszerű: hívja meg a Push-OutputBinding elemet a Cosmos DB kimeneti kötésének nevével (newbookmark) és a $newBookmark objektum értékével.
Az üzenetek közzététele az üzenetsorban egyszerű: hívja meg a Push-OutputBinding elemet a kimeneti kötés nevével (newmessage) és a $newBookmark objektum értékével.

Feljegyzés

Képernyőkép a felhasználói felület eszköztippjétől, amely szerint az üzenetsor automatikusan létrejön.

Ennyi az egész. A következő szakaszban megnézzük munkánk eredményét működés közben is.

Próba

Most, hogy már több kimeneti kötésünk van, a tesztelés kicsit bonyolultabb lesz. Az előző egységekben egy HTTP-kérés lekérdezési sztringgel való elküldésével teszteltük a tartalmat, de ezúttal HTTP-bejegyzést szeretnénk végrehajtani. Azt is ellenőrizni kell, hogy az üzenetek eljutnak-e az üzenetsorba.

A HttpTrigger3 függvény Kód + Teszt paneljének parancssávján válassza a Tesztelés/Futtatás lehetőséget. Megjelenik egy új ablaktábla, amelyen meg van nyitva a Bemenet lap, ahogy az a képen látható:
A HTTP-metódus legördülő listájában ellenőrizze, hogy a POST ki van-e jelölve.
Cserélje le a kérelem törzsének tartalmát a következő JSON-objektumra:
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```
Válassza a Futtatás lehetőséget.
A programozott folyamat a Naplók panelen jelenik meg. Ha elkészült, ellenőrizze, hogy a Kimenet lapon megjelenik-e a "Könyvjelző már létezik" felirat a HTTP-válasz tartalombeállításában.

Hozzáadta a könyvjelző elemet a Gyakorlat – Adatok olvasása bemeneti kötésekkel című témakörben. A válasz megerősíti, hogy a var bookmark = context.bindings.bookmark JavaScript megfelelően működik, és hogy a PowerShell-kód ugyanazt a kapcsolatot használja.
Tegyünk közzé egy második könyvjelzőt az adatbázisba. Válassza a Bemenet lapot.
Cserélje le a kérelem törzsének tartalmát a következő JSON-objektumra:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Válassza a Futtatás lehetőséget.
Ellenőrizze, hogy a Kimenet lapon megjelenik-e a "könyvjelző hozzáadva!" a HTTP-válasz tartalmában, ahogyan az az alábbi képernyőképen látható.

Gratulálunk! A függvény a tervezett módon működik! De mi a helyzet a kódhoz hozzáadott üzenetsor-művelettel? Nos, nézzük meg, történt-e valamilyen beírás az üzenetsorba.

Az üzenet üzenetsorba írásának ellenőrzése

Az Azure Queue Storage-üzenetsorokat a rendszer egy tárfiókban üzemelteti. A kimeneti kötés létrehozásakor konfigurálta a tárfiókot.

Az Azure Portal globális keresősávján adja meg a tárfiókokat, majd a találatok listájában válassza a Tárfiókok lehetőséget. Megjelenik a Tárfiókok panel.
Válassza ki a newmessage kimeneti kötés konfigurálásához használt tárfiókot.
A Tárfiók menü Adattárolás területén válassza az Üzenetsorok lehetőséget a tárfiók által üzemeltetett üzenetsorok listázásához. Ellenőrizze, hogy a könyvjelzők folyamat utáni üzenetsora szerepel-e a listán, ahogyan az az alábbi képernyőképen látható.
A könyvjelzők utáni folyamat kiválasztásával listázhatja az üzenetsorban lévő üzeneteket. Ha minden a terv szerint haladt, az üzenetsor tartalmazza a könyvjelző adatbázishoz adásakor küldött üzenetet. A következőhöz hasonlóan kell kinéznie.

Ebben a példában az üzenet egyedi azonosítót kapott, az Üzenet szöveg oszlopa pedig JSON formátumban jeleníti meg a könyvjelzőt. Nem található üzenet a hozzáadni kívánt Azure-könyvjelzőhöz docs , mert az már létezik az adatbázisban.
A függvény további teszteléséhez módosítsa a kérelem törzsét a tesztpanelen új azonosító-/URL-készletekkel, és futtassa a függvényt. Figyelje az üzenetsorban a további érkező üzeneteket. Az adatbázist is megvizsgálva ellenőrizheti, hogy új bejegyzések lettek-e hozzáadva.

Ebben a gyakorlatban kiterjesztettük a kötések ismeretét a kimeneti kötésekre, és adatokat írtunk az Azure Cosmos DB-be. Kimeneti kötést adtunk hozzá az üzenetek Azure-üzenetsorba való közzétételéhez. Ez a példa bemutatja a kötések valódi erejét, amely segít az adatok alakításában és áthelyezésében a bejövő forrásokból a különböző célhelyekre. Nem kellett adatbáziskódot írni, és nem kellett kapcsolati sztring magunkat kezelni. Ehelyett deklaratív módon konfiguráltuk a kötéseket, és lehetővé tettük, hogy a platform gondoskodjon a kapcsolatok biztonságáról, a függvény skálázásáról és a kapcsolatok skálázásáról.

Folytatás