Delen via

Zelfstudie: Een functie maken in Java met een Event Hub-trigger en een Azure Cosmos DB-uitvoerbinding

  • Artikel

In deze zelfstudie ontdekt u hoe u Azure Functions gebruikt om een Java-functie te maken die een doorlopende stroom van temperatuur- en drukgegevens analyseert. Event Hub-gebeurtenissen die sensorwaarden vertegenwoordigen activeren de functie. De functie verwerkt de gebeurtenisgegevens en voegt vervolgens statusvermeldingen toe aan een Azure Cosmos DB-exemplaar.

In deze zelfstudie gaat u:

  • Azure-resources maken en beheren met behulp van de Azure CLI.
  • Java-functies maken en testen die communiceren met deze resources.
  • Uw functies naar Azure implementeren en ze bewaken met Application Insights.

Als u geen Azure-abonnement hebt, kunt u een gratis Azure-account maken voordat u begint.

Vereisten

Om deze zelfstudie te voltooien moet het volgende geïnstalleerd zijn:

Belangrijk

De omgevingsvariabele JAVA_HOME moet zijn ingesteld op de installatielocatie van de JDK om deze zelfstudie te kunnen voltooien.

Als u de code voor deze zelfstudie direct wilt gebruiken, raadpleegt u de voorbeeldopslagplaats java-functions-eventhub-cosmosdb.

Azure-resources maken

In deze zelfstudie hebt u de volgende resources nodig:

  • Een resourcegroep die de andere resources bevat
  • Een Event Hubs-naamruimte, event hub en autorisatieregel
  • Een Azure Cosmos DB-account, -database en -verzameling
  • Een functie-app en een opslagaccount om deze te hosten

In de volgende onderdelen ziet u hoe u deze resources maakt met behulp van de Azure CLI.

Omgevingsvariabelen instellen

Maak vervolgens enkele omgevingsvariabelen voor de namen en de locatie van de resources die u gaat maken. Gebruik de volgende opdrachten om de tijdelijke aanduidingen <value> te vervangen door uw gekozen waarden. Waarden moeten voldoen aan de naamgevingsregels en -beperkingen voor Azure-resources. Gebruik voor de variabele LOCATION een van de waarden die door de opdracht az functionapp list-consumption-locations worden geproduceerd.

RESOURCE_GROUP=<value>
EVENT_HUB_NAMESPACE=<value>
EVENT_HUB_NAME=<value>
EVENT_HUB_AUTHORIZATION_RULE=<value>
COSMOS_DB_ACCOUNT=<value>
STORAGE_ACCOUNT=<value>
FUNCTION_APP=<value>
LOCATION=<value>

In de rest van deze zelfstudie worden deze variabelen gebruikt. Houd er rekening mee dat deze variabelen alleen behouden blijven tijdens uw huidige sessie in Azure CLI of Cloud Shell. U moet deze opdrachten opnieuw uitvoeren als u een ander lokaal terminalvenster gebruikt, of als er een time-out optreedt voor de Cloud Shell-sessie.

Een brongroep maken

Azure gebruikt resourcegroepen om alle gerelateerde resources in uw account te verzamelen. Op die manier kunt u ze bekijken als eenheid en ze met één opdracht verwijderen wanneer u klaar bent.

Gebruik de volgende opdracht om een resourcegroep te maken:

az group create \
    --name $RESOURCE_GROUP \
    --location $LOCATION

Een Event Hub maken

Maak vervolgens een Azure Event Hubs-naamruimte, event hub en autorisatieregel met behulp van de volgende opdrachten:

az eventhubs namespace create \
    --resource-group $RESOURCE_GROUP \
    --name $EVENT_HUB_NAMESPACE
az eventhubs eventhub create \
    --resource-group $RESOURCE_GROUP \
    --name $EVENT_HUB_NAME \
    --namespace-name $EVENT_HUB_NAMESPACE \
    --retention-time 1 \
    --cleanup-policy Delete
az eventhubs eventhub authorization-rule create \
    --resource-group $RESOURCE_GROUP \
    --name $EVENT_HUB_AUTHORIZATION_RULE \
    --eventhub-name $EVENT_HUB_NAME \
    --namespace-name $EVENT_HUB_NAMESPACE \
    --rights Listen Send

De Event Hubs-naamruimte bevat de daadwerkelijke event hub en de autorisatieregel. De autorisatieregel stelt uw functies in staat om berichten te sturen naar de hub en te luisteren naar de overeenkomstige gebeurtenissen. De ene functie verstuurt berichten die telemetriegegevens vertegenwoordigen. Een andere functie luistert naar gebeurtenissen, analyseert de gebeurtenisgegevens en slaat de resultaten op in Azure Cosmos DB.

Een Azure Cosmos DB maken

Maak vervolgens een Azure Cosmos DB-account, -database en -verzameling met behulp van de volgende opdrachten:

az cosmosdb create \
    --resource-group $RESOURCE_GROUP \
    --name $COSMOS_DB_ACCOUNT
az cosmosdb sql database create \
    --resource-group $RESOURCE_GROUP \
    --account-name $COSMOS_DB_ACCOUNT \
    --name TelemetryDb
az cosmosdb sql container create \
    --resource-group $RESOURCE_GROUP \
    --account-name $COSMOS_DB_ACCOUNT \
    --database-name TelemetryDb \
    --name TelemetryInfo \
    --partition-key-path '/temperatureStatus'

De waarde partition-key-path partitioneert uw gegevens op basis van de temperatureStatus-waarde voor elk item. Met de partitiesleutel kan Azure Cosmos DB de prestaties verbeteren door uw gegevens te verdelen in afzonderlijke subsets waartoe deze onafhankelijk toegang heeft.

Maak een opslagaccount en functie-app

Maak vervolgens een Azure Storage-account, wat vereist is voor Azure Functions, en maak vervolgens de functie-app. Gebruik de volgende opdrachten:

az storage account create \
    --resource-group $RESOURCE_GROUP \
    --name $STORAGE_ACCOUNT \
    --sku Standard_LRS
az functionapp create \
    --resource-group $RESOURCE_GROUP \
    --name $FUNCTION_APP \
    --storage-account $STORAGE_ACCOUNT \
    --consumption-plan-location $LOCATION \
    --runtime java \
    --functions-version 4

Wanneer de az functionapp create-opdracht uw functie-app maakt, wordt er ook een Application Insights-resource met dezelfde naam gemaakt. De functie-app wordt automatisch geconfigureerd met een instelling met de naam APPINSIGHTS_INSTRUMENTATIONKEY die deze verbindt met Application Insights. U kunt de app-telemetrie bekijken nadat u uw functies hebt geïmplementeerd in Azure, zoals verderop in deze zelfstudie beschreven wordt.

Uw functie-app configureren

De functie-app moet toegang hebben tot de andere resources om goed te kunnen werken. In de volgende onderdelen ontdekt u hoe u uw functie-app zodanig configureert dat deze op uw lokale machine kan worden uitgevoerd.

Verbindingsreeken voor een resource ophalen

Gebruik de volgende opdrachten om de opslag, Event Hub en Azure Cosmos DB-verbindingsreeks s op te halen en op te slaan in omgevingsvariabelen:

Notitie

Microsoft raadt aan de veiligste verificatiestroom te gebruiken die beschikbaar is. De verificatiestroom die in deze procedure wordt beschreven, zoals voor databases, caches, berichten of AI-services, vereist een zeer hoge mate van vertrouwen in de toepassing en brengt risico's met zich mee die niet aanwezig zijn in andere stromen. Gebruik deze stroom alleen wanneer veiligere opties, zoals beheerde identiteiten voor wachtwoordloze of sleutelloze verbindingen, niet haalbaar zijn. Voor bewerkingen van lokale machines geeft u de voorkeur aan gebruikersidentiteiten voor verbindingen zonder wachtwoord of sleutelloze verbindingen.

AZURE_WEB_JOBS_STORAGE=$( \
    az storage account show-connection-string \
        --name $STORAGE_ACCOUNT \
        --query connectionString \
        --output tsv)
echo $AZURE_WEB_JOBS_STORAGE
EVENT_HUB_CONNECTION_STRING=$( \
    az eventhubs eventhub authorization-rule keys list \
        --resource-group $RESOURCE_GROUP \
        --name $EVENT_HUB_AUTHORIZATION_RULE \
        --eventhub-name $EVENT_HUB_NAME \
        --namespace-name $EVENT_HUB_NAMESPACE \
        --query primaryConnectionString \
        --output tsv)
echo $EVENT_HUB_CONNECTION_STRING
COSMOS_DB_CONNECTION_STRING=$( \
    az cosmosdb keys list \
        --resource-group $RESOURCE_GROUP \
        --name $COSMOS_DB_ACCOUNT \
        --type connection-strings \
        --query 'connectionStrings[0].connectionString' \
        --output tsv)
echo $COSMOS_DB_CONNECTION_STRING

Deze variabelen worden ingesteld op waarden die worden opgehaald vanuit Azure CLI-opdrachten. Elke opdracht maakt gebruik van een JMESPath-query om de verbindingsreeks op te halen uit de geretourneerde JSON-payload. De verbindingsreeksen worden ook weergegeven met echo zodat u kunt controleren of ze met succes zijn opgehaald.

De instellingen van uw functie-app bijwerken

Gebruik vervolgens de volgende opdracht om de waarden van de verbindingsreeks over te zetten naar de app-instellingen in uw Azure Functions-account:

az functionapp config appsettings set \
    --resource-group $RESOURCE_GROUP \
    --name $FUNCTION_APP \
    --settings \
        AzureWebJobsStorage=$AZURE_WEB_JOBS_STORAGE \
        EventHubConnectionString=$EVENT_HUB_CONNECTION_STRING \
        CosmosDBConnectionSetting=$COSMOS_DB_CONNECTION_STRING

Uw Azure-resources zijn nu aangemaakt en geconfigureerd om goed te kunnen samen werken.

Uw functies maken en testen

Nu gaat u een project maken op uw lokale machine, Java-code toevoegen en deze testen. U gebruikt opdrachten die werken met de Azure Functions Plugin voor Maven en de Azure Functions Core Tools. Uw functies worden lokaal uitgevoerd, maar gebruiken de cloudresources die u hebt gemaakt. Wanneer uw functies lokaal werken, kunt u Maven gebruiken om ze te implementeren naar de cloud en te kijken hoe uw gegevens en analyses verzqmeld worden.

Als u Cloud Shell hebt gebruikt om uw resources aan te maken, wordt u niet lokaal verbonden met Azure. Gebruik in dat geval de opdracht az login om het browsergebaseerde aanmeldingsproces te starten. Stel vervolgens, indien nodig, het standaardabonnement in met az account set --subscription, gevolgd door de abonnements-id. Voer ten slotte de volgende opdrachten uit om enkele omgevingsvariabelen opnieuw te maken op uw lokale machine. Vervang de tijdelijke aanduidingen <value> door de waarden die u eerder hebt gebruikt.

RESOURCE_GROUP=<value>
FUNCTION_APP=<value>

Een lokaal Functions-project maken

Gebruik de volgende Maven-opdracht om een Functions-project te maken en de nodige afhankelijkheden toe te voegen.

mvn archetype:generate --batch-mode \
    -DarchetypeGroupId=com.microsoft.azure \
    -DarchetypeArtifactId=azure-functions-archetype \
    -DappName=$FUNCTION_APP \
    -DresourceGroup=$RESOURCE_GROUP \
    -DappRegion=$LOCATION \
    -DgroupId=com.example \
    -DartifactId=telemetry-functions

Deze opdracht genereert verschillende bestanden in een telemetry-functions-map:

  • Een pom.xml-bestand dat kan worden gebruikt met Maven
  • Een local.settings.json-bestand om app-instellingen te bewaren voor lokale tests
  • Een host.json bestand dat de Azure Functions-extensiebundel inschakelt, vereist voor Azure Cosmos DB-uitvoerbinding in uw functie voor gegevensanalyse
  • Een Function.java-bestand dat een standaard functie-implementatie bevat
  • Een aantal testbestanden die niet nodig zijn voor deze zelfstudie

Verwijder de testbestanden om compilatiefouten te voorkomen Voer de volgende opdrachten uit om naar de nieuwe projectmap te navigeren en verwijder de testmap:

cd telemetry-functions
rm -r src/test

Haal de instellingen van uw functie-app op voor lokaal gebruik

Voor lokale tests heeft uw functieproject de verbindingsreeksen nodig die u eerder in deze zelfstudie hebt toegevoegd aan uw functie-app in Azure. Gebruik de volgende Azure Functions Core Tools-opdracht, die alle instellingen van de functie-app die zijn opgeslagen in de cloud ophaalt en ze toevoegt aan uw local.settings.json-bestand:

Notitie

Microsoft raadt aan de veiligste verificatiestroom te gebruiken die beschikbaar is. De verificatiestroom die in deze procedure wordt beschreven, zoals voor databases, caches, berichten of AI-services, vereist een zeer hoge mate van vertrouwen in de toepassing en brengt risico's met zich mee die niet aanwezig zijn in andere stromen. Gebruik deze stroom alleen wanneer veiligere opties, zoals beheerde identiteiten voor wachtwoordloze of sleutelloze verbindingen, niet haalbaar zijn. Voor bewerkingen van lokale machines geeft u de voorkeur aan gebruikersidentiteiten voor verbindingen zonder wachtwoord of sleutelloze verbindingen.

func azure functionapp fetch-app-settings $FUNCTION_APP

Java-code toevoegen

Open vervolgens het Function.java-bestand en vervang de inhoud door de volgende code.

package com.example;

import com.example.TelemetryItem.status;
import com.microsoft.azure.functions.annotation.Cardinality;
import com.microsoft.azure.functions.annotation.CosmosDBOutput;
import com.microsoft.azure.functions.annotation.EventHubOutput;
import com.microsoft.azure.functions.annotation.EventHubTrigger;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.annotation.TimerTrigger;
import com.microsoft.azure.functions.ExecutionContext;
import com.microsoft.azure.functions.OutputBinding;

public class Function {

    @FunctionName("generateSensorData")
    @EventHubOutput(
        name = "event",
        eventHubName = "", // blank because the value is included in the connection string
        connection = "EventHubConnectionString")
    public TelemetryItem generateSensorData(
        @TimerTrigger(
            name = "timerInfo",
            schedule = "*/10 * * * * *") // every 10 seconds
            String timerInfo,
        final ExecutionContext context) {

        context.getLogger().info("Java Timer trigger function executed at: "
            + java.time.LocalDateTime.now());
        double temperature = Math.random() * 100;
        double pressure = Math.random() * 50;
        return new TelemetryItem(temperature, pressure);
    }

    @FunctionName("processSensorData")
    public void processSensorData(
        @EventHubTrigger(
            name = "msg",
            eventHubName = "", // blank because the value is included in the connection string
            cardinality = Cardinality.ONE,
            connection = "EventHubConnectionString")
            TelemetryItem item,
        @CosmosDBOutput(
            name = "databaseOutput",
            databaseName = "TelemetryDb",
            collectionName = "TelemetryInfo",
            connectionStringSetting = "CosmosDBConnectionSetting")
            OutputBinding<TelemetryItem> document,
        final ExecutionContext context) {

        context.getLogger().info("Event hub message received: " + item.toString());

        if (item.getPressure() > 30) {
            item.setNormalPressure(false);
        } else {
            item.setNormalPressure(true);
        }

        if (item.getTemperature() < 40) {
            item.setTemperatureStatus(status.COOL);
        } else if (item.getTemperature() > 90) {
            item.setTemperatureStatus(status.HOT);
        } else {
            item.setTemperatureStatus(status.WARM);
        }

        document.setValue(item);
    }
}

Zoals u kunt zien, bevat dit bestand twee functies, generateSensorData en processSensorData. De functie generateSensorData simuleert een sensor die de temperatuur- en drukwaarden doorstuurt naar de event hub. Een tijdstrigger voert de functie elke 10 seconden uit en een Event Hub-uitvoerbinding verzendt de retourwaarde naar de event hub.

Wanneer de event hub het bericht ontvangt, genereert het een gebeurtenis. De functie processSensorData wordt uitgevoerd wanneer het de gebeurtenis ontvangt. Vervolgens verwerkt het de gebeurtenisgegevens en gebruikt het een Azure Cosmos DB-uitvoerbinding om de resultaten naar Azure Cosmos DB te sturen.

De gegevens die door deze functies worden gebruikt, worden opgeslagen met behulp van een klasse met de naam TelemetryItem, die u moet implementeren. Maak een nieuw bestand met de naam TelemetryItem.java op dezelfde locatie als Function.java en voeg de volgende code toe:

package com.example;

public class TelemetryItem {

    private String id;
    private double temperature;
    private double pressure;
    private boolean isNormalPressure;
    private status temperatureStatus;
    static enum status {
        COOL,
        WARM,
        HOT
    }

    public TelemetryItem(double temperature, double pressure) {
        this.temperature = temperature;
        this.pressure = pressure;
    }

    public String getId() {
        return id;
    }

    public double getTemperature() {
        return temperature;
    }

    public double getPressure() {
        return pressure;
    }

    @Override
    public String toString() {
        return "TelemetryItem={id=" + id + ",temperature="
            + temperature + ",pressure=" + pressure + "}";
    }

    public boolean isNormalPressure() {
        return isNormalPressure;
    }

    public void setNormalPressure(boolean isNormal) {
        this.isNormalPressure = isNormal;
    }

    public status getTemperatureStatus() {
        return temperatureStatus;
    }

    public void setTemperatureStatus(status temperatureStatus) {
        this.temperatureStatus = temperatureStatus;
    }
}

lokaal uitvoeren

U kunt nu de functies lokaal bouwen en uitvoeren en gegevens weergeven in uw Azure Cosmos DB.

Gebruik de volgende Maven-opdrachten om de functies te bouwen en uitvoeren:

mvn clean package
mvn azure-functions:run

Na sommige build- en opstartberichten ziet u uitvoer die lijkt op het volgende voorbeeld telkens de functie wordt uitgevoerd:

[10/22/19 4:01:30 AM] Executing 'Functions.generateSensorData' (Reason='Timer fired at 2019-10-21T21:01:30.0016769-07:00', Id=c1927c7f-4f70-4a78-83eb-bc077d838410)
[10/22/19 4:01:30 AM] Java Timer trigger function executed at: 2019-10-21T21:01:30.015
[10/22/19 4:01:30 AM] Function "generateSensorData" (Id: c1927c7f-4f70-4a78-83eb-bc077d838410) invoked by Java Worker
[10/22/19 4:01:30 AM] Executed 'Functions.generateSensorData' (Succeeded, Id=c1927c7f-4f70-4a78-83eb-bc077d838410)
[10/22/19 4:01:30 AM] Executing 'Functions.processSensorData' (Reason='', Id=f4c3b4d7-9576-45d0-9c6e-85646bb52122)
[10/22/19 4:01:30 AM] Event hub message received: TelemetryItem={id=null,temperature=32.728691307527015,pressure=10.122563042388165}
[10/22/19 4:01:30 AM] Function "processSensorData" (Id: f4c3b4d7-9576-45d0-9c6e-85646bb52122) invoked by Java Worker
[10/22/19 4:01:38 AM] Executed 'Functions.processSensorData' (Succeeded, Id=1cf0382b-0c98-4cc8-9240-ee2a2f71800d)

U kunt vervolgens naar het Azure-portal gaan en naar uw Azure Cosmos DB-account navigeren. Selecteer Data Explorer, vouw TelemetryInfouit en selecteer items om uw gegevens weer te geven wanneer deze aankomen.

Azure Cosmos DB Data Explorer

Implementeren naar Azure en app-telemetrie weergeven

Ten slotte kunt u uw app implementeren in Azure en controleren of deze blijft werken zoals hij dat lokaal deed.

Implementeer uw project naar Azure met behulp van de volgende opdracht:

mvn azure-functions:deploy

Uw functies worden nu uitgevoerd in Azure, en blijven gegevens verzamelen in uw Azure Cosmos DB. U kunt uw geïmplementeerde functie-app weergeven in de Azure-portal en de app-telemetrie weergeven via de verbonden Application Insights-resource, zoals te zien is in de volgende schermopnames:

Live Metrics Stream:

Live Metrics Stream van Application Insights

Prestaties:

Prestatieblade van Application Insights

Resources opschonen

Wanneer u klaar bent met de Azure-resources die u in deze zelfstudie hebt gemaakt, kunt u deze verwijderen met de volgende opdracht:

az group delete --name $RESOURCE_GROUP

Volgende stappen

In deze zelfstudie hebt u geleerd hoe u een Azure-functie maakt waarmee Event Hub-gebeurtenissen worden verwerkt en een Azure Cosmos DB-exemplaar wordt bijgewerkt. Zie de Azure Functions Java-ontwikkelaarshandleiding voor meer informatie. Zie de referentie com.microsoft.azure.functions.annotation voor meer informatie over de gebruikte aantekeningen.

Deze zelfstudie heeft omgevingsvariabelen en toepassingsinstellingen gebruikt om geheimen zoals verbindingsreeksen op te slaan. Zie voor informatie over het opslaan van deze geheimen in Azure Key Vault Key Vault-referenties gebruiken voor App Service en Azure Functions.

Notitie

Microsoft raadt aan de veiligste verificatiestroom te gebruiken die beschikbaar is. De verificatiestroom die in deze procedure wordt beschreven, zoals voor databases, caches, berichten of AI-services, vereist een zeer hoge mate van vertrouwen in de toepassing en brengt risico's met zich mee die niet aanwezig zijn in andere stromen. Gebruik deze stroom alleen wanneer veiligere opties, zoals beheerde identiteiten voor wachtwoordloze of sleutelloze verbindingen, niet haalbaar zijn. Voor bewerkingen van lokale machines geeft u de voorkeur aan gebruikersidentiteiten voor verbindingen zonder wachtwoord of sleutelloze verbindingen.

Vervolgens leert u Azure Pipelines CI/CD gebruiken voor geautomatiseerde implementatie:

Java maken en implementeren naar Azure Functions