Zelfstudie: Een functie maken in Java met een Event Hub-trigger en een Azure Cosmos DB-uitvoerbinding
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:
- Java Developer Kit, versie 8
- Apache Maven, versie 3.0 of hoger
- Azure Functions Core Tools, versie 2.6.666 of hoger
Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.
Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.
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:
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 \
--message-retention 1
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 3
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:
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.
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.jsonbestand 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:
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:
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",
containerName = "TelemetryInfo",
connection = "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:
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.
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:
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:
Prestaties:
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:
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.
Vervolgens leert u Azure Pipelines CI/CD gebruiken voor geautomatiseerde implementatie: