Gyakorlat – Adatok olvasása bemeneti kötésekkel

20 perc

Tegyük fel, hogy könyvjelző-keresési szolgáltatást szeretne létrehozni. Kezdetben a szolgáltatás írásvédett. Ha a felhasználók bejegyzést szeretnének találni, a bejegyzés azonosítójával rendelkező kérést küldenek, és a függvény visszaadja az URL-címet. Az alábbi folyamatábra a logikai folyamatot szemlélteti.

Amikor egy felhasználó szöveget tartalmazó kérést küld, a Könyvjelző keresése függvény olyan bejegyzést próbál megkeresni az adatbázisban, amely egy könyvjelzőt tartalmaz, amely a szöveget kulcsként vagy azonosítóként tartalmazza. A rendszer egy olyan eredményt ad vissza, amely jelzi, hogy megtalálta-e a bejegyzést.

Amikor az Azure-függvény könyvjelző-azonosítóval rendelkező kérést kap, először ellenőrzi, hogy a kérés érvényes-e. Ha nem, hibaüzenet jelenik meg. Ha a kérelem érvényes, a függvény ellenőrzi, hogy a könyvjelző azonosítója létezik-e az Azure Cosmos DB-adatbázisban. Ha nem létezik, hibaüzenet jelenik meg. Ha megtalálja a könyvjelző-azonosítót, sikeres választ ad.

Az adatokat tárolnia kell valahol. Az előző folyamatábra az adattár egy Azure Cosmos DB-példány. De hogyan csatlakozhat egy adatbázishoz egy függvényből, és hogyan olvashatja az adatokat? A funkciók világában az ilyen feladatokhoz bemeneti kötést kell konfigurálnia. Egy bemeneti kötés konfigurálása az Azure Portalon egyszerű. Ahogy rövidesen láthatja, nem kell kódot írnia vagy tárkapcsolatot nyitnia. Az Azure Functions futtatókörnyezete és adatkötése elvégzi Ön helyett ezeket a feladatokat.

Azure Cosmos DB-fiók létrehozása

Feljegyzés

Ez a gyakorlat nem az Azure Cosmos DB-hez készült oktatóanyag. Ha többet szeretne megtudni, tekintse meg az Azure Cosmos DB teljes képzési tervét a modul végén.

Adatbázisfiók létrehozása

Az adatbázisfiók egy olyan tároló, amellyel egy vagy több adatbázist kezelhet. Adatbázis létrehozása előtt létre kell hoznunk egy adatbázisfiókot.

Az Azure Portal erőforrásmenüjében vagy a Kezdőlapon válassza az Erőforrás létrehozása lehetőséget. Megjelenik az Erőforrás létrehozása panel.
Az Erőforrás létrehozása menüben válassza az Adatbázisok lehetőséget, majd keresse meg és válassza ki az Azure Cosmos DB-t. Megjelenik a Számítási feladatnak leginkább megfelelő API? panel.
Az Azure Cosmos DB for NoSQL-ben válassza a Létrehozás lehetőséget, hogy létrehozhassuk a Cosmos DB-eseményindítót és a bemeneti/kimeneti kötéseket. Megjelenik az Azure Cosmos DB-fiók létrehozása – Azure Cosmos DB for NoSQL panel.

Az Alapszintű beállítások lapon adja meg az alábbi értékeket minden beállításhoz.

Beállítás	Érték	Leírás
Projekt részletei
Előfizetés	Concierge-előfizetés	A tesztkörnyezet erőforrásaival működő Azure-előfizetés.
Erőforráscsoport	A legördülő listában válassza a [tesztkörnyezeti erőforráscsoport neve] lehetőséget	A tesztkörnyezet erőforráscsoportja.
Példány részletei
Fiók neve	`globally unique name`	Adjon meg egy egyedi, de azonosítható nevet az Azure Cosmos DB-fiókhoz; `documents.azure.com` a program hozzá van fűzve a megadott névhez. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Hely	`region`	Válassza ki az Önhöz legközelebbi régiót.

Fogadja el a fennmaradó beállítások alapértelmezett értékeit, és válassza a Véleményezés + létrehozás lehetőséget a bemenet ellenőrzéséhez. Megjelenik egy érvényesítési sikeresség-értesítés .
Válassza a Létrehozás lehetőséget egy adatbázisfiók kiépítéséhez és üzembe helyezéséhez.
Az üzembe helyezés eltarthat egy ideig. Várjon egy sikeres üzembe helyezési üzenetet az Értesítési központban, mielőtt továbblépne.
Válassza az Ugrás az erőforrásra lehetőséget a portálon található adatbázisfiókhoz való ugráshoz. Megjelenik az Azure Cosmos DB-fiók gyors üzembe helyezési panelje.

Ezután hozzáadunk egy tárolót, majd hozzáadunk egy adatbázist az Azure Cosmos DB-fiókhoz.

Tároló hozzáadása

Az Azure Cosmos DB-ben a tárolók különböző, felhasználó által létrehozott entitások, más néven elemek tárolására szolgálnak. Létrehozunk egy Könyvjelzők nevű tárolót.

Hozzunk létre adatbázist és tárolót az Adatkezelő eszközzel.

Az Azure Cosmos DB-fiók menüjében válassza az Adatkezelőt. Megjelenik a Cosmos DB-fiók Adatkezelő panelje.
Válassza az Új tároló mezőt. Megjelenik az Új tároló panel. Előfordulhat, hogy görgetnie kell a megtekintéséhez.

Minden beállításhoz adja meg a következő értékeket.

Beállítás	Érték	Leírás
Adatbázis azonosítója	Válassza az Új létrehozása lehetőséget, és adja meg a func-io-learn-db értéket az adatbázis-azonosítóhoz	Az adatbázisnevek 1–255 karakter hosszúak lehetnek, és nem tartalmazhatnak `/, \\, #, ?`, vagy záró szóközt. Bármit beírhat, de ebben a modulban func-io-learn-db-t használunk.
Adatbázis maximális ru/s	4000	Fogadja el a másodpercenkénti 4000 kérelemegység (RU/s) alapértelmezett átviteli sebességét. A késés csökkentése érdekében később felskálázhatja a teljesítményt.
Tároló azonosítója	Könyvjelzők	A tárolóazonosítók nevére ugyanazok a karakterkorlátozások vonatkoznak, mint az adatbázisnevekre. Ebben a modulban könyvjelzőket használunk.
Partíciókulcs	/id	A partíciókulcs határozza meg, hogy az Azure Cosmos DB-gyűjteményen belüli dokumentumok hogyan lesznek elosztva a logikai adatpartíciókra. Itt a partíciókulcs-beállítást használjuk kényelemként, mivel ebben a modulban nem foglalkozunk az adatbázis teljesítményével. Az Azure Cosmos DB partíciókulcs-stratégiáiról a Microsoft Learn Azure Cosmos DB-moduljaiból tudhat meg többet.

Fogadja el az összes többi beállítás alapértelmezett beállításait.

Görgessen a panel aljára, és válassza az OK gombot. Hagyjon néhány percet az adatbázis és a tároló létrehozásához.

Ha elkészült, az Adatkezelő megjeleníti a func-io-learn-db-t a DATA-ban a NOSQL API-ban.
A func-io-learn-db elemet választva bontsa ki. Figyelje meg, hogy a func-io-learn-db adatbázis több gyermektagot tartalmaz, köztük a méretezést és a könyvjelzőket.
Bontsa ki a Könyvjelzők tárolót . Figyelje meg, hogy több gyermektag már előre feltölti.

A következő feladatban néhány adatot, más néven elemeket ad hozzá a Könyvjelzők tárolóhoz.

Tesztadatok hozzáadása

Adatokat szeretne hozzáadni a Könyvjelzők tárolóhoz . Az Adatkezelővel url-címet és azonosítót tárolhat az egyes elemekhez.

Bontsa ki a func-io-learn-db adatbázist és a Könyvjelzők tárolót, majd válassza az Elemek lehetőséget. Megjelenik az Elemek lap.
A parancssávon válassza az Új elem lehetőséget.
Cserélje le az új elem alapértelmezett kódját a következő JSON-kódra.
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```

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

Figyelje meg, hogy a hozzáadott két sornál több tulajdonság jelenik meg. Mindegyik egy aláhúzással (_rid, _self, _etag, _attachments, _ts)kezdődik. Az alábbi táblázatban ismertetett tulajdonságok a tárolóhoz hozzáadott elemek kezeléséhez szükségesek.

Tulajdonság	Leírás
`_rid`	Az erőforrás-azonosító egy egyedi azonosító, amely szintén hierarchikus az erőforrásmodell erőforrás-veremén. Az azonosító belsőleg használatos az elemerőforrás elhelyezéséhez és navigációjához.
`_self`	Az erőforrás egyedi címezhető URI-ja.
`_etag`	Az optimista egyidejűség vezérléséhez szükséges.
`_attachments`	A mellékletek erőforrásának címezhető elérési útja.
`_ts`	Az erőforrás utolsó frissítésének időbélyege.

Vegyünk fel még néhány elemet a Könyvjelzők tárolóba. A parancssávon válassza az Új elem lehetőséget. Hozzon létre négy elemet az alábbi tartalommal. Az elemek hozzáadásához válassza az Új elem lehetőséget, majd az egyes elemek másolása és beillesztése után válassza a Mentés lehetőséget. Figyelje meg, hogy az egyes elemek hogyan lesznek hozzáadva az elemek listájához.
```
{
    "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"
}
```
Amikor befejezte a könyvjelzőadatok megadását, a tárolónak az alábbi képhez hasonlóan kell kinéznie.

A Könyvjelzők tároló öt elemet tartalmaz. Ebben az esetben, ha egy kérés "id=docs" értékkel érkezik, megkeresi az azonosítót a Könyvjelzők tárolóban, és visszaadja az URL-címet https://learn.microsoft.com/azure. Hozzunk létre egy Azure-függvényt, amely értékeket keres a Könyvjelzők tárolóban.

A függvény létrehozása

Nyissa meg az előző leckében létrehozott függvényalkalmazást. Az erőforrás menüjében válassza a Kezdőlap lehetőséget, és a Legutóbbi erőforrások szakaszban meg kell jelennie a függvényalkalmazásnak (a Típus egyenlő függvényalkalmazással). Válassza ki a függvényalkalmazást. Megjelenik a Függvényalkalmazás panel.
Az Áttekintés lap Függvények lapján egy függvénynek kell lennie: HttpTrigger1.
Hozzunk létre egy másik függvényt. Válassza a Létrehozás lehetőséget a Függvények lapon. Megjelenik a Függvény létrehozása panel, amely a támogatott eseményindítók sablonjait sorolja fel.
A Sablon kiválasztása szakaszban válassza a HTTP-eseményindítót, majd a Tovább gombot.
Fogadja el az összes alapértelmezett beállítást, és válassza a Létrehozás lehetőséget a függvény létrehozásához.

Megjelenik a HttpTrigger2 függvény Áttekintés panelje.

A függvény ellenőrzése

Az eddigi előrehaladást az új függvény tesztelésével ellenőrizheti.

A parancssávon válassza a Függvény URL-címének lekérése lehetőséget. Megjelenik a Függvény URL-címének lekérése párbeszédpanel.
Válassza az alapértelmezett (függvénykulcs) lehetőséget a legördülő listában, majd válassza a Másolás vágólapra ikont, és válassza az OK gombot.
Illessze be a másolt függvény URL-címét egy új böngészőlap címsorába. Fűzze hozzá a lekérdezési sztring értékét &name=<your name> az URL-cím végéhez, cserélje le <your name> a nevét, majd nyomja le az Enter billentyűt. Az Azure-függvénynek személyre szabott választ kell adnia a böngészőben.

Most, hogy már működik a csontvázfüggvényünk, fordítsuk a figyelmünket arra, hogy adatokat olvassunk az Azure Cosmos DB-ből vagy a forgatókönyvünkben a Könyvjelzők tárolóból.

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

Ha adatokat szeretne beolvasni a létrehozott adatbázisból, meg kell adnia egy bemeneti kötést. Ahogy itt látható, konfigurálhat egy kötést, amely csak néhány lépésben tud beszélni az adatbázissal.

Az Azure Portal httpTrigger2 függvény menüjében válassza az Integráció lehetőséget. Megjelenik a függvény integrációs panelje.

Olyan sablont használt, amely HTTP-eseményindító-kérelmet hozott létre HTTP kimeneti kötéssel. Adjunk hozzá egy Azure Cosmos DB bemeneti kötést.
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.
Az Azure Cosmos DB részletek szakaszában a Cosmos DB-fiók kapcsolatbeállítása alatt válassza az Új hivatkozást. Megjelenik az Új Cosmos DB kapcsolat párbeszédpanel.

Ha megjelenik egy üzenet, amely arra kéri, hogy telepítse a Microsoft.Azure.WebJobs.Extensions.CosmosDB bővítményt, válassza a Telepítés lehetőséget, és várja meg, amíg befejeződik.
Alapértelmezés szerint az Azure felismeri a korábban létrehozott Azure Cosmos DB-fiókot. Válassza az OK gombot az adatbázishoz való csatlakozás beállításához. Az adatbázisfiókhoz új kapcsolat van konfigurálva, és megjelenik a Cosmos DB-fiók kapcsolatmezőjében .

Egy adott azonosítóval rendelkező könyvjelzőt szeretnénk megkeresni, ezért kössük a lekérdezési sztringben kapott azonosítót a kötéshez.

Fejezzük be a beállításokat a Bevitel létrehozása panelen. Minden beállításhoz adja meg a következő értékeket. Ha többet szeretne megtudni az egyes beállítások céljáról, válassza a mező információs ikonját.

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 beállított adatbázisnév.
Gyűjtemény neve	`Bookmarks`	A gyűjtemény, amelyből az adatokat olvastuk. Ez a beállítás meg lett határozva.
Dokumentumazonosító	`id`	Adja hozzá a Könyvjelzők Azure Cosmos DB-tároló létrehozásakor definiált dokumentumazonosítót.
Partíciókulcs	`/id`	Adja hozzá a Könyvjelzők Azure Cosmos DB-gyűjtemény létrehozásakor definiált partíciókulcsot. Az itt megadott kulcsnak (az `<key>` bemeneti kötési formátumban megadva) egyeznie kell a gyűjteményben szereplővel.
SQL-lekérdezés (nem kötelező)	Hagyja üresen	Egyszerre csak egy dokumentumot fog beolvasni az azonosító alapján. A Dokumentumazonosító beállítással végzett szűrés tehát jobb, mint egy SQL-lekérdezés használata ebben a példányban. Egyetlen bejegyzés lekéréséhez (`SELECT * from b where b.ID = id`) is létrehozhat egy SQL-lekérdezést. Ez a lekérdezés valóban visszaadna egy dokumentumot, azonban egy dokumentumgyűjteményen belül. A kódnak így feleslegesen kellene manipulálnia a gyűjteményt. SQL-lekérdezést akkor használjon inkább, ha több dokumentumra szeretne keresni.

Annak tisztázásához, hogy miért használjuk ezeket a beállításokat, egy adott azonosítóval rendelkező könyvjelzőt szeretnénk keresni, ezért a függvény által kapott dokumentumazonosítót a bemeneti kötéshez kötöttük. Ez a szintaxis más néven egy kötési kifejezés. A függvényt egy olyan HTTP-kérés aktiválja, amely egy lekérdezési sztringgel adja meg a keresendő azonosítót. Mivel az azonosítók egyediek a gyűjteményben, a kötés 0 (nem található) vagy 1 (talált) dokumentumot ad vissza.

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

A függvény implementációjának frissítése

Most, hogy definiálta a kötést, használhatja a függvényben. A létrehozott kötés implementálásához két módosítást kell végrehajtania:

Módosítsa a függvény nyelvspecifikus implementációs kódját. Meg kell határoznia, hogy egy olyan dokumentum található-e az adatbázisban, amely megfelel a függvénynek átadott azonosítónak.
Módosítsa a függvény JSON-implementációs kódját, hogy a lekérdezési sztringben átadott paramétert fogadja el.

A függvény JavaScript-implementációs kódjának módosítása

A HttpTrigger2 függvény Függvény menüjében válassza a Kód + Teszt lehetőséget. Megjelenik a Code + Test panel a HttpTrigger2 függvényhez.

Cserélje le az index.js fájlban lévő összes kódot a következő kódra.

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

A parancssávon válassza a Mentés lehetőséget. Válassza a Fájlrendszernaplók lehetőséget a naplók panel felső részén található legördülő menüben (amely alapértelmezés szerint az App Insights-naplókat jeleníti meg). Megjelenik a Naplók panel, amelyen látható, hogy Connected!

Vizsgáljuk meg, mit csinál ez a kód.

Egy HTTP-kérelem aktiválja a függvényt, a(z) id lekérdezésparaméter pedig eljut az Azure Cosmos DB bemeneti kötéséhez.
Ha az adatbázis talál egy olyan dokumentumot, amely megfelel ennek az azonosítónak, a bookmark paraméter a található dokumentumra van állítva.

Ebben a példában a kód egy olyan választ hoz létre, amely az adatbázis megfelelő dokumentumában található URL-értéket tartalmazza.
Ha nem található a kulcsnak megfelelő dokumentum, a kérés egy hasznos adattal és állapotkóddal válaszol, amely közli a felhasználóval a rossz hírt.

A függvény JSON-implementációs kódjának módosítása

Válassza function.json az elérési út legördülő listájából<functionapp> \ HttpTrigger2 \.

Cserélje le az function.json fájlban lévő összes kódot a következő kódra. Ügyeljen rá, és cserélje le your-database az Azure Cosmos DB-fiók nevére.

{
  "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}",
    }
  ]
}

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

A függvény PowerShell-implementációs kódjának módosítása

A HttpTrigger2 függvény Függvény menüjében válassza a Kód + Teszt lehetőséget. Megjelenik a Code + Test panel a HttpTrigger2 függvényhez, amely megjeleníti a run.ps1 fájlt.

Cserélje le a fájl összes kódját a run.ps1 következő kódra.

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

A parancssávon válassza a Mentés lehetőséget. Válassza a Fájlrendszernaplók lehetőséget a naplók panel felső részén található legördülő menüben (amely alapértelmezés szerint az App Insights-naplókat jeleníti meg). Megjelenik a Naplók panel, amelyen látható, hogy Connected!

Vizsgáljuk meg, mit csinál ez a kód.

Egy HTTP-kérelem aktiválja a függvényt, a(z) id lekérdezésparaméter pedig eljut az Azure Cosmos DB bemeneti kötéséhez.
Ha az adatbázis talál egy olyan dokumentumot, amely megfelel ennek az azonosítónak, a bookmark paraméter a található dokumentumra van állítva.

Ebben a példában a kód egy olyan választ hoz létre, amely az adatbázis megfelelő dokumentumában található URL-értéket tartalmazza.
Ha nem található a kulcsnak megfelelő dokumentum, a kérés egy hasznos adattal és állapotkóddal válaszol, amely közli a felhasználóval a rossz hírt.

A függvény JSON-implementációs kódjának módosítása

Válassza function.json az elérési út legördülő listájából<functionapp> \ HttpTrigger2 \.

Módosítsa a paraméter értékét id , és partitionKey fogadja el a következő paramétert {id}: . A function.json kódnak az alábbi példához kell hasonlítania, ahol your-database a Rendszer a Cosmos DB-adatbázis nevére cseréli.

{
  "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}"
    }
  ]
}

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

Próba

Már a HttpTrigger2 függvény Kód + Teszt paneljén kell lennie.
A parancssávon válassza a Függvény URL-címének lekérése lehetőséget. Megjelenik a Függvény URL-címének lekérése párbeszédpanel.
A Kulcs legördülő listában válassza az alapértelmezett lehetőséget a Függvénykulcs területen, majd válassza a Másolás vágólapra ikont az URL-cím végén.
Illessze be a másolt függvénykulcsot egy új böngészőlap címsorába, majd adja hozzá a lekérdezési sztring értékét &id=docs az URL-cím végéhez. Az eredményként kapott URL-címnek a következő példához kell hasonlítania:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
A kérés futtatásához nyomja le az Enter billentyűt . A függvény által visszaadott válasznak hasonlónak kell lennie az alábbi példához.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Cserélje le &id=docs az &id=missingEnter billentyűt, és figyelje meg a választ. Öt könyvjelzőt definiáltunk, és értelmes hibaválaszt hoztunk létre, ha a kért könyvjelző nem létezik.

Ebben az egységben manuálisan létrehozta az első bemeneti kötést, amellyel adatokat olvashat be egy Azure Cosmos DB-adatbázisból. A kötéseknek köszönhetően az adatbázisban való kereséshez és az adatok beolvasásához csak minimális mennyiségű kódot kellett írnia. A legtöbb munkája során deklaratív módon konfigurálta a kötést, és a platform gondoskodott a többiről.

A következő egységben egy Azure Cosmos DB kimeneti kötéssel további adatokat adhat a könyvjelzőgyűjteményhez.

Gyakorlat – Adatok olvasása bemeneti kötésekkel

Azure Cosmos DB-fiók létrehozása

Adatbázisfiók létrehozása

Tároló hozzáadása

Tesztadatok hozzáadása

A függvény létrehozása

A függvény ellenőrzése

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

A függvény implementációjának frissítése

A függvény JavaScript-implementációs kódjának módosítása

A függvény JSON-implementációs kódjának módosítása

A függvény PowerShell-implementációs kódjának módosítása

A függvény JSON-implementációs kódjának módosítása

Próba

Visszajelzés