Övning – Skriva data med utdatabindningar

15 minuter

I föregående övning implementerade vi ett scenario för att söka efter bokmärken i en Azure Cosmos DB-databas. Vi konfigurerade en indatabindning att läsa data från vår bokmärkessamling. Men vi kan göra mer. Vi utökar scenariot till att även omfatta dataskrivning. Titta på följande flödesschema:

Beslutsflödesdiagram som illustrerar processen med att lägga till ett bokmärke i Azure Cosmos DB-serverdelen och returnera ett svar.

I det här scenariot får vi begäranden om att lägga till bokmärken i vår samling. Begärandena skickas i önskad nyckel eller önskat ID tillsammans med bokmärkets URL. Som du ser i flödesschemat svarar vi med ett fel om nyckeln redan finns i vår serverdel.

Om nyckeln som skickades till oss inte hittas lägger vi till det nya bokmärket i databasen. Vi skulle kunna nöja oss här, men vi ska göra lite till.

Lägger du märke till ytterligare ett steg i flödesschemat? Hittills har vi inte gjort mycket med de data som vi fick när det gäller bearbetning. Vi flytta det som vi tar emot till en databas. Men i en verklig lösning skulle vi förmodligen bearbeta data på något sätt. Vi kan utföra all bearbetning i samma funktion, men i den här övningen visar vi ett mönster som avlastar ytterligare bearbetning till en annan komponent eller affärslogik.

Vad kan vara ett bra exempel på avlastning av arbete i vårt bokmärkesscenario? Så vad händer om vi skickar nytt bokmärke till en QR-kodgenererad tjänst? Tjänsten skulle i sin tur generera en QR-kod för URL:en, lagra avbildningen i Blob Storage och lägga till adressen till QR-avbildningen i posten i vår bokmärkessamling. Det är tidskrävande att anropa en tjänst för att generera en QR-avbildning. I stället för att vänta på resultatet lämnar vi uppgiften till en funktion och låter den slutföra den här uppgiften asynkront.

Precis som Azure Functions har stöd för indatabindningar för olika integreringskällor har det också en uppsättning mallar för utdatabindningar som gör det enkelt för dig att skriva data till datakällor. Utdatabindningar har även konfigurerats i function.json-filen. Som du ser i den här övningen kan vi konfigurera vår funktion så att den fungerar med flera datakällor och tjänster.

Viktigt!

Den här övningen bygger på sandbox-resurser och resurser som du skapade i tidigare enheter. mer specifikt Azure Cosmos DB-databasen, bokmärken och indatabindningar. Om du inte har slutfört övningarna i tidigare enheter kan du inte slutföra den här övningen.

Skapa en HTTP-utlöst funktion

I Azure Portal går du till funktionsappen som du skapade genom att välja namnet på funktionsappen i sökvägen till sökvägen längst upp på funktionssidan HttpTrigger2.
På fliken Funktioner på sidan Översikt bör du ha de HTTP-utlösarfunktioner som du har skapat.
Välj Skapa på fliken Funktioner . Fönstret Skapa funktion visas.
Under avsnittet Välj en mall väljer du HTTP-utlösare och sedan Nästa. Acceptera standardinställningarna på fliken Mallinformation och välj Skapa. Fönstret Översikt för funktionen HttpTrigger3 visas.

Lägga till en Azure Cosmos DB-indatabindning

Nu ska vi lägga till ytterligare en Azure Cosmos DB-indatabindning.

I menyn HttpTrigger3-funktion väljer du Integrering. Fönstret Integrering visas.
I rutan Utlösare och indata väljer du Lägg till indata. Fönstret Skapa indata visas.
I listrutan Bindningstyp väljer du Azure Cosmos DB.
Anslutningsinställningen för Cosmos DB-kontot bör fyllas i i förväg med den anslutning som du skapade i föregående övning.

Om du inte ser anslutningen i listan följer du de här stegen för att skapa en ny anslutning.
1. I avsnittet Azure Cosmos DB-information går du till inställningen för Cosmos DB-kontoanslutning och väljer länken Ny.
2. När dialogrutan Ny Cosmos DB-anslutning visas väljer du OK för att skapa anslutningen. En ny Cosmos DB-kontoanslutning skapas.

Ange följande värden för de andra inställningarna i det här fönstret. Om du vill veta mer om syftet med en inställning kan du när som helst välja informationsikonen till höger.

Inställning	Värde	beskrivning
Dokumentparameternamn	`bookmark`	Det namn som används för att identifiera den här bindningen i koden.
Databasnamn	`func-io-learn-db`	Databas att arbeta med. Det här värdet är det databasnamn som vi konfigurerade tidigare i den här lektionen.
Samlingsnamn	`Bookmarks`	Namnet på den samling som data läss från. Vi definierade den här inställningen tidigare i lektionen.
Dokument-ID	`{id}`	Lägg till `{id}` för att använda rätt bindningsuttryck och acceptera parametern som skickas i frågesträngen.
Partitionsnyckel	`{id}`	Lägg till `{id}` för att använda rätt bindningsuttryck och acceptera parametern som skickas i frågesträngen.
SQL-fråga (valfritt)	Lämna tomt	Vi hämtar bara ett objekt i taget baserat på ID:t. Därför är filtrering med inställningen Dokument bättre än att använda en SQL-fråga i den här instansen. Vi kan skapa en SQL-fråga för att returnera en post (`SELECT * from b where b.ID = /id`). Den frågan returnerar faktiskt ett objekt, men den returneras i en objektsamling. Vår kod skulle behöva ändra en samling i onödan. Använda SQL-frågemetoden när du vill hämta flera dokument.

Precis som den indatabindning som vi skapade i föregående övning vill vi slå upp ett bokmärke med ett specifikt ID, så vi kopplade dokument-ID:t som vår funktion tar emot i frågesträngen till bindningen, som kallas bindningsuttrycket. Funktionsutlösaren är en HTTP-begäran som använder en frågesträng för att ange det ID som ska slås upp. Bindningen returnerar antingen 0 -dokument (hittades inte) eller 1 (hittades).

Välj Lägg till för att spara indatabindningskonfigurationen.

Nu har vi en Azure Cosmos DB-indatabindning. Nu ska vi lägga till en utdatabindning så att vi kan skriva nya poster till vår samling.

Lägga till en Azure Cosmos DB-utdatabindning

I fönstret Integrering för HttpTrigger3 går du till rutan Utdata och väljer Lägg till utdata. Fönstret Skapa utdata visas.
Under Bindningstyp går du till listrutan och väljer Azure Cosmos DB.
Anslutningsinställningen för Cosmos DB-kontot bör fyllas i i förväg med den anslutning som du skapade tidigare. Om inte expanderar du listrutan och väljer den anslutning som du definierade för HttpTrigger3-indatabindning.

Ange följande värden för de återstående inställningarna för utdatabindningen.

Inställning	Värde	beskrivning
Dokumentparameternamn	`newbookmark`	Det namn som används för att identifiera den här bindningen i koden. Den här parametern används för att skriva en ny bokmärkespost.
Databasnamn	`func-io-learn-db`	Databas att arbeta med. Det här värdet är det databasnamn som vi konfigurerade tidigare i den här lektionen.
Samlingsnamn	`Bookmarks`	Namnet på den samling som data läss från. Det här värdet är containernamnet som vi definierade tidigare i lektionen.
Partitionsnyckel	`/id`	Lägg till partitionsnyckeln som vi definierade när vi skapade Azure Cosmos DB-containern Bokmärke tidigare. Nyckeln som anges här (anges i indatabindningskonfigurationen `<key>`) måste matcha den i containern.

Välj Lägg till för att spara den här konfigurationen för utdatabindning.

Nu har vi en bindning att läsa från vår samling och en bindning för att skriva till den.

Lägga till en Azure Queue Storage-utdatabindning

Azure Queue Storage är en tjänst för lagring av meddelanden som kan nås var som helst i världen. Storleken på ett enskilt meddelande kan vara så mycket som 64 KB och en kö kan innehålla miljontals meddelanden – upp till den totala kapaciteten för lagringskontot som kön definieras i. Följande diagram visar på hög nivå hur en kö används i vårt scenario.

Bild som visar en lagringskö med en funktion som push-överför och en annan funktion som poppar meddelanden.

I det här exemplet ser du att en funktion med namnet add-bookmark lägger till meddelanden i en kö, och en annan med namnet gen-qr-code visar meddelanden från samma kö och bearbetar begäran. Eftersom vi skriver eller push-överför meddelanden till kön från add-bookmark lägger vi till en ny utdatabindning i din lösning.

Nu ska vi skapa bindningen via portalen.

I fönstret Integrering för din funktion går du till rutan Utdata och väljer Lägg till utdata. Fönstret Skapa utdata visas.
I listrutan Bindningstyp väljer du Azure Queue Storage.

Om ett meddelande visas där du uppmanas att installera Microsoft.Azure.WebJobs.Extensions.Storage tillägget väljer du installera och väntar tills det har slutförts.

Därefter konfigurerar vi en anslutning till lagringskontot, där vår kö finns.

Under Lagringskontoanslutning väljer du Nytt. Dialogrutan Ny lagringskontoanslutning visas.
I början av den här modulen skapades även ett lagringskonto åt dig när du skapade funktionsappen. Välj den i listrutan och välj sedan OK.

Inställningen För lagringskontoanslutning fylls i med namnet på en anslutning.

Även om vi kan behålla standardvärdena ska vi ändra vissa inställningar för att ge de återstående egenskaperna mer betydelse.

Slutför inställningarna i fönstret Skapa utdata genom att ersätta följande gamla värden med de nya värdena:

Inställning	Gammalt värde	Nytt värde	beskrivning
Meddelandeparameternamn	outputQueueItem	newmessage	Bindningsegenskapen som vi använder i kod.
Könamn	outqueue	bookmarks-post-process	Namnet på kön där vi placerar bokmärken så att en annan funktion kan bearbeta dem ytterligare.

Välj Lägg till för att spara utdatakonfigurationen för Azure Queue Storage.

Uppdatera funktionsimplementeringen

Nu har alla våra bindningar upprättats. Nu är det dags att använda dem i vår funktion.

Om du vill öppna filen index.js i kodredigeraren väljer du funktionen HttpTrigger3.
I menyn väljer du Kod + Test. Fönstret Kod + test visas för din funktion.

Ersätt all kod i index.js-filen med koden från följande kodavsnitt och välj sedan Spara i kommandofältet.

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

Nu ska vi analysera på detaljnivå vad den här koden gör:

Eftersom den här funktionen förändrar våra data kan vi förvänta oss att HTTP-begäran är en POST och att bokmärkesdata ska ingå i begärandetexten.
Vår Azure Cosmos DB-indatabindning försöker hämta ett dokument eller ett bokmärke med hjälp av den id som vi tar emot. Om den hittar en post anges objektet bookmark . Villkoret if(bookmark) kontrollerar om en post hittades.
Att lägga till i databasen är lika enkelt som att ange bindningsparametern context.bindings.newbookmark till den nya bokmärkesposten, som vi skapade som en JSON-sträng.
Att skicka ett meddelande till vår kö är lika enkelt som att konfigurera context.bindings.newmessage-parametern.

Kommentar

Den enda aktivitet som du utförde var att skapa en köbindning. Du skapade aldrig kön uttryckligen. Du har nu sett hur kraftfulla bindningar är! Precis som följande meddelande anger skapas kön automatiskt åt dig om den inte finns.

Skärmbild som visar meddelande om att kön skapas automatiskt. .

Välj function.json i listrutan i sökvägen <functionapp> \ HttpTrigger3 \ och gör följande ändringar:
1. Ändra alla instanser av "collectionName" till "containerName".
2. Ändra alla instanser av "connectionStringSetting" till "connection".
3. Ta bort referenserna till "methods": [].

Den sista function.json filen bör likna den här koden.

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

I kommandofältet väljer du Spara.

Klart! Låt oss titta på vårt arbete i praktiken i nästa avsnitt.

Om du vill öppna filen run.ps1 i kodredigeraren väljer du funktionen HttpTrigger3 från sökvägen längst upp i fönstret.
På funktionsmenyn under Utvecklare väljer du Kod + Test. Fönstret Kod + test för din HttpTrigger3-funktion visas och standardinnehållet i run.ps1 visas.

Ersätt innehållet i filen med följande kod.

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älj Spara i kommandofältet. En anslutning upprättas och en loggfilsession öppnas.

Nu ska vi analysera på detaljnivå vad den här koden gör:

Eftersom den här funktionen förändrar våra data kan vi förvänta oss att HTTP-begäran är en POST och att bokmärkesdata ska ingå i begärandetexten.
Vår Azure Cosmos DB-indatabindning försöker hämta ett dokument eller bokmärke med hjälp id av i begäran. Om den hittar en post anges objektet bookmark . Villkoret if ($bookmark) kontrollerar om en post hittades.
Att lägga till i databasen är lika enkelt som att anropa Push-OutputBinding med namnet på Cosmos DB-utdatabindningen (newbookmark) och värdet för $newBookmark-objektet.
Att publicera ett meddelande till vår kö är lika enkelt som att anropa Push-OutputBinding med namnet på utdatabindningen (newmessage) för kön och värdet för $newBookmark-objektet.

Kommentar

Skärmbild som visar tipset för användargränssnittsverktyget om att kön skapas automatiskt.

Klart! Låt oss titta på vårt arbete i praktiken i nästa avsnitt.

Prova nu

Nu när vi har flera utdatabindningar blir testen lite svårare. I tidigare enheter var vi nöjda med att testa genom att skicka en HTTP-begäran med en frågesträng, men vi vill utföra ett HTTP-inlägg den här gången. Vi måste också kontrollera om meddelandena kommer fram till kön.

I kommandofältet i fönstret Kod + Test för din HttpTrigger3-funktion väljer du Test/Kör. Ett nytt fönster visas, med fliken Indata öppen, som du ser i den här bilden:
I listrutan HTTP-metod kontrollerar du att POST är markerat.

Ersätt innehållet i begärandetexten med följande JSON-objekt:

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

Markera Kör.
Den programmatiska förloppet visas i fönstret Loggar . När du är klar kontrollerar du att fliken Utdata visar "Bokmärket finns redan" i innehållsinställningen HTTP-svar.

Du har lagt till bokmärkesobjektet i Övning – Läsa data med indatabindningar. Svaret bekräftar att JavaScript var bookmark = context.bindings.bookmark fungerar korrekt och att din PowerShell-kod gör samma anslutning.
Nu ska vi publicera ett andra bokmärke i databasen. Välj fliken Indata .
Ersätt innehållet i begärandetexten med följande JSON-objekt:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Markera Kör.
Kontrollera att fliken Utdata visar "bokmärke har lagts till!" i HTTP-svarsinnehållet, enligt följande skärmbild.

Grattis! Din funktion fungerar som den är utformad! Men hur är det med köåtgärden som vi lade till i koden? Så nu ska vi se om något har skrivits till en kö.

Kontrollera att ett meddelande skrivs till vår kö

Azure Queue Storage-köer finns på ett lagringskonto. Du konfigurerade lagringskontot när du skapade utdatabindningen.

I fältet Azure Portal global sökning anger du lagringskonton och väljer sedan Lagringskonton i resultatlistan. Fönstret Lagringskonton visas.
Välj det lagringskonto som du använde för att konfigurera utdatabindningen newmessage .
I menyn Lagringskonto går du till Datalagring och väljer Köer för att visa en lista över köer som hanteras av det här lagringskontot. Kontrollera att kön bookmarks-post-process visas enligt följande skärmbild.
Välj bookmarks-post-process för att visa de meddelanden som finns i kön. Om allt gått enligt planen innehåller kön meddelandet som du har skapade när du skickade ett bokmärke till databasen. Det ska se ut som i följande exempel.

I det här exemplet fick meddelandet ett unikt ID och kolumnen Meddelandetext visar ditt bokmärke i JSON-format. Det finns inget meddelande för Azure-bokmärket docs som du försökte lägga till eftersom det redan fanns i databasen.
Du kan testa funktionen ytterligare genom att ändra begärandetexten i testfönstret med nya ID/URL-uppsättningar och köra funktionen. Titta på den här kön för att se fler meddelanden tas emot. Du kan också titta på databasen för att kontrollera att nya poster har lagts till.

I den här övningen utökade vi dina kunskaper om bindningar till utdatabindningar och skrev data till din Azure Cosmos DB. Vi har lagt till en utdatabindning för att publicera meddelanden i en Azure-kö. Det här exemplet visar den verkliga kraften i bindningar som hjälper dig att forma och flytta data från inkommande källor till olika mål. Vi behövde inte skriva någon databaskod eller hantera anslutningssträng själva. I stället konfigurerade vi bindningar deklarativt och låter plattformen ta hand om att skydda anslutningar, skala vår funktion och skala våra anslutningar.