Snabbstart: Skapa en API för tabellapp med Java SDK och Azure Cosmos DB
GÄLLER FÖR: Tabell
Den här snabbstarten visar hur du kommer åt Api:et för Azure Cosmos DB-tabeller från ett Java-program. Api:et för Azure Cosmos DB-tabeller ä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 någon Azure-prenumeration kan du skapa ett kostnadsfritt konto innan du börjar.
Exempelprogram
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 färdig 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 tabell-API:ets schemalösa funktioner.
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 Portal, Azure CLI eller Azure PowerShell.
Logga in på Azure Portal 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 Portal utför du följande steg för att skapa en tabell i ditt Azure Cosmos DB-konto.
3 – Hämta Azure Cosmos DB-anslutningssträng
För att få åtkomst till dina tabeller i Azure Cosmos DB behöver din app tabellanslutningssträngen för CosmosDB Storage-kontot. Anslutningssträngen kan hämtas med hjälp av Azure Portal, Azure CLI eller Azure PowerShell.
Anslutningssträngen för ditt Azure Cosmos DB-konto betraktas som 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 anslutningssträngen 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 Tables-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 skapar ett TableClient-objektböna som ska hanteras av Spring-containern och som en singleton för att åstadkomma detta.
TableServiceConfig.java
I filen för programmet redigerar tableClientConfiguration()
du 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 using-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 Tjänster . 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 listEntities 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 objektet TableEntity
.
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 detta ändamål. 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. Den använder sedan en ordlista för att lagra alla andra egenskaper på 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 avbilda alla. Den här klassen innehåller också metoder för att visa en lista över 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
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 OData-filtersträng till metoden listEntities . Om du till exempel vill hämta 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 FilterSystemfrågealternativ
I exempelprogrammet FilterResultsInputModel
är objektet utformat för att avbilda alla filterkriterier 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. Därefter 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 skapa 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 observationsdatum/-tid mappas till PartitionKey
egenskaperna respektive RowKey
) som tillsammans utgör en unik nyckel för raden i tabellen. Sedan mappas de ytterligare egenskaperna för indatamodellobjektet till ordlisteegenskaper för 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 felmeddelande. 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 upsert-data med variabelegenskaper
En av fördelarna med att använda Tabell-API för Azure Cosmos DB ä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 behöver 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 Table 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 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 att lägga till 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 Tables-API:et med hjälp av metoden getEntity på TableClient. Därefter uppdateras entitetsobjektet och metoden används updateEntity
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 från början. Om du vill uppdatera entiteten oavsett kan du skicka ett värde etag
för 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 upsert en ny rad med hjälp av ett TableEntity
-objekt.
Om du väljer knappen Infoga med expanderbara data öppnas en dialogruta där du kan infoga ett objekt med anpassade egenskaper, som visar hur Azure Cosmos DB-tabell-API:et automatiskt lägger till egenskaper (kolumner) i tabellen vid behov. 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 din Azure Cosmos DB-tabell.
Välj alternativet Filtrera resultat på den översta menyn för att gå 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 Portal 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 Table.