Oefening: gegevens lezen met invoerbindingen

20 minuten

Stel dat u een opzoekservice voor bladwijzers wilt maken. In eerste instantie is uw service alleen-lezen. Als gebruikers een vermelding willen vinden, verzenden ze een aanvraag met de id van de vermelding en retourneert onze functie de URL. Het volgende stroomdiagram illustreert de logische stroom.

Wanneer een gebruiker een aanvraag met tekst verzendt, probeert de functie bladwijzer zoeken naar een vermelding in uw database die een bladwijzer bevat met de tekst als sleutel of id. Het systeem retourneert een resultaat dat aangeeft of u de vermelding hebt gevonden.

Wanneer de Azure-functie een aanvraag met een bladwijzer-id ontvangt, wordt eerst gecontroleerd of de aanvraag geldig is. Als dit niet het probleem is, wordt er een foutbericht gegenereerd. Als de aanvraag geldig is, controleert de functie of de bladwijzer-id bestaat in de Azure Cosmos DB-database. Als deze niet bestaat, wordt er een foutbericht gegenereerd. Als de id van de bladwijzer wordt aangetroffen, wordt een bericht gegenereerd dat dit aangeeft.

De gegevens moeten ergens worden opgeslagen. In het vorige stroomdiagram is het gegevensarchief een Azure Cosmos DB-exemplaar. Maar hoe maakt u vanuit een functie verbinding met een database en leest u gegevens? In de wereld van functies gaat u een invoerbinding voor die taak configureren. Het configureren van een invoerbinding via Azure Portal is eenvoudig. Zoals u binnenkort ziet, hoeft u geen code te schrijven of een opslagverbinding te openen. Deze taken worden voor u verwerkt via Azure Functions-runtime en -bindingen.

Een Azure Cosmos DB-account maken

Notitie

Deze oefening is niet bedoeld als zelfstudie over Azure Cosmos DB. Als u meer wilt weten, raadpleegt u het volledige leertraject over Azure Cosmos DB aan het einde van deze module.

Een databaseaccount maken

Een databaseaccount is een container voor het beheren van een of meer databases. Voordat we een database kunnen maken, moeten we een databaseaccount maken.

Selecteer een resource maken in het resourcemenu van Azure Portal of op de startpagina. Het deelvenster Een resource maken wordt weergegeven.
Selecteer databases in het menu Een resource maken en zoek en selecteer Vervolgens Azure Cosmos DB. Het deelvenster Welke API past het beste bij uw workload? wordt weergegeven.
Selecteer Maken in de optie Azure Cosmos DB for NoSQL, zodat we een Cosmos DB-trigger en invoer-/uitvoerbindingen kunnen maken. Het deelvenster Azure Cosmos DB-account maken - Azure Cosmos DB voor NoSQL wordt weergegeven.

Voer op het tabblad Basisinformatie de volgende waarden in voor elke instelling.

Instelling	Weergegeven als	Beschrijving
Projectgegevens
Abonnement	Concierge-abonnement	Het Azure-abonnement dat werkt met de resources in de sandbox.
Resourcegroep	Selecteer in de vervolgkeuzelijst [naam sandbox-resourcegroep]	De resourcegroep voor uw sandbox.
Exemplaardetails
Accountnaam	`globally unique name`	Voer een unieke maar identificeerbare naam in voor uw Azure Cosmos DB-account; `documents.azure.com` wordt toegevoegd aan de naam die u opgeeft. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Locatie	`region`	Selecteer de dichtstbijzijnde regio.

Accepteer de standaardwaarden voor de overige instellingen en selecteer Beoordelen en maken om uw invoer te valideren. Er wordt een melding voor geslaagde validatie weergegeven.
Selecteer Maken om een databaseaccount in te richten en te implementeren.
De implementatie kan enige tijd in beslag nemen. Wacht totdat het bericht Implementatie is voltooid in de Notification Hub voordat u doorgaat.
Selecteer Ga naar de resource om naar het databaseaccount in de portal te gaan. Het deelvenster Snel starten voor uw Azure Cosmos DB-account wordt weergegeven.

Vervolgens voegen we een container toe en voegen we vervolgens een database toe aan het Azure Cosmos DB-account.

Een container toevoegen

In een Azure Cosmos DB wordt een container gebruikt voor het opslaan van verschillende door de gebruiker gegenereerde entiteiten, ook wel items genoemd. We maken een container met de naam Bladwijzers.

Laten we het hulpprogramma Data Explorer gebruiken om een database en container te maken.

Selecteer Data Explorer in het menu van uw Azure Cosmos DB-account. Het deelvenster Data Explorer voor uw Cosmos DB-account wordt weergegeven.
Selecteer het vak Nieuwe container . Het deelvenster Nieuwe container wordt weergegeven. Mogelijk moet u schuiven om deze te zien.

Voer de volgende waarden in voor elke instelling.

Instelling	Weergegeven als	Beschrijving
Database-id	Selecteer Nieuwe maken en voer func-io-learn-db in voor de database-id	Databasenamen mogen 1 tot 255 tekens lang `/, \\, #, ?`zijn en mogen geen spatie bevatten of een volgruimte bevatten. U kunt wat u wilt invoeren, maar we gebruiken func-io-learn-db in deze module.
Maximale RU/s voor database	4000	Accepteer de standaarddoorvoer van 4000 aanvraageenheden per seconde (RU/s). Als u de latentie wilt verminderen, kunt u de prestaties later omhoog schalen.
Container-id	Bladwijzers	Voor id's van containers gelden dezelfde tekenvereisten als voor databasenamen. In deze module gebruiken we bladwijzers .
Partitiesleutel	/id	Met de partitiesleutel wordt opgegeven hoe de documenten in Azure Cosmos DB-verzamelingen worden verdeeld over logische gegevenspartities. We gebruiken de instelling Partitiesleutel als gemak omdat we ons niet bezighouden met databaseprestaties in deze module. Bekijk de Microsoft Learn Azure Cosmos DB-modules voor meer informatie over strategieën voor partitiesleutels van Azure Cosmos DB.

Accepteer de standaardwaarden voor alle andere instellingen.

Schuif naar de onderkant van het deelvenster en selecteer OK. Wacht enkele minuten totdat de database en container zijn gemaakt.

Als u klaar bent, geeft Data Explorer func-io-learn-db weer in DATA onder NOSQL-API.
Selecteer func-io-learn-db om deze uit te vouwen. U ziet dat uw func-io-learn-db-database verschillende onderliggende leden bevat, waaronder schaal- en bladwijzers.
Vouw de container Bladwijzers uit. U ziet dat meerdere onderliggende leden deze al vooraf hebben ingevuld.

In de volgende taak voegt u enkele gegevens, ook wel items genoemd, toe aan de container Bladwijzers.

Testgegevens toevoegen

U wilt gegevens toevoegen aan de container Bladwijzers . Gebruik Data Explorer om een URL en id voor elk item op te slaan.

Vouw de func-io-learn-db-database en de container Bladwijzers uit en selecteer vervolgens Items. Het tabblad Items wordt weergegeven.
Selecteer Nieuw item in de opdrachtbalk.
Vervang de standaardcode van het nieuwe item door de volgende JSON-code.
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```

Selecteer Opslaan op de opdrachtbalk.

U ziet dat er meer eigenschappen worden weergegeven dan de twee regels die we hebben toegevoegd. Ze beginnen allemaal met een onderstreping (_rid, _self, _etag, _attachments, _ts). Deze eigenschappen, zoals beschreven in de volgende tabel, worden door het systeem gegenereerd om de items te beheren die u aan de container toevoegt.

Eigenschappen	Beschrijving
`_rid`	Resource-id is een unieke id die ook hiërarchisch is per resourcestack in het resourcemodel. De id wordt intern gebruikt voor plaatsing en navigatie van de itemresource.
`_self`	Unieke adresseerbare URI voor de resource.
`_etag`	Vereist voor optimistisch gelijktijdigheidsbeheer.
`_attachments`	Adresseerbaar pad voor de resource bijlagen.
`_ts`	Tijdstempel van de laatste update van deze resource.

Laten we nog enkele items toevoegen aan de container Bladwijzers . Selecteer Nieuw item in de opdrachtbalk. Nog vier items maken met de volgende inhoud. Voeg de items toe door Nieuw item te selecteren en vervolgens Opslaan te selecteren nadat u elk nieuw item hebt gekopieerd en geplakt. U ziet hoe elk item wordt toegevoegd aan de lijst met items.
```
{
    "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"
}
```
Wanneer u klaar bent met het invoeren van de bladwijzergegevens, moet uw container eruitzien als de volgende afbeelding.

De container Bladwijzers bevat vijf items. Als in dit scenario een aanvraag binnenkomt met 'id=docs', wordt die id in de container Bladwijzers opgezoekd en wordt de URL https://learn.microsoft.com/azuregeretourneerd. Laten we een Azure-functie maken waarmee waarden in de container Bladwijzers worden opgezoekd.

Een functie maken

Ga naar de functie-app die u in de vorige les hebt gemaakt. Selecteer in het resourcemenu De optie Start en in de sectie Recente resources ziet u de functie-app (Type is gelijk aan functie-app). Selecteer uw functie-app. Het deelvenster Functie-app wordt weergegeven.
Op het tabblad Functies op de pagina Overzicht hebt u één functie, HttpTrigger1.
Laten we een andere functie maken. Selecteer Maken op het tabblad Functions . Het deelvenster Functie maken wordt weergegeven met sjablonen voor ondersteunde triggers.
Selecteer in de sectie Selecteer een sjabloon de HTTP-trigger en selecteer vervolgens Volgende.
Accepteer alle standaardinstellingen en selecteer Maken om uw functie te maken.

Het deelvenster Overzicht voor de functie HttpTrigger2 wordt weergegeven.

De functie controleren

U kunt onze voortgang tot nu toe controleren door de nieuwe functie te testen.

Selecteer Functie-URL ophalen in de opdrachtbalk. Het dialoogvenster Functie-URL ophalen wordt weergegeven.
Selecteer standaard (functietoets) in de vervolgkeuzelijst, selecteer vervolgens het pictogram Kopiëren naar klembord en selecteer OK.
Plak de functie-URL die u hebt gekopieerd in de adresbalk van een nieuw browsertabblad. Voeg de waarde &name=<your name> van de querytekenreeks toe aan het einde van de URL, vervang deze <your name> door uw naam en druk op Enter. De Azure-functie moet een persoonlijk antwoord retourneren in de browser.

Nu onze skeletal-functie werkt, gaan we onze aandacht vestigen op het lezen van gegevens uit uw Azure Cosmos DB, of in ons scenario, vanuit uw container Bladwijzers .

Een Azure Cosmos DB-invoerbinding toevoegen

Voor het lezen van gegevens uit de database, moet u een invoerbinding definiëren. Zoals u hier ziet, kunt u in slechts enkele stappen een binding configureren die met uw database kan communiceren.

Selecteer Integratie in azure Portal in het menu HttpTrigger2-functie bovenaan. Het deelvenster Integratie voor uw functie wordt weergegeven.

U hebt een sjabloon gebruikt waarmee een HTTP-triggeraanvraag is gemaakt met een HTTP-uitvoerbinding. We gaan een Azure Cosmos DB-invoerbinding toevoegen.
Selecteer Invoer toevoegen in het vak Trigger en invoer. Het deelvenster Invoer maken wordt weergegeven.
Selecteer Azure Cosmos DB in de vervolgkeuzelijst Bindingstype.
Selecteer in de sectie Details van Azure Cosmos DB, onder de verbindingsinstelling van het Cosmos DB-account, de nieuwe koppeling. Het dialoogvenster Nieuwe Cosmos DB-verbinding wordt weergegeven.

Als er een bericht wordt weergegeven waarin u wordt gevraagd om de extensie Microsoft.Azure.WebJobs.Extensions.CosmosDB te installeren, selecteert u Installeren en wacht u tot deze is voltooid.
Standaard herkent Azure het Azure Cosmos DB-account dat u eerder hebt gemaakt. Selecteer OK om een verbinding met uw database in te stellen. Er is een nieuwe verbinding met het databaseaccount geconfigureerd en wordt weergegeven in het verbindingsveld van het Cosmos DB-account.

We willen een bladwijzer met een specifieke id opzoeken, dus we koppelen de id die we in de querytekenreeks ontvangen aan de binding.

Laten we de instellingen in het deelvenster Invoer maken voltooien. Voer de volgende waarden in voor elke instelling. Als u meer wilt weten over het doel van elke instelling, selecteert u het informatiepictogram in dat veld.

Instelling	Weergegeven als	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. Deze waarde is de databasenaam die we hebben ingesteld.
Verzamelingsnaam	`Bookmarks`	De verzameling waaruit we de gegevens lezen. Deze instelling is gedefinieerd.
Document-id	`id`	Voeg de document-id toe die we hebben gedefinieerd bij het maken van de Azure Cosmos DB-container Bladwijzers .
Partitiesleutel	`/id`	Voeg de partitiesleutel toe die u hebt gedefinieerd bij het maken van de Azure Cosmos DB-verzameling Bladwijzers . De hier ingevoerde sleutel (opgegeven in de indeling van invoerbinding `<key>`) moet overeenkomen met de sleutel in de verzameling.
SQL-query (optioneel)	Leeg laten	U kunt slechts één document tegelijk ophalen op basis van de id. Filteren met de instelling Document-id is dus beter dan het gebruik van een SQL-query in dit exemplaar. U kunt een SQL-query maken die één vermelding retourneert (`SELECT * from b where b.ID = id`). Met deze query wordt weliswaar een document geretourneerd, maar deze wordt dan in een documentverzameling geretourneerd. De code moet dan onnodig een hele verzameling afhandelen. Gebruik een SQL-query als u meerdere documenten wilt hebben.

Om te verduidelijken waarom we deze instellingen gebruiken, willen we een bladwijzer met een specifieke id opzoeken. Daarom hebben we de document-id die onze functie in de querytekenreeks ontvangt, gekoppeld aan de invoerbinding. Deze syntax is een zogenaamde bindingsexpressie. De functie wordt geactiveerd door een HTTP-aanvraag waarin een querytekenreeks wordt gebruikt om de id op te zoeken. Omdat id's uniek zijn in onze verzameling, retourneert de binding ofwel 0 (niet gevonden) of 1 (gevonden) documenten.

Als u deze configuratie van de invoerbinding wilt opslaan, selecteert u Toevoegen.

De functie-implementatie bijwerken

Nu uw binding is gedefinieerd, kunt u deze gebruiken in uw functie. U moet twee wijzigingen aanbrengen om de binding te implementeren die u hebt gemaakt:

Wijzig de taalspecifieke implementatiecode van uw functie. Er moet worden bepaald of een document is gevonden in de database die overeenkomt met de id die wordt doorgegeven aan de functie.
Wijzig de JSON-implementatiecode van uw functie zodat deze een parameter accepteert die wordt doorgegeven in de querytekenreeks.

De JavaScript-implementatiecode van uw functie wijzigen

Selecteer Code + Test in het menu Functie voor de functie HttpTrigger2. Het deelvenster Code en test wordt weergegeven voor de functie HttpTrigger2 .

Vervang alle code in het bestand index.js door de volgende code.

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

Selecteer Opslaan op de opdrachtbalk. Selecteer Bestandssysteemlogboeken in de vervolgkeuzelijst bovenaan het deelvenster Logboeken (waarin Standaard App Insights-logboeken worden weergegeven). Het deelvenster Logboeken wordt weergegeven met Connected!

Laten we eens kijken wat deze code doet.

De functie wordt geactiveerd door een binnenkomende HTTP-aanvraag, en een queryparameter id wordt aan de Azure Cosmos DB-invoerbinding doorgegeven.
Als de database een document vindt dat overeenkomt met deze id, wordt de bookmark parameter ingesteld op het gevonden document.

In dit voorbeeld wordt met de code een antwoord samengesteld dat de URL-waarde bevat die in het bijbehorende document van de database wordt gevonden.
Als er geen document wordt gevonden dat overeenkomt met deze sleutel, reageert de aanvraag met een nettolading en statuscode die de gebruiker het slechte nieuws vertelt.

De JSON-implementatiecode van uw functie wijzigen

Selecteer function.json in de vervolgkeuzelijst in uw <functionapp> \ HttpTrigger2 \ pad.

Vervang alle code in het bestand function.json door de volgende code. Zorg ervoor dat en vervang deze door your-database de naam van uw Azure Cosmos DB-account.

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

Selecteer Opslaan op de opdrachtbalk.

De PowerShell-implementatiecode van uw functie wijzigen

Selecteer Code + Test in het menu Functie voor de functie HttpTrigger2. Het deelvenster Code en test wordt weergegeven voor de functie HttpTrigger2 , met het run.ps1 bestand.

Vervang alle code in het run.ps1 bestand door de volgende code.

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

Selecteer Opslaan op de opdrachtbalk. Selecteer Bestandssysteemlogboeken in de vervolgkeuzelijst bovenaan het deelvenster Logboeken (waarin Standaard App Insights-logboeken worden weergegeven). Het deelvenster Logboeken wordt weergegeven met Connected!

Laten we eens kijken wat deze code doet.

De functie wordt geactiveerd door een binnenkomende HTTP-aanvraag, en een queryparameter id wordt aan de Azure Cosmos DB-invoerbinding doorgegeven.
Als de database een document vindt dat overeenkomt met deze id, wordt de bookmark parameter ingesteld op het gevonden document.

In dit voorbeeld wordt met de code een antwoord samengesteld dat de URL-waarde bevat die in het bijbehorende document van de database wordt gevonden.
Als er geen document wordt gevonden dat overeenkomt met deze sleutel, reageert de aanvraag met een nettolading en statuscode die de gebruiker het slechte nieuws vertelt.

De JSON-implementatiecode van uw functie wijzigen

Selecteer function.json in de vervolgkeuzelijst in uw <functionapp> \ HttpTrigger2 \ pad.

Wijzig de waarden voor id en partitionKey zodat ze een parameter van {id}. Uw function.json code moet eruitzien als in het volgende voorbeeld, waarbij your-database deze wordt vervangen door de naam van uw Cosmos DB-database.

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

Selecteer Opslaan op de opdrachtbalk.

Probeer het zelf

U moet zich al in het deelvenster Code + Test voor uw HttpTrigger2-functie bevindt.
Selecteer de functie-URL ophalen in de opdrachtbalk. Het dialoogvenster Functie-URL ophalen wordt weergegeven.
Selecteer in de vervolgkeuzelijst Sleutel de standaardwaarde onder Functietoets en selecteer vervolgens het pictogram Kopiëren naar klembord aan het einde van de URL.
Plak de functiesleutel die u hebt gekopieerd in de adresbalk van een nieuw browsertabblad en voeg vervolgens de waarde van de querytekenreeks &id=docs toe aan het einde van de URL. De resulterende URL moet er ongeveer uitzien als in het volgende voorbeeld:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Druk op Enter om de aanvraag uit te voeren. Het antwoord dat door uw functie wordt geretourneerd, moet vergelijkbaar zijn met het volgende voorbeeld.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Vervang &id=docs door &id=missing, druk op Enter en bekijk het antwoord. We hebben vijf bladwijzers gedefinieerd en er is een zinvolle foutreactie gemaakt als de aangevraagde bladwijzer niet bestaat.

In deze module hebt u handmatig uw eerste invoerbinding gemaakt om gegevens uit een Azure Cosmos DB-database te kunnen lezen. De hoeveelheid code die u hebt geschreven om in de database te zoeken en gegevens te lezen, is dankzij de bindingen minimaal. U hebt het grootste deel van uw werk gedaan om de binding declaratief te configureren en het platform zorgde voor de rest.

In de volgende module voegt u meer gegevens toe aan de verzameling bladwijzers via een Azure Cosmos DB-uitvoerbinding.

Oefening: gegevens lezen met invoerbindingen

Een Azure Cosmos DB-account maken

Een databaseaccount maken

Een container toevoegen

Testgegevens toevoegen

Een functie maken

De functie controleren

Een Azure Cosmos DB-invoerbinding toevoegen

De functie-implementatie bijwerken

De JavaScript-implementatiecode van uw functie wijzigen

De JSON-implementatiecode van uw functie wijzigen

De PowerShell-implementatiecode van uw functie wijzigen

De JSON-implementatiecode van uw functie wijzigen

Probeer het zelf

Feedback