Övning – Läsa data med indatabindningar

20 minuter

Anta att du vill skapa en uppslagstjänst för bokmärken. Till en början är tjänsten skrivskyddad. Om användarna vill hitta en post skickar de en begäran med postens ID och vår funktion returnerar URL:en. Följande flödesschema illustrerar det logiska flödet.

När en användare skickar en begäran med text försöker funktionen hitta bokmärket för att hitta en post i databasen som innehåller ett bokmärke med texten som en nyckel eller ett ID. Systemet returnerar ett resultat som anger om du hittade posten.

När Azure-funktionen tar emot en begäran med ett bokmärkes-ID kontrollerar den först om begäran är giltig. Om det inte är det genereras ett felsvar. Om begäran är giltig kontrollerar funktionen om bokmärkes-ID:t finns i Azure Cosmos DB-databasen. Om den inte finns genereras ett felsvar. Om bokmärkes-ID:t hittas visas ett svar om att åtgärden lyckades.

Du måste lagra data någonstans. I det tidigare flödesschemat är datalagret en Azure Cosmos DB-instans. Men hur ansluter du till en databas från en funktion och läser data? I en värld av funktioner konfigurerar du en indatabindning för jobbet. Det är enkelt att konfigurera en indatabindning via Azure Portal. Som du snart ser behöver du inte skriva kod eller öppna en lagringsanslutning. Azure Functions-körningen och bindningar tar hand om de här uppgifterna åt dig.

Skapa ett Azure Cosmos DB-konto

Kommentar

Den här övningen är inte avsedd att vara en självstudie om Azure Cosmos DB. Om du är intresserad av att lära dig mer kan du läsa den fullständiga utbildningsvägen om Azure Cosmos DB i slutet av den här modulen.

Skapa ett databaskonto

Ett databaskonto är en container för hantering av en eller flera databaser. Innan vi kan skapa en databas behöver vi skapa ett databaskonto.

På resursmenyn Azure Portal eller på startsidan väljer du Skapa en resurs. Fönstret Skapa en resurs visas.
I menyn Skapa en resurs väljer du Databaser och söker sedan efter och väljer Azure Cosmos DB. Fönstret Vilket API passar bäst för din arbetsbelastning? visas.
I alternativet Azure Cosmos DB for NoSQL väljer du Skapa så att vi kan skapa en Cosmos DB-utlösare och indata-/utdatabindningar. Fönstret Skapa Azure Cosmos DB-konto – Azure Cosmos DB för NoSQL visas.

På fliken Grundläggande anger du följande värden för varje inställning.

Inställning	Värde	beskrivning
Projektinformation
Prenumeration	Concierge-prenumeration	Den Azure-prenumeration som fungerar med resurserna i sandbox-miljön.
Resursgrupp	I listrutan väljer du [resursgruppsnamn för sandbox-miljö]	Resursgruppen för sandbox-miljön.
Instansinformation
Kontonamn	`globally unique name`	Ange ett unikt men identifierbart namn för ditt Azure Cosmos DB-konto. `documents.azure.com` läggs till i det namn som du anger. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Plats	`region`	Välj den region som är närmast dig.

Acceptera standardvärdena för de återstående inställningarna och välj Granska + skapa för att verifiera dina indata. Ett meddelande om valideringsframgång visas.
Välj Skapa för att etablera och distribuera ett databaskonto.
Distributionen kan ta lite tid. Vänta tills ett distributionsmeddelande har slutförts i meddelandehubben innan du fortsätter.
Välj Gå till resurs för att gå till databaskontot i portalen. Fönstret Snabbstart för ditt Azure Cosmos DB-konto visas.

Därefter lägger vi till en container och lägger sedan till en databas till Azure Cosmos DB-kontot.

Lägga till en container

I en Azure Cosmos DB används en container för att lagra olika användargenererade entiteter, även kallade objekt. Vi skapar en container med namnet Bokmärken.

Nu ska vi använda datautforskaren för att skapa en databas och container.

Välj Datautforskaren i azure Cosmos DB-kontomenyn. Fönstret Datautforskaren för ditt Cosmos DB-konto visas.
Välj rutan Ny container . Fönstret Ny container visas. Du kan behöva rulla för att se den.

Ange följande värden för varje inställning.

Inställning	Värde	beskrivning
Databas-ID	Välj Skapa ny och ange func-io-learn-db för databas-ID:t	Databasnamn kan vara mellan 1 och 255 tecken långa och får inte innehålla `/, \\, #, ?`, eller ett avslutande blanksteg. Du kan ange vad du vill, men vi använder func-io-learn-db i den här modulen.
Databas max RU/s	4000	Acceptera standarddataflödet på 4 000 enheter för begäranden per sekund (RU/s). Om du vill minska svarstiden kan du skala upp prestandan senare.
Container-ID	Bokmärken	För container-ID:n gäller samma teckenkrav som för databasnamn. Vi använder bokmärken i den här modulen.
Partitionsnyckel	/id	Partitionsnyckeln anger hur dokument i Azure Cosmos DB-samlingar är distribuerade mellan olika logiska datapartitioner. Vi använder inställningen Partitionsnyckel som en bekvämlighet här eftersom vi inte bryr oss om databasprestanda i den här modulen. Mer information om partitionsnyckelstrategier för Azure Cosmos DB finns i Microsoft Learn Azure Cosmos DB-modulerna.

Acceptera standardinställningarna för alla andra inställningar.

Rulla längst ned i fönstret och välj OK. Tillåt några minuter för att databasen och containern ska skapas.

När du är klar visar Datautforskaren func-io-learn-db i DATA under NOSQL API.
Välj func-io-learn-db för att expandera den. Observera att databasen func-io-learn-db innehåller flera underordnade medlemmar, inklusive Skala och Bokmärken.
Expandera containern Bokmärken . Observera att flera underordnade medlemmar redan fyller i den i förväg.

I nästa uppgift lägger du till vissa data, även kallade objekt, i containern Bokmärken.

Lägga till testdata

Du vill lägga till data i containern Bokmärken . Använd Datautforskaren för att lagra en URL och ett ID för varje objekt.

Expandera databasen func-io-learn-db och containern Bookmarks och välj sedan Objekt. Fliken Objekt visas.
I kommandofältet väljer du Nytt objekt.

Ersätt standardkoden för det nya objektet med följande JSON-kod.

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

I kommandofältet väljer du Spara.

Observera att fler egenskaper än de två rader som vi lade till visas. Alla börjar med en understrykning (_rid, _self, _etag, _attachments, _ts). Dessa egenskaper, som beskrivs i följande tabell, genereras system för att hantera de objekt som du lägger till i containern.

Property	beskrivning
`_rid`	Resurs-ID är en unik identifierare som också är hierarkisk per resursstacken i resursmodellen. ID:t används internt för placering och navigering av objektresursen.
`_self`	Unik adresserbar URI för resursen.
`_etag`	Krävs för optimistisk samtidighetskontroll.
`_attachments`	Adresserbar sökväg för resursen för bifogade filer.
`_ts`	Tidsstämpel för den senaste uppdateringen av den här resursen.

Nu ska vi lägga till några fler objekt i containern Bokmärken . I kommandofältet väljer du Nytt objekt. Skapa ytterligare fyra objekt med följande innehåll. Lägg till objekten genom att välja Nytt objekt och välj sedan Spara när du har kopierat och klistrat in varje nytt objekt. Observera hur varje objekt läggs till i listan med objekt.
```
{
    "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"
}
```
När du har angett bokmärkesdata bör containern se ut som följande bild.

Containern Bokmärken har fem objekt. I det här scenariot, om en begäran kommer med "id=docs", letar den upp det ID:t i containern Bokmärken och returnerar URL:en https://learn.microsoft.com/azure. Nu ska vi skapa en Azure-funktion som söker efter värden i containern Bokmärken.

Skapa din funktion

Gå till funktionsappen som du skapade i föregående lektion. I resursmenyn väljer du Start, och i avsnittet Senaste resurser bör du se din funktionsapp (Typ är lika med funktionsapp). Välj din funktionsapp. Fönstret Funktionsapp visas.
På fliken Funktioner på sidan Översikt bör du ha en funktion, HttpTrigger1.
Nu ska vi skapa en annan funktion. Välj Skapa på fliken Funktioner . Fönstret Skapa funktion visas med mallar för utlösare som stöds.
I avsnittet Välj en mall väljer du HTTP-utlösare och sedan Nästa.
Acceptera alla standardinställningar och välj Skapa för att skapa funktionen.

Fönstret Översikt för funktionen HttpTrigger2 visas.

Verifiera funktionen

Du kan verifiera våra framsteg hittills genom att testa den nya funktionen.

I kommandofältet väljer du Hämta funktions-URL. Dialogrutan Hämta funktions-URL visas.
Välj standard (funktionsnyckel) i listrutan, välj sedan ikonen Kopiera till Urklipp och välj OK.
Klistra in funktions-URL:en som du kopierade till adressfältet på en ny webbläsarflik. Lägg till frågesträngsvärdet &name=<your name> i slutet av URL:en, ersätt <your name> med ditt namn och tryck sedan på Retur. Azure-funktionen bör returnera ett personligt svar i webbläsaren.

Nu när vi har vår skelettfunktion igång ska vi fokusera på att läsa data från din Azure Cosmos DB, eller i vårt scenario, från din bokmärkescontainer .

Lägga till en Azure Cosmos DB-indatabindning

Du måste definiera en indatabindning om du vill kuna läsa data från databasen. Som du ser här kan du konfigurera en bindning som kan kommunicera med databasen i bara några få steg.

I Azure Portal går du till menyn HttpTrigger2-funktion längst upp och väljer Integrering. Fönstret Integrering för funktionen visas.

Du använde en mall som skapade en HTTP-utlösarbegäran med en HTTP-utdatabindning. Nu ska vi lägga till en Azure Cosmos DB-indatabindning.
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.
I avsnittet Azure Cosmos DB-information går du till inställningen för Cosmos DB-kontoanslutning och väljer länken Ny. Dialogrutan Ny Cosmos DB-anslutning visas.

Om ett meddelande visas där du uppmanas att installera tillägget Microsoft.Azure.WebJobs.Extensions.CosmosDB väljer du Installera och väntar tills det har slutförts.
Som standard identifierar Azure det Azure Cosmos DB-konto som du skapade tidigare. Välj OK för att konfigurera en anslutning till databasen. En ny anslutning till databaskontot konfigureras och visas i fältet Cosmos DB-kontoanslutning .

Vi vill slå upp ett bokmärke med ett specifikt ID, så vi kopplar det ID som vi får i frågesträngen till bindningen.

Nu ska vi slutföra inställningarna i fönstret Skapa indata . Ange följande värden för varje inställning. Om du vill veta mer om syftet med varje inställning väljer du informationsikonen i fältet.

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 anger.
Samlingsnamn	`Bookmarks`	Samlingen vi läste data från. Den här inställningen har definierats.
Dokument-ID	`id`	Lägg till det dokument-ID som vi definierade när vi skapade Azure Cosmos DB-containern Bokmärken .
Partitionsnyckel	`/id`	Lägg till partitionsnyckeln som du definierade när du skapade Azure Cosmos DB-samlingen Bokmärken . Nyckeln du anger här (anges i inmatningsbundet format `<key>`) måste matcha nyckeln i samlingen.
SQL-fråga (valfritt)	Lämna tomt	Du hämtar bara ett dokument i taget baserat på ID:t. Därför är filtrering med inställningen Dokument-ID bättre än att använda en SQL-fråga i den här instansen. Du kan skapa en SQL-fråga för att returnera en post (`SELECT * from b where b.ID = id`). Frågan skulle verkligen returnera ett dokument, men den skulle returnera det i en dokumentsamling. Din kod skulle behöva ändra en samling i onödan. Använda SQL-frågemetoden när du vill hämta flera dokument.

För att klargöra varför vi använder de här inställningarna 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 indatabindningen. Den här syntaxen kallas för ett bindningsuttryck. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange vilket ID som ska sökas upp. Eftersom ID:t är unika i vår samling returnerar bindningen antingen 0 (hittades inte) eller 1 (hittades).

Om du vill spara den här indatabindningskonfigurationen väljer du Lägg till.

Uppdatera funktionsimplementeringen

Nu när bindningen har definierats kan du använda den i din funktion. Du måste göra två ändringar för att implementera bindningen som du skapade:

Ändra funktionens språkspecifika implementeringskod. Den måste avgöra om ett dokument hittades i databasen som matchar det ID som skickas till funktionen.
Ändra funktionens JSON-implementeringskod så att den accepterar en parameter som skickas i frågesträngen.

Ändra javascript-implementeringskoden för funktionen

I funktionsmenyn för din HttpTrigger2-funktion väljer du Kod + Test. Fönstret Kod + test visas för funktionen HttpTrigger2 .

Ersätt all kod i filen index.js med följande kod.

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

I kommandofältet väljer du Spara. Välj Filsystemloggar i listrutan längst upp i mitten av loggfönstret (som visar App Insights-loggar som standard). Fönstret Loggar visas och visar att du har Connected!

Nu ska vi undersöka vad den här koden gör.

En inkommande HTTP-begäran utlöser funktionen, och en id-frågeparameter skickas till Azure Cosmos DB-indatabindningen.
Om databasen hittar ett dokument som matchar det här ID:t anges parametern bookmark till det dokument som finns.

I det här exemplet skapar koden ett svar som innehåller det URL-värde som finns i motsvarande dokument i databasen.
Om inget dokument hittas som matchar den här nyckeln svarar begäran med en nyttolast och statuskod som meddelar användaren de dåliga nyheterna.

Ändra funktionens JSON-implementeringskod

Välj function.json i listrutan i sökvägen <functionapp> \ HttpTrigger2 \ .

Ersätt all kod i filen function.json med följande kod. Se till att ersätta your-database med namnet på ditt Azure Cosmos DB-konto.

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

I kommandofältet väljer du Spara.

Ändra funktionens PowerShell-implementeringskod

I funktionsmenyn för din HttpTrigger2-funktion väljer du Kod + Test. Fönstret Kod + test visas för funktionen HttpTrigger2 och run.ps1 visar filen.

Ersätt all kod i run.ps1 filen med följande kod.

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

I kommandofältet väljer du Spara. Välj Filsystemloggar i listrutan längst upp i mitten av loggfönstret (som visar App Insights-loggar som standard). Fönstret Loggar visas och visar att du har Connected!

Nu ska vi undersöka vad den här koden gör.

En inkommande HTTP-begäran utlöser funktionen, och en id-frågeparameter skickas till Azure Cosmos DB-indatabindningen.
Om databasen hittar ett dokument som matchar det här ID:t anges parametern bookmark till det dokument som finns.

I det här exemplet skapar koden ett svar som innehåller det URL-värde som finns i motsvarande dokument i databasen.
Om inget dokument hittas som matchar den här nyckeln svarar begäran med en nyttolast och statuskod som meddelar användaren de dåliga nyheterna.

Ändra funktionens JSON-implementeringskod

Välj function.json i listrutan i sökvägen <functionapp> \ HttpTrigger2 \ .

Ändra värdena för id och partitionKey så att de accepterar en parameter av {id}. Din function.json-kod bör likna följande exempel, där your-database ersätts med namnet på cosmos DB-databasen.

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

I kommandofältet väljer du Spara.

Prova nu

Du bör redan vara i fönstret Kod + test för din HttpTrigger2-funktion .
I kommandofältet väljer du Hämta funktions-URL. Dialogrutan Hämta funktions-URL visas.
I listrutan Nyckel väljer du standard under Funktionsnyckel och väljer sedan ikonen Kopiera till Urklipp i slutet av URL:en.
Klistra in funktionsnyckeln som du kopierade till adressfältet på en ny webbläsarflik och lägg sedan till frågesträngsvärdet &id=docs i slutet av URL:en. Den resulterande URL:en bör likna följande exempel:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Tryck på Retur för att köra begäran. Svaret som returneras av funktionen bör likna följande exempel.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Ersätt &id=docs med &id=missing, tryck på Retur och observera svaret. Vi definierade fem bokmärken och skapade ett meningsfullt felsvar om det begärda bokmärket inte finns.

I den här lektionen skapade du din första indatabindning manuellt för att kunna läsa från en Azure Cosmos DB-databas. Mängden kod som du skrev för att söka i databasen och läsa data var minimal, tack vare bindningarna. Du gjorde det mesta av ditt arbete med att konfigurera bindningen deklarativt, och plattformen tog hand om resten.

I nästa lektion lägger du till fler data i bokmärkessamlingen via en Azure Cosmos DB-utdatabindning.

Övning – Läsa data med indatabindningar

Skapa ett Azure Cosmos DB-konto

Skapa ett databaskonto

Lägga till en container

Lägga till testdata

Skapa din funktion

Verifiera funktionen

Lägga till en Azure Cosmos DB-indatabindning

Uppdatera funktionsimplementeringen

Ändra javascript-implementeringskoden för funktionen

Ändra funktionens JSON-implementeringskod

Ändra funktionens PowerShell-implementeringskod

Ändra funktionens JSON-implementeringskod

Prova nu

Feedback