Snabbstart: Skapa ett API för tabellapp med Java SDK och Azure Cosmos DB
GÄLLER FÖR: Bord
Den här snabbstarten visar hur du kommer åt Azure Cosmos DB-tabell-API:et från ett Java-program. Azure Cosmos DB-tabell-API:et är ett schemalöst datalager som gör att program kan lagra strukturerade NoSQL-data i molnet. Eftersom data lagras i en schemalös design läggs nya egenskaper (kolumner) automatiskt till i tabellen när ett objekt med ett nytt attribut läggs till i tabellen.
Java-program kan komma åt Azure Cosmos DB-tabell-API:et med hjälp av klientbiblioteket azure-data-tables .
Förutsättningar
Exempelprogrammet är skrivet i Spring Boot 2.6.4, Du kan använda Antingen Visual Studio Code eller IntelliJ IDEA som IDE.
Om du inte har en Azure-prenumeration kan du skapa ettkostnadsfritt konto innan du börjar.
Programexempel
Exempelprogrammet för den här självstudien kan klonas eller laddas ned från lagringsplatsen https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-java. Både en startapp och en slutförd app ingår i exempellagringsplatsen.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-java
Exempelprogrammet använder väderdata som exempel för att demonstrera funktionerna i tabell-API:et. Objekt som representerar väderobservationer lagras och hämtas med hjälp av API:et för tabell, inklusive lagring av objekt med ytterligare egenskaper för att demonstrera de schemalösa funktionerna i tabell-API:et.
1 – Skapa ett Azure Cosmos DB-konto
Du måste först skapa ett Azure Cosmos DB Tables API-konto som innehåller de tabeller som används i ditt program. Detta kan göras med hjälp av Azure-portalen, Azure CLI eller Azure PowerShell.
Logga in på Azure-portalen och följ dessa steg för att skapa ett Azure Cosmos DB-konto.
2 – Skapa en tabell
Därefter måste du skapa en tabell i ditt Azure Cosmos DB-konto som programmet ska använda. Till skillnad från en traditionell databas behöver du bara ange namnet på tabellen, inte egenskaperna (kolumnerna) i tabellen. När data läses in i tabellen skapas egenskaperna (kolumnerna) automatiskt efter behov.
I Azure-portalen utför du följande steg för att skapa en tabell i ditt Azure Cosmos DB-konto.
3 – Hämta Azure Cosmos DB-niska veze
För att få åtkomst till dina tabeller i Azure Cosmos DB behöver din app tabellen niska veze för CosmosDB Storage-kontot. Niska veze kan hämtas med hjälp av Azure-portalen, Azure CLI eller Azure PowerShell.
Niska veze för ditt Azure Cosmos DB-konto anses vara en apphemlighet och måste skyddas som alla andra apphemligheter eller lösenord. I det här exemplet används POM för att lagra niska veze under utvecklingen och göra den tillgänglig för programmet.
<profiles>
<profile>
<id>local</id>
<properties>
<azure.tables.connection.string>
<![CDATA[YOUR-DATA-TABLES-SERVICE-CONNECTION-STRING]]>
</azure.tables.connection.string>
<azure.tables.tableName>WeatherData</azure.tables.tableName>
</properties>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
</profile>
</profiles>
4 – Inkludera paketet azure-data-tables
Om du vill komma åt Azure Cosmos DB-tabell-API:et från ett Java-program inkluderar du paketet azure-data-tables .
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-data-tables</artifactId>
<version>12.2.1</version>
</dependency>
5 – Konfigurera tabellklienten i TableServiceConfig.java
Azure SDK kommunicerar med Azure med hjälp av klientobjekt för att köra olika åtgärder mot Azure. TableClient-objektet är det objekt som används för att kommunicera med Azure Cosmos DB-tabell-API:et.
Ett program skapar vanligtvis ett enda TableClient-objekt per tabell som ska användas i hela programmet. Vi rekommenderar att du anger att en metod genererar en TableClient-objektböna som ska hanteras av Spring-containern och som en singleton för att åstadkomma detta.
TableServiceConfig.java
I filen i programmet redigerar du tableClientConfiguration()
metoden så att den matchar följande kodfragment:
@Configuration
public class TableServiceConfiguration {
private static String TABLE_NAME;
private static String CONNECTION_STRING;
@Value("${azure.tables.connection.string}")
public void setConnectionStringStatic(String connectionString) {
TableServiceConfiguration.CONNECTION_STRING = connectionString;
}
@Value("${azure.tables.tableName}")
public void setTableNameStatic(String tableName) {
TableServiceConfiguration.TABLE_NAME = tableName;
}
@Bean
public TableClient tableClientConfiguration() {
return new TableClientBuilder()
.connectionString(CONNECTION_STRING)
.tableName(TABLE_NAME)
.buildClient();
}
}
Du måste också lägga till följande med -instruktion överst i TableServiceConfig.java
filen.
import com.azure.data.tables.TableClient;
import com.azure.data.tables.TableClientBuilder;
6 – Implementera tabellåtgärder i Azure Cosmos DB
Alla Azure Cosmos DB-tabellåtgärder för exempelappen implementeras i TablesServiceImpl
klassen som finns i katalogen Services . Du måste importera SDK-paketet com.azure.data.tables
.
import com.azure.data.tables.TableClient;
import com.azure.data.tables.models.ListEntitiesOptions;
import com.azure.data.tables.models.TableEntity;
import com.azure.data.tables.models.TableTransactionAction;
import com.azure.data.tables.models.TableTransactionActionType;
I början av TableServiceImpl
klassen lägger du till en medlemsvariabel för TableClient-objektet och en konstruktor så att TableClient-objektet kan matas in i klassen.
@Autowired
private TableClient tableClient;
Hämta rader från en tabell
Klassen TableClient innehåller en metod med namnet listEntiteter som gör att du kan välja rader från tabellen. Eftersom inga parametrar skickas till metoden i det här exemplet väljs alla rader från tabellen.
Metoden tar också en allmän parameter av typen TableEntity som anger att modellklassdata returneras som. I det här fallet används den inbyggda klassen TableEntity , vilket innebär listEntities
att metoden returnerar en PagedIterable<TableEntity>
samling som resultat.
public List<WeatherDataModel> retrieveAllEntities() {
List<WeatherDataModel> modelList = tableClient.listEntities().stream()
.map(WeatherDataUtils::mapTableEntityToWeatherDataModel)
.collect(Collectors.toList());
return Collections.unmodifiableList(WeatherDataUtils.filledValue(modelList));
}
Klassen TableEntity som definierats i com.azure.data.tables.models
paketet har egenskaper för partitionsnyckeln och radnyckelvärdena i tabellen. Tillsammans dessa två värden för en unik nyckel för raden i tabellen. I det här exempelprogrammet lagras namnet på väderstationen (staden) i partitionsnyckeln och datum/tid för observationen lagras i radnyckeln. Alla andra egenskaper (temperatur, luftfuktighet, vindhastighet) lagras i en ordlista i TableEntity
objektet.
Det är vanligt att mappa ett TableEntity-objekt till ett objekt med din egen definition. Exempelprogrammet definierar en klass WeatherDataModel
i katalogen Models för det här ändamålet. Den här klassen har egenskaper för stationsnamnet och observationsdatumet som partitionsnyckeln och radnyckeln mappas till, vilket ger mer meningsfulla egenskapsnamn för dessa värden. Sedan används en ordlista för att lagra alla andra egenskaper i objektet. Det här är ett vanligt mönster när du arbetar med Table Storage eftersom en rad kan ha valfritt antal godtyckliga egenskaper och vi vill att våra modellobjekt ska kunna samla in alla. Den här klassen innehåller också metoder för att visa egenskaperna för klassen.
public class WeatherDataModel {
public WeatherDataModel(String stationName, String observationDate, OffsetDateTime timestamp, String etag) {
this.stationName = stationName;
this.observationDate = observationDate;
this.timestamp = timestamp;
this.etag = etag;
}
private String stationName;
private String observationDate;
private OffsetDateTime timestamp;
private String etag;
private Map<String, Object> propertyMap = new HashMap<String, Object>();
public String getStationName() {
return stationName;
}
public void setStationName(String stationName) {
this.stationName = stationName;
}
public String getObservationDate() {
return observationDate;
}
public void setObservationDate(String observationDate) {
this.observationDate = observationDate;
}
public OffsetDateTime getTimestamp() {
return timestamp;
}
public void setTimestamp(OffsetDateTime timestamp) {
this.timestamp = timestamp;
}
public String getEtag() {
return etag;
}
public void setEtag(String etag) {
this.etag = etag;
}
public Map<String, Object> getPropertyMap() {
return propertyMap;
}
public void setPropertyMap(Map<String, Object> propertyMap) {
this.propertyMap = propertyMap;
}
}
Metoden mapTableEntityToWeatherDataModel
används för att mappa ett TableEntity-objekt till ett WeatherDataModel
objekt. Metoden mapTableEntityToWeatherDataModel
mappar PartitionKey
direkt egenskaperna , RowKey
, Timestamp
och Etag
och använder properties.keySet
sedan för att iterera över de andra egenskaperna i TableEntity
objektet och mappa dem till WeatherDataModel
objektet, minus de egenskaper som redan har mappats direkt.
Redigera koden i mapTableEntityToWeatherDataModel
metoden så att den matchar följande kodblock.
public static WeatherDataModel mapTableEntityToWeatherDataModel(TableEntity entity) {
WeatherDataModel observation = new WeatherDataModel(
entity.getPartitionKey(), entity.getRowKey(),
entity.getTimestamp(), entity.getETag());
rearrangeEntityProperties(observation.getPropertyMap(), entity.getProperties());
return observation;
}
private static void rearrangeEntityProperties(Map<String, Object> target, Map<String, Object> source) {
Constants.DEFAULT_LIST_OF_KEYS.forEach(key -> {
if (source.containsKey(key)) {
target.put(key, source.get(key));
}
});
source.keySet().forEach(key -> {
if (Constants.DEFAULT_LIST_OF_KEYS.parallelStream().noneMatch(defaultKey -> defaultKey.equals(key))
&& Constants.EXCLUDE_TABLE_ENTITY_KEYS.parallelStream().noneMatch(defaultKey -> defaultKey.equals(key))) {
target.put(key, source.get(key));
}
});
}
Filtrera rader som returneras från en tabell
Om du vill filtrera raderna som returneras från en tabell kan du skicka en filtersträng i OData-format till metoden listEntities . Om du till exempel vill få alla väderavläsningar för Chicago mellan midnatt 1 juli 2021 och midnatt 2 juli 2021 (inklusive) skickar du följande filtersträng.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Du kan visa alla OData-filteroperatorer på OData-webbplatsen i avsnittet Filter System Query Option
I exempelprogrammet FilterResultsInputModel
är objektet utformat för att avbilda alla filtervillkor som tillhandahålls av användaren.
public class FilterResultsInputModel implements Serializable {
private String partitionKey;
private String rowKeyDateStart;
private String rowKeyTimeStart;
private String rowKeyDateEnd;
private String rowKeyTimeEnd;
private Double minTemperature;
private Double maxTemperature;
private Double minPrecipitation;
private Double maxPrecipitation;
public String getPartitionKey() {
return partitionKey;
}
public void setPartitionKey(String partitionKey) {
this.partitionKey = partitionKey;
}
public String getRowKeyDateStart() {
return rowKeyDateStart;
}
public void setRowKeyDateStart(String rowKeyDateStart) {
this.rowKeyDateStart = rowKeyDateStart;
}
public String getRowKeyTimeStart() {
return rowKeyTimeStart;
}
public void setRowKeyTimeStart(String rowKeyTimeStart) {
this.rowKeyTimeStart = rowKeyTimeStart;
}
public String getRowKeyDateEnd() {
return rowKeyDateEnd;
}
public void setRowKeyDateEnd(String rowKeyDateEnd) {
this.rowKeyDateEnd = rowKeyDateEnd;
}
public String getRowKeyTimeEnd() {
return rowKeyTimeEnd;
}
public void setRowKeyTimeEnd(String rowKeyTimeEnd) {
this.rowKeyTimeEnd = rowKeyTimeEnd;
}
public Double getMinTemperature() {
return minTemperature;
}
public void setMinTemperature(Double minTemperature) {
this.minTemperature = minTemperature;
}
public Double getMaxTemperature() {
return maxTemperature;
}
public void setMaxTemperature(Double maxTemperature) {
this.maxTemperature = maxTemperature;
}
public Double getMinPrecipitation() {
return minPrecipitation;
}
public void setMinPrecipitation(Double minPrecipitation) {
this.minPrecipitation = minPrecipitation;
}
public Double getMaxPrecipitation() {
return maxPrecipitation;
}
public void setMaxPrecipitation(Double maxPrecipitation) {
this.maxPrecipitation = maxPrecipitation;
}
}
När det här objektet skickas till retrieveEntitiesByFilter
-metoden i TableServiceImpl
klassen skapas en filtersträng för varje egenskapsvärde som inte är null. Sedan skapas en kombinerad filtersträng genom att alla värden kopplas ihop med en "och"-sats. Den här kombinerade filtersträngen skickas till metoden listEntities i TableClient-objektet och endast rader som matchar filtersträngen returneras. Du kan använda en liknande metod i koden för att konstruera lämpliga filtersträngar som krävs av ditt program.
public List<WeatherDataModel> retrieveEntitiesByFilter(FilterResultsInputModel model) {
List<String> filters = new ArrayList<>();
if (!StringUtils.isEmptyOrWhitespace(model.getPartitionKey())) {
filters.add(String.format("PartitionKey eq '%s'", model.getPartitionKey()));
}
if (!StringUtils.isEmptyOrWhitespace(model.getRowKeyDateStart())
&& !StringUtils.isEmptyOrWhitespace(model.getRowKeyTimeStart())) {
filters.add(String.format("RowKey ge '%s %s'", model.getRowKeyDateStart(), model.getRowKeyTimeStart()));
}
if (!StringUtils.isEmptyOrWhitespace(model.getRowKeyDateEnd())
&& !StringUtils.isEmptyOrWhitespace(model.getRowKeyTimeEnd())) {
filters.add(String.format("RowKey le '%s %s'", model.getRowKeyDateEnd(), model.getRowKeyTimeEnd()));
}
if (model.getMinTemperature() != null) {
filters.add(String.format("Temperature ge %f", model.getMinTemperature()));
}
if (model.getMaxTemperature() != null) {
filters.add(String.format("Temperature le %f", model.getMaxTemperature()));
}
if (model.getMinPrecipitation() != null) {
filters.add(String.format("Precipitation ge %f", model.getMinPrecipitation()));
}
if (model.getMaxPrecipitation() != null) {
filters.add(String.format("Precipitation le %f", model.getMaxPrecipitation()));
}
List<WeatherDataModel> modelList = tableClient.listEntities(new ListEntitiesOptions()
.setFilter(String.join(" and ", filters)), null, null).stream()
.map(WeatherDataUtils::mapTableEntityToWeatherDataModel)
.collect(Collectors.toList());
return Collections.unmodifiableList(WeatherDataUtils.filledValue(modelList));
}
Infoga data med ett TableEntity-objekt
Det enklaste sättet att lägga till data i en tabell är att använda ett TableEntity-objekt . I det här exemplet mappas data från ett indatamodellobjekt till ett TableEntity-objekt . Egenskaperna för indataobjektet som representerar väderstationens namn och datum/tid för observation mappas till PartitionKey
egenskaperna och RowKey
) som tillsammans utgör en unik nyckel för raden i tabellen. Sedan mappas de ytterligare egenskaperna för indatamodellobjektet till ordlisteegenskaper i TableClient-objektet . Slutligen används metoden createEntity i TableClient-objektet för att infoga data i tabellen.
insertEntity
Ändra klassen i exempelprogrammet så att den innehåller följande kod.
public void insertEntity(WeatherInputModel model) {
tableClient.createEntity(WeatherDataUtils.createTableEntity(model));
}
Upsert-data med ett TableEntity-objekt
Om du försöker infoga en rad i en tabell med en kombination av partitionsnyckel/radnyckel som redan finns i tabellen får du ett fel. Därför är det ofta bättre att använda upsertEntity i stället för insertEntity
metoden när du lägger till rader i en tabell. Om den angivna kombinationen av partitionsnyckel/radnyckel redan finns i tabellen uppdaterar metoden upsertEntity den befintliga raden. Annars läggs raden till i tabellen.
public void upsertEntity(WeatherInputModel model) {
tableClient.upsertEntity(WeatherDataUtils.createTableEntity(model));
}
Infoga eller öka data med variabelegenskaper
En av fördelarna med att använda Azure Cosmos DB-tabell-API:et är att om ett objekt som läses in i en tabell innehåller nya egenskaper läggs dessa egenskaper automatiskt till i tabellen och värdena som lagras i Azure Cosmos DB. Du behöver inte köra DDL-instruktioner som ALTER TABLE
att lägga till kolumner som i en traditionell databas.
Den här modellen ger ditt program flexibilitet när du hanterar datakällor som kan lägga till eller ändra vilka data som behöver samlas in över tid eller när olika indata ger olika data till ditt program. I exempelprogrammet kan vi simulera en väderstation som inte bara skickar basväderdata utan även några ytterligare värden. När ett objekt med dessa nya egenskaper lagras i tabellen för första gången läggs motsvarande egenskaper (kolumner) automatiskt till i tabellen.
I exempelprogrammet byggs ExpandableWeatherObject
klassen runt en intern ordlista för att stödja alla egenskaper i objektet. Den här klassen representerar ett typiskt mönster för när ett objekt måste innehålla en godtycklig uppsättning egenskaper.
public class ExpandableWeatherObject {
private String stationName;
private String observationDate;
private Map<String, Object> propertyMap = new HashMap<String, Object>();
public String getStationName() {
return stationName;
}
public void setStationName(String stationName) {
this.stationName = stationName;
}
public String getObservationDate() {
return observationDate;
}
public void setObservationDate(String observationDate) {
this.observationDate = observationDate;
}
public Map<String, Object> getPropertyMap() {
return propertyMap;
}
public void setPropertyMap(Map<String, Object> propertyMap) {
this.propertyMap = propertyMap;
}
public boolean containsProperty(String key) {
return this.propertyMap.containsKey(key);
}
public Object getPropertyValue(String key) {
return containsProperty(key) ? this.propertyMap.get(key) : null;
}
public void putProperty(String key, Object value) {
this.propertyMap.put(key, value);
}
public List<String> getPropertyKeys() {
List<String> list = Collections.synchronizedList(new ArrayList<String>());
Iterator<String> iterators = this.propertyMap.keySet().iterator();
while (iterators.hasNext()) {
list.add(iterators.next());
}
return Collections.unmodifiableList(list);
}
public Integer getPropertyCount() {
return this.propertyMap.size();
}
}
Om du vill infoga eller utöka ett sådant objekt med hjälp av API:et för tabell mappar du egenskaperna för det expanderbara objektet till ett TableEntity-objekt och använder metoderna createEntity eller upsertEntity i TableClient-objektet efter behov.
public void insertExpandableEntity(ExpandableWeatherObject model) {
tableClient.createEntity(WeatherDataUtils.createTableEntity(model));
}
public void upsertExpandableEntity(ExpandableWeatherObject model) {
tableClient.upsertEntity(WeatherDataUtils.createTableEntity(model));
}
Uppdatera en entitet
Entiteter kan uppdateras genom att anropa metoden updateEntity i TableClient-objektet . Eftersom en entitet (rad) som lagras med tabell-API:et kan innehålla valfri godtycklig uppsättning egenskaper är det ofta användbart att skapa ett uppdateringsobjekt baserat på ett ordlisteobjekt som liknar det ExpandableWeatherObject
som beskrevs tidigare. I det här fallet är den enda skillnaden tillägget av en etag
egenskap som används för samtidighetskontroll under uppdateringar.
public class UpdateWeatherObject {
private String stationName;
private String observationDate;
private String etag;
private Map<String, Object> propertyMap = new HashMap<String, Object>();
public String getStationName() {
return stationName;
}
public void setStationName(String stationName) {
this.stationName = stationName;
}
public String getObservationDate() {
return observationDate;
}
public void setObservationDate(String observationDate) {
this.observationDate = observationDate;
}
public String getEtag() {
return etag;
}
public void setEtag(String etag) {
this.etag = etag;
}
public Map<String, Object> getPropertyMap() {
return propertyMap;
}
public void setPropertyMap(Map<String, Object> propertyMap) {
this.propertyMap = propertyMap;
}
}
I exempelappen skickas det här objektet till updateEntity
-metoden i TableServiceImpl
klassen. Den här metoden läser först in den befintliga entiteten från Tabell-API:et med metoden getEntity i TableClient. Den uppdaterar sedan entitetsobjektet och använder updateEntity
metoden för att spara uppdateringarna i databasen. Observera hur metoden updateEntity tar objektets aktuella Etag för att säkerställa att objektet inte har ändrats sedan det lästes in. Om du vill uppdatera entiteten oavsett kan du skicka ett värde etag
till updateEntity
metoden.
public void updateEntity(UpdateWeatherObject model) {
TableEntity tableEntity = tableClient.getEntity(model.getStationName(), model.getObservationDate());
Map<String, Object> propertiesMap = model.getPropertyMap();
propertiesMap.keySet().forEach(key -> tableEntity.getProperties().put(key, propertiesMap.get(key)));
tableClient.updateEntity(tableEntity);
}
Ta bort en entitet
Om du vill ta bort en entitet från en tabell anropar du metoden deleteEntity i TableClient-objektet med partitionsnyckeln och radnyckeln för objektet.
public void deleteEntity(WeatherInputModel model) {
tableClient.deleteEntity(model.getStationName(),
WeatherDataUtils.formatRowKey(model.getObservationDate(), model.getObservationTime()));
}
7 – Kör koden
Kör exempelprogrammet för att interagera med Azure Cosmos DB-tabell-API:et. Första gången du kör programmet finns det inga data eftersom tabellen är tom. Använd någon av knapparna överst i programmet för att lägga till data i tabellen.
Om du väljer knappen Infoga med tabellentitet öppnas en dialogruta där du kan infoga eller utöka en ny rad med hjälp av ett TableEntity
objekt.
När du väljer knappen Infoga med expanderbara data visas en dialogruta där du kan infoga ett objekt med anpassade egenskaper, vilket visar hur Azure Cosmos DB Tables API automatiskt lägger till egenskaper (kolumner) i tabellen när det behövs. Använd knappen Lägg till anpassat fält för att lägga till en eller flera nya egenskaper och demonstrera den här funktionen.
Använd knappen Infoga exempeldata för att läsa in exempeldata i azure Cosmos DB-tabellen.
Välj alternativet Filtrera resultat på den översta menyn som ska tas till sidan Filterresultat. På den här sidan fyller du i filtervillkoren för att visa hur en filtersats kan skapas och skickas till Azure Cosmos DB-tabell-API:et.
Rensa resurser
När du är klar med exempelprogrammet bör du ta bort alla Azure-resurser som är relaterade till den här artikeln från ditt Azure-konto. Du kan göra detta genom att ta bort resursgruppen.
Du kan ta bort en resursgrupp med hjälp av Azure-portalen genom att göra följande.
Nästa steg
I den här snabbstarten har du fått lära dig att skapa ett Azure Cosmos DB-konto, skapa en tabell med datautforskaren och att köra en app. Nu kan du köra frågor mot dina data med hjälp av API:et för Tabell.