Oefening: gegevens schrijven met uitvoerbindingen

15 minuten

In de vorige oefening hebben we een scenario geïmplementeerd om bladwijzers op te zoeken in een Azure Cosmos DB-database. Er is een invoerbinding geconfigureerd voor het lezen van gegevens uit de verzameling bladwijzers. Maar we kunnen meer doen. We gaan het scenario uitbreiden zodat er ook wordt geschreven. Kijk eens naar het volgende stroomdiagram:

Decision flow diagram illustrating the process of adding a bookmark in Azure Cosmos DB back-end and returning a response.

In dit scenario ontvangen we aanvragen om bladwijzers toe te voegen aan onze verzameling. De aanvragen worden doorgegeven met de gewenste sleutel of id. Daarnaast wordt de bladwijzer-URL doorgegeven. Zoals u in het stroomdiagram kunt zien, reageren we met een fout als de sleutel al bestaat in onze back-end.

Als de sleutel die aan ons is doorgegeven niet wordt gevonden, voegen we de nieuwe bladwijzer toe aan onze database. We zouden het hierbij kunnen laten, maar dat doen we niet.

Ziet u de volgende stap in het stroomdiagram? Tot nu toe hebben we niet veel gedaan met de gegevens die we ontvangen in termen van verwerking. We verplaatsen de gegevens die we ontvangen naar een database. In een echte oplossing verwerken we de gegevens waarschijnlijk op een bepaalde manier. We kunnen alle verwerkingen in dezelfde functie uitvoeren, maar in deze oefening laten we een patroon zien waarmee verdere verwerking naar een ander onderdeel of stuk bedrijfslogica wordt offload.

Wat kan een goed voorbeeld zijn van offloading van werk in ons bladwijzerscenario? Wat zou er gebeuren als we de nieuwe bladwijzer naar een service voor het maken van QR-codes versturen? Deze service genereert op zijn beurt een QR-code voor de URL, slaat de afbeelding op in Blob Storage en voegt het adres van de QR-afbeelding toe aan de vermelding in onze verzameling bladwijzers. Het aanroepen van een service voor het genereren van een QR-afbeelding kost veel tijd. Dus in plaats van te wachten op het resultaat, geven we de taak over aan een functie en laten we deze taak asynchroon voltooien.

Net zoals Azure Functions invoerbindingen ondersteunt voor verschillende integratiebronnen, heeft Azure Functions ook een set sjablonen voor uitvoerbindingen, zodat u eenvoudig gegevens naar gegevensbronnen kunt schrijven. Uitvoerbindingen kunnen ook worden geconfigureerd in het bestand function.json. Zoals u in deze oefening ziet, kunnen we onze functie configureren voor gebruik met meerdere gegevensbronnen en services.

Belangrijk

Deze oefening bouwt voort op de sandbox-resources en -resources die u in eerdere eenheden hebt gemaakt; met name de Azure Cosmos DB-database, bladwijzers en invoerbindingen. Als u de oefeningen in vorige lessen niet hebt voltooid, kunt u deze oefening niet voltooien.

Een met HTTP geactiveerde functie maken

Ga in Azure Portal naar de functie-app die u hebt gemaakt door de naam van de functie-app te selecteren in het breadcrumb-pad boven aan de functiepagina httpTrigger2 .
Op het tabblad Functies op de pagina Overzicht moet u de HTTP-triggerfuncties hebben die u hebt gemaakt.
Selecteer Maken op het tabblad Functions . Het deelvenster Functie maken wordt weergegeven.
Selecteer onder de sectie Selecteer een sjabloon de HTTP-trigger en selecteer vervolgens Maken. Het deelvenster Overzicht voor de functie HttpTrigger3 wordt weergegeven.

Een Azure Cosmos DB-invoerbinding toevoegen

Laten we nog een Azure Cosmos DB-invoerbinding toevoegen.

Selecteer Integratie in het menu HttpTrigger3-functie. Het deelvenster Integratie wordt weergegeven.
Selecteer Invoer toevoegen in het vak Invoer. Het deelvenster Invoer maken wordt weergegeven.
Selecteer Azure Cosmos DB in de vervolgkeuzelijst Bindingstype.
De verbindingsinstelling van het Cosmos DB-account moet vooraf worden ingevuld met de verbinding die u in de vorige oefening hebt gemaakt.

Als de verbinding niet wordt weergegeven, volgt u deze stappen om een nieuwe verbinding te maken.
1. Selecteer in de sectie Details van Azure Cosmos DB, onder de verbindingsinstelling van het Cosmos DB-account, de nieuwe koppeling.
2. Wanneer het dialoogvenster Nieuwe Cosmos DB-verbinding wordt weergegeven, selecteert u OK om de verbinding te maken. Er wordt een nieuwe Cosmos DB-accountverbinding gemaakt.

Voer de volgende waarden in voor de andere instellingen in dit deelvenster. Voor meer informatie over het doel van een instelling kunt u op elk gewenst moment het informatiepictogram rechts selecteren.

Instelling	Weergegeven als	Omschrijving
Parameternaam van document	`bookmark`	De naam voor het identificeren van deze binding in uw code.
Databasenaam	`func-io-learn-db`	De database om mee te werken. Dit is de databasenaam die u eerder in de les hebt ingesteld.
Verzamelingsnaam	`Bookmarks`	De naam van de verzameling waaruit gegevens worden gelezen. We hebben deze instelling eerder in de les gedefinieerd.
Document-id	`{id}`	Voeg `{id}` toe om de juiste bindingexpressie te gebruiken en accepteer de parameter die wordt doorgegeven in de querytekenreeks.
Partitiesleutel	`{id}`	Voeg opnieuw toe `{id}` om de juiste bindingsexpressie te gebruiken en accepteer de parameter die wordt doorgegeven in de querytekenreeks.
SQL-query (optioneel)	Leeg laten	Er wordt slechts één item tegelijk opgehaald op basis van de id. Filteren met de documentinstelling is dus beter dan het gebruik van een SQL-query in dit exemplaar. We kunnen een SQL-query maken die één vermelding retourneert (`SELECT * from b where b.ID = /id`). Deze query retourneert inderdaad een item, maar retourneert het in een itemsverzameling. De code moet dan een hele verzameling afhandelen, wat niet nodig is. Gebruik een SQL-query als u meerdere documenten wilt hebben.

Net als de invoerbinding die we in de vorige oefening hebben gemaakt, willen we een bladwijzer met een specifieke id opzoeken. Daarom hebben we de document-id gekoppeld die onze functie in de querytekenreeks ontvangt aan de binding, die de bindingexpressie wordt genoemd. De functietrigger is een HTTP-aanvraag die gebruikmaakt van een querytekenreeks om de id op te geven die moet worden opgezoekd. De binding retourneert 0 (niet gevonden) of 1 (gevonden) documenten.

Selecteer OK om de configuratie van de invoerbinding op te slaan.

U hebt nu een Azure Cosmos DB-invoerbinding. We gaan een uitvoerbinding toevoegen, zodat we nieuwe vermeldingen naar onze verzameling kunnen schrijven.

Een Cosmos DB-uitvoerbinding toevoegen

Selecteer uitvoer toevoegen in het deelvenster Integratie voor HttpTrigger3 in het vak Uitvoer. Het deelvenster Uitvoer maken wordt weergegeven.
Selecteer Azure Cosmos DB in de vervolgkeuzelijst onder Bindingstype.
De verbindingsinstelling van het Cosmos DB-account moet vooraf worden ingevuld met de verbinding die u eerder hebt gemaakt. Als dat niet het probleem is, vouwt u de vervolgkeuzelijst uit en selecteert u de verbinding die u hebt gedefinieerd voor httpTrigger3-invoerbinding.

Voer de volgende waarden in voor de resterende instellingen voor de uitvoerbinding.

Instelling	Weergegeven als	Omschrijving
Parameternaam van document	`newbookmark`	De naam voor het identificeren van deze binding in uw code. Deze parameter wordt gebruikt om een nieuwe bladwijzer te schrijven.
Databasenaam	`func-io-learn-db`	De database om mee te werken. Dit is de databasenaam die u eerder in de les hebt ingesteld.
Verzamelingsnaam	`Bookmarks`	De naam van de verzameling waaruit gegevens worden gelezen. Deze waarde is de containernaam die we eerder in de les hebben gedefinieerd.
Partitiesleutel	`/id`	Voeg de partitiesleutel toe die we hebben gedefinieerd toen we eerder de Azure Cosmos DB-container Bladwijzers maakten. De sleutel die hier is ingevoerd (opgegeven in de configuratie van de invoerbinding `<key>`) moet overeenkomen met de sleutel in de container.

Selecteer OK om deze uitvoerbindingsconfiguratie op te slaan.

We hebben nu een binding die moet worden gelezen uit onze verzameling en een binding om ernaar te schrijven.

Een uitvoerbinding voor Azure Queue Storage toevoegen

Azure Queue Storage is een service voor de opslag van berichten die overal vandaan kunnen worden opgevraagd. De grootte van één bericht kan maximaal 64 kB zijn en een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteit van het opslagaccount waarin het is gedefinieerd. In het volgende diagram ziet u op hoog niveau hoe een wachtrij in ons scenario wordt gebruikt.

Illustration showing a storage queue with a function pushing and another function popping messages.

In dit voorbeeld ziet u dat een functie met de naam add-bookmark berichten toevoegt aan een wachtrij, en een andere benoemde gen-qr-code berichten uit dezelfde wachtrij weergeeft en de aanvraag verwerkt. Omdat we berichten naar de wachtrij schrijven of pushen vanuit een bladwijzer toevoegen, voegen we een nieuwe uitvoerbinding toe aan uw oplossing.

We gaan de binding maken via de portal.

Selecteer uitvoer toevoegen in het deelvenster Integratie voor uw functie in het vak Uitvoer. Het deelvenster Uitvoer maken wordt weergegeven.
Selecteer Azure Queue Storage in de vervolgkeuzelijst Bindingstype.

Als er een bericht wordt weergegeven waarin u wordt gevraagd om de Microsoft.Azure.WebJobs.Extensions.Storage extensie te installeren, selecteert u Installeren en wacht u totdat deze is voltooid.

Vervolgens hebben we een opslagaccountverbinding ingesteld, waar onze wachtrij wordt gehost.

Onder Opslagaccountverbinding selecteert u Nieuwe. Het dialoogvenster Nieuwe opslagaccountverbinding wordt weergegeven.
Aan het begin van deze module, toen u uw functie-app maakte, is er ook een opslagaccount voor u gemaakt. Selecteer deze in de vervolgkeuzelijst en selecteer VERVOLGENS OK.

De verbindingsinstelling van het opslagaccount wordt gevuld met de naam van een verbinding.

Hoewel we de standaardwaarden kunnen behouden, gaan we enkele instellingen wijzigen om meer betekenis te geven aan de resterende eigenschappen.

Voltooi de instellingen in het deelvenster Uitvoer maken door de volgende oude waarden te vervangen door de nieuwe waarden:

Instelling	Oude waarde	Nieuwe waarde	Omschrijving
Naam van de berichtparameter	outputQueueItem	newmessage	De bindingseigenschap die we in code gebruiken.
Wachtrijnaam	outqueue	bookmarks-post-process	De naam van de wachtrij waarin we bladwijzers plaatsen, zodat een andere functie ze verder kan verwerken.

Selecteer OK om de uitvoerconfiguratie voor Azure Queue Storage op te slaan.

Functie-implementatie bijwerken

We hebben nu al onze bindingen ingesteld. Het is tijd om ze in de functie te gaan gebruiken.

Als u het bestand index.js in de code-editor wilt openen, selecteert u de functie HttpTrigger3.
Selecteer Code + Test in het menu onder Ontwikkelaars. Het deelvenster Code en test wordt weergegeven voor uw functie.

Vervang alle code in het bestand index.js door de code uit het volgende codefragment en selecteer opslaan in de opdrachtbalk.

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

Laten we eens gaan bekijken wat deze code precies doet:

Met deze functie worden onze gegevens gewijzigd. Daarom moet de HTTP-aanvraag een BERICHT zijn en moeten de bladwijzergegevens onderdeel zijn van de aanvraagbody.
De Azure Cosmos DB-invoerbinding probeert een document of bladwijzer op te halen met de id die we ontvangen. Als er een vermelding wordt gevonden, wordt het bookmark object ingesteld. Met de voorwaarde if(bookmark) wordt gecontroleerd of er vermeldingen zijn gevonden.
Toevoegen aan de database is net zo eenvoudig als het instellen van de context.bindings.newbookmark bindingsparameter op de nieuwe bladwijzervermelding, die we hebben gemaakt als een JSON-tekenreeks.
Als u berichten in de wachtrij wilt plaatsen, stelt u eenvoudigweg de parameter context.bindings.newmessage in.

Notitie

De enige taak die u hebt uitgevoerd, is een wachtrijbinding maken. De wachtrij zelf hebt u nooit expliciet gemaakt. Dit is de kracht van bindingen! Zoals de volgende melding aangeeft, wordt er automatisch een wachtrij gemaakt als er nog geen wachtrij bestaat.

Screenshot showing message that the queue will be auto-created. .

Dat was het. U kunt in de volgende sectie uw creatie in actie zien.

Als u het bestand run.ps1 in de code-editor wilt openen, selecteert u de functie HttpTrigger3 in de breadcrumb boven aan het deelvenster.
Selecteer Code + Test in het menu Functie onder Ontwikkelaar. Het deelvenster Code + Test voor de functie HttpTrigger3 wordt weergegeven, met de standaardinhoud van run.ps1.

Vervang de inhoud in het bestand door de volgende code.

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

Selecteer Opslaan op de opdrachtbalk. Er wordt een verbinding gemaakt en er wordt een logboekbestandssessie geopend.

Laten we eens gaan bekijken wat deze code precies doet:

Met deze functie worden onze gegevens gewijzigd. Daarom moet de HTTP-aanvraag een BERICHT zijn en moeten de bladwijzergegevens onderdeel zijn van de aanvraagbody.
Onze Azure Cosmos DB-invoerbinding probeert een document of bladwijzer op te halen met behulp van de id aanvraag. Als er een vermelding wordt gevonden, wordt het bookmark object ingesteld. Met de voorwaarde if ($bookmark) wordt gecontroleerd of er vermeldingen zijn gevonden.
Het toevoegen aan de database is net zo eenvoudig als het aanroepen van Push-OutputBinding met de naam van de Cosmos DB-uitvoerbinding (newbookmark) en de waarde van het $newBookmark-object.
Het posten van een bericht naar onze wachtrij is net zo eenvoudig als het aanroepen van Push-OutputBinding met de naam van de wachtrijuitvoerbinding (newmessage) en de waarde van het $newBookmark-object.

Notitie

Screenshot showing UI tool tip that the queue will be auto-created.

Dat was het. U kunt in de volgende sectie uw creatie in actie zien.

Probeer het zelf

Nu u over meerdere uitvoerbindingen beschikt, wordt het testen iets lastiger. In vorige lessen waren we inhoud om te testen door een HTTP-aanvraag met een querytekenreeks te verzenden, maar we willen deze keer een HTTP-bericht uitvoeren. U moet ook controleren of berichten in de wachtrij aankomen.

Selecteer Testen/uitvoeren in de opdrachtbalk van het deelvenster Code + Test voor de functie HttpTrigger3. Er wordt een nieuw deelvenster weergegeven, met het tabblad Invoer geopend, zoals wordt weergegeven in deze afbeelding:
Controleer in de vervolgkeuzelijst http-methode of POST is geselecteerd.

Vervang de inhoud van de aanvraagbody door het volgende JSON-object:

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

Selecteer Uitvoeren.
De programmatische voortgang wordt weergegeven in het deelvenster Logboeken . Wanneer dit is voltooid, controleert u of op het tabblad Uitvoer 'Bladwijzer bestaat al'. Dit gebeurt in de instelling voor de HTTP-antwoordinhoud .

U hebt het bladwijzeritem toegevoegd in Oefening: gegevens lezen met invoerbindingen. Het antwoord bevestigt dat uw var bookmark = context.bindings.bookmark JavaScript correct werkt en dat uw PowerShell-code dezelfde verbinding maakt.
Laten we een tweede bladwijzer posten in de database. Selecteer het tabblad Invoer .
Vervang de inhoud van de aanvraagbody door het volgende JSON-object:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Selecteer Uitvoeren.
Controleer of op het tabblad Uitvoer 'bladwijzer toegevoegd!' wordt weergegeven in de HTTP-antwoordinhoud, zoals wordt weergegeven in de volgende schermopname.

Gefeliciteerd! Uw functie werkt zoals ontworpen! Maar hoe zit het met de wachtrijbewerking die we aan de code hebben toegevoegd? Laten we eens gaan kijken of er iets naar een wachtrij is geschreven.

Controleren of er een bericht naar de wachtrij is geschreven

Azure Queue Storage-wachtrijen worden gehost in een opslagaccount. U hebt het opslagaccount geconfigureerd toen u de uitvoerbinding maakte.

Voer in de algemene zoekbalk van Azure Portal opslagaccounts in en selecteer vervolgens Opslagaccounts in de lijst met resultaten. Het deelvenster Opslagaccounts wordt weergegeven.
Selecteer het opslagaccount dat u hebt gebruikt om de newmessage-uitvoerbinding te configureren.
Selecteer in het menu Opslagaccount onder Gegevensopslag wachtrijen om de wachtrijen weer te geven die door dit opslagaccount worden gehost. Controleer of de wachtrij bladwijzers na het proces wordt weergegeven, zoals wordt weergegeven in de volgende schermopname.
Selecteer bladwijzers na het proces om de berichten in de wachtrij weer te geven. Als alles volgens plan is verlopen, bevindt zich in de wachtrij het bericht dat u hebt geplaatst toen u een bladwijzer aan de database toegevoegde. Het zou er als volgt moeten uitzien.

In dit voorbeeld heeft het bericht een unieke id gekregen en de kolom Berichttekst geeft uw bladwijzer weer in JSON-indeling. Er is geen bericht voor de Azure-bladwijzer docs die u probeerde toe te voegen, omdat deze al in de database bestond.
U kunt de functie verder testen door de aanvraagbody in het testvenster te wijzigen met nieuwe id/URL-sets en de functie uit te voeren. Kijk naar deze wachtrij terwijl er meer berichten aankomen. U kunt ook de database bekijken om te controleren of er nieuwe items zijn toegevoegd.

In deze oefening hebben we uw kennis van bindingen uitgebreid met uitvoerbindingen en gegevens naar uw Azure Cosmos DB geschreven. We hebben een uitvoerbinding toegevoegd om berichten te posten in een Azure-wachtrij. In dit voorbeeld ziet u de ware kracht van bindingen om u te helpen bij het vormgeven en verplaatsen van gegevens van binnenkomende bronnen naar verschillende bestemmingen. U hebt niet zelf databasecode geschreven en u hebt ook nog niet zelf verbindingsreeksen hoeven te beheren. In plaats daarvan hebben we bindingen declaratief geconfigureerd en kunnen we het platform laten zorgen voor het beveiligen van verbindingen, het schalen van onze functie en het schalen van onze verbindingen.

Doorgaan