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. We hebben een invoerbinding geconfigureerd om gegevens te lezen uit onze verzameling bladwijzers. Maar we kunnen meer doen. We gaan het scenario uitbreiden zodat er ook wordt geschreven. Kijk eens naar het volgende stroomdiagram:

Beslissingsstroomdiagram dat het proces illustreert van het toevoegen van een bladwijzer in de back-end van Azure Cosmos DB en het retourneren van een antwoord.

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 stroomschema kunt zien, geven we een foutmelding als de sleutel al bestaat in onze backend.

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 laten we nog een beetje meer doen.

Ziet u de volgende stap in het stroomdiagram? Tot nu toe hebben we niet veel gedaan met de gegevens die we hebben 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. In deze oefening laten we echter een patroon zien waarmee verdere verwerking wordt overgedragen aan een ander onderdeel of stuk bedrijfslogica.

Wat kan een goed voorbeeld zijn van het uitbesteden van werk in ons scenario met bladwijzers? Wat zou er gebeuren als we de nieuwe bladwijzer naar een service voor het maken van QR-codes versturen? Deze service genereert 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 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 nog niet hebt voltooid, kunt u deze oefening niet voltooien.

Een met HTTP geactiveerde functie maken

Ga in de 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 sjabloonde HTTP-trigger en selecteer vervolgens Volgende. Accepteer de standaardwaarden op het tabblad Details van sjabloon en selecteer 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 Trigger en 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	Waarde	Beschrijving
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 verzameling van items. 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 ofwel 0 (niet gevonden) of 1 (gevonden) document.

Selecteer Toevoegen 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 items aan onze verzameling kunnen toevoegen.

Een Cosmos DB-uitvoerbinding toevoegen

Selecteer uitvoer toevoegen in het deelvenster Integratie voor HttpTrigger3 in het vak Uitvoer. Het deelvenster Create Output 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	Waarde	Beschrijving
Parameternaam van document	`newbookmark`	De naam voor het identificeren van deze binding in uw code. Deze parameter wordt gebruikt om een nieuwe bladwijzer toe te voegen.
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 Toevoegen om deze uitvoerbindingsconfiguratie op te slaan.

We hebben nu een binding om uit onze verzameling te lezen en een binding om erin 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 de wachtrij is gedefinieerd. In het volgende diagram ziet u op hoog niveau hoe een wachtrij in ons scenario wordt gebruikt.

Afbeelding van een opslagwachtrij met een functiepush en een andere functie die berichten weergeeft.

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 laat verschijnen en de aanvraag verwerkt. Omdat we berichten naar de wachtrij schrijven of pushen vanuit add-bookmark, 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 Create Output 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	Beschrijving
Naam van de berichtparameter	uitvoerwachtrij-item	nieuw bericht	De bindingseigenschap die we in code gebruiken.
Wachtrijnaam	uitvoerwachtrij	bladwijzers-na-verwerking	De naam van de wachtrij waarin we bladwijzers plaatsen, zodat een andere functie ze verder kan verwerken.

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

Functie-implementatie bijwerken

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

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

Vervang alle code in het index.js-bestand door de code uit het volgende codefragment. 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:

Omdat deze functie onze gegevens wijzigt, verwachten we dat de HTTP-aanvraag een POST is en dat de bladwijzergegevens deel uitmaken 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. Je bent getuige van de kracht van bindingen! Zoals de volgende melding aangeeft, wordt er automatisch een wachtrij gemaakt als er nog geen wachtrij bestaat.

Schermopname van het bericht dat de wachtrij automatisch wordt gemaakt. .

Selecteer function.json in de vervolgkeuzelijst in uw <functionapp> \ HttpTrigger3 \ pad en breng de volgende wijzigingen aan:
1. Wijzig alle gevallen van "collectionName" in "containerName".
2. Wijzig alle gevallen van "connectionStringSetting" in "connection".
3. Verwijder de verwijzingen naar "methods": [].

Het uiteindelijke function.json-bestand moet lijken op deze code.

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

Selecteer Opslaan op de opdrachtbalk.

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. 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:

Omdat deze functie onze gegevens wijzigt, verwachten we dat de HTTP-aanvraag een POST is en dat de bladwijzergegevens deel uitmaken van de aanvraagbody.
Om een document of bladwijzer op te halen, probeert onze Azure Cosmos DB-invoerbinding dit met behulp van de id in het verzoek. 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

Schermopname van de interface-tip dat de wachtrij automatisch zal worden aangemaakt.

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 tevreden met testen door een HTTP-verzoek met een querystring te verzenden, maar we willen deze keer een HTTP-post doen. We moeten ook controleren of berichten in de wachtrij terechtkomen.

Selecteer Test/Run 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 UitvoerBladwijzer bestaat al. wordt weergegeven 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 de tekst 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 opslagaccounts in de algemene zoekbalk van Azure Portal in. Selecteer vervolgens de optie 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 vermeldingen worden toegevoegd.

In deze oefening hebben we uw kennis van bindingen uitgebreid met uitvoerbindingen en het schrijven van gegevens naar uw Azure Cosmos DB. 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. We hoeven geen databasecode te schrijven of verbindingsreeks zelf 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.