From 38ea3a94f85d478f77c91cacb6e8785634885284 Mon Sep 17 00:00:00 2001 From: Brandon Siegel Date: Tue, 1 Sep 2020 14:09:26 -0700 Subject: [PATCH] Update Tables README --- sdk/tables/azure-data-tables/README.md | 163 +++++++++++++++++++++++-- 1 file changed, 156 insertions(+), 7 deletions(-) diff --git a/sdk/tables/azure-data-tables/README.md b/sdk/tables/azure-data-tables/README.md index a60e6c7ab5995..fd1f3abb94aa0 100644 --- a/sdk/tables/azure-data-tables/README.md +++ b/sdk/tables/azure-data-tables/README.md @@ -4,14 +4,15 @@ key/attribute store with a schemaless design. Tables storage gives developers fl best parts of Azure cloud. [Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_documentation] -| [Product documentation][azconfig_docs] | [Samples][samples] +| [REST API documentation][rest_api] | [Product documentation][product_documentation] | [Samples][samples] ## Getting started ### Prerequisites -- Java Development Kit (JDK) with version 8 or above +- [Java Development Kit (JDK)][jdk] with version 8 or above - [Azure Subscription][azure_subscription] +- An existing Azure storage account or Azure Cosmos DB Table API account ### Include the Package @@ -25,17 +26,159 @@ best parts of Azure cloud. ``` [//]: # ({x-version-update-end}) +### Create a Storage Account +To create a Storage Account you can use the [Azure Portal][storage_account_create_portal] or [Azure CLI][storage_account_create_cli]. + +```bash +az storage account create \ + --resource-group \ + --name \ + --location +``` + +Your storage account URL, subsequently identified as ``, would be formatted as follows +`http(s)://.table.core.windows.net`. + +### Create a Cosmos DB Table API account +To create a Cosmos DB Table API account you can use the [Azure Portal][cosmosdb_create_portal] or [Azure CLI][cosmosdb_create_cli]. + +```bash +az cosmosdb create \ + --resource-group \ + --name + --capabilities EnableTable +``` + +Your Table API account URL, subsequently identified as ``, would be formatted as follows +`http(s)://.table.cosmosdb.azure.com`. + ## Key concepts +Common uses of the Table service include: + +- Storing TBs of structured data capable of serving web scale applications +- Storing datasets that don't require complex joins, foreign keys, or stored procedures and can be de-normalized for fast access +- Quickly querying data using a clustered index +- Accessing data using the OData protocol + +Learn more about options for authentication _(including Connection Strings, Shared Key Authentication, and Shared Access Signatures)_ [in our samples][samples]. + ## Examples -Use the client library for Tables to: -- manages tables -- edit and access table contents + +### Create, List, and Delete Azure tables + +First, we need to construct a `TableServiceClient`. + +```java +TableServiceClient tableServiceClient = new TableServiceClientBuilder() + .endpoint("") + .sasToken("") + .buildClient(); +``` + +Next, we can create a new table. + +```java +tableServiceClient.createTable(tableName); +``` + +The set of existing Azure tables can be queries using an OData filter. + +```java +ListTablesOptions options = new ListTablesOptions() + .setFilter(String.format("TableName eq '%s'", tableName)); + +for (TableItem tableItem : tableServiceClient.listTables(options)) { + System.out.println(tableItem.getName()); +} +``` + +Individual tables can be deleted from the service. + +```java +tableServiceClient.deleteTable(tableName); +``` + +### Add, Query, and Delete table entities + +To interact with table entities, we must first construct a `TableClient`. + +```java +TableClient tableClient = new TableClientBuilder() + .endpoint("") + .sasToken("") + .tableName(tableName) + .buildClient(); +``` + +Alternatively, a `TableClient` can be retrieved from an existing `TableServiceClient`. + +```java +TableClient tableClient = tableServiceClient.getTableClient(tableName); +``` + +Define a new `TableEntity` with some properties so that we can add it to the table. + +```java +TableEntity entity = new TableEntity(partitionKey, rowKey) + .addProperty("Product", "Marker Set") + .addProperty("Price", 5.00) + .addProperty("Quantity", 21); +``` + +Using the `TableClient` we can now add our new entity to the table. + +```java +tableClient.createEntity(entity); +``` + +To inspect the set of existing table entities, we can query the table using an OData filter. + +```java +ListEntitiesOptions options = new ListEntitiesOptions() + .setFilter(String.format("PartitionKey eq '%s'", partitionKey)); + +for (TableEntity entity : tableClient.listEntities(options)) { + System.out.println(String.format("%s: %.2f", entity.getProperty("Product"), entity.getProperty("Price"))); +} +``` + +If we no longer need our new table entity, it can be deleted. + +```java +tableClient.deleteEntity(partitionKey, rowKey); +``` ## Troubleshooting +When you interact with the Azure table library, errors returned by the service correspond to the same HTTP +status codes returned for [REST API][rest_api] requests. + +For example, if you try to create a table that already exists, a `409` error is returned, indicating "Conflict". + +```java +TableServiceClient tableServiceClient = new TableServiceClientBuilder() + .endpoint("") + .sasToken("") + .buildClient(); + +// Create the table if it doesn't already exist. + +tableServiceClient.createTableIfNotExists(tableName); + +// Now attempt to create the same table unconditionally. + +try { + tableServiceClient.createTable(tableName); +} catch (TableServiceErrorException e) { + System.out.println(e.getResponse().getStatusCode()); // 409 +} +``` + ## Next steps +Get started with our [Table samples][samples]. + ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution. @@ -51,9 +194,15 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m [coc_contact]: mailto:opencode@microsoft.com [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ [coc]: https://opensource.microsoft.com/codeofconduct/ +[cosmosdb_create_cli]: https://docs.microsoft.com/en-us/azure/cosmos-db/scripts/cli/table/create +[cosmosdb_create_portal]: https://docs.microsoft.com/en-us/azure/cosmos-db/create-table-java#create-a-database-account +[jdk]: https://docs.microsoft.com/java/azure/jdk/ [package]: https://search.maven.org/artifact/com.azure/azure-data-tables -[samples_readme]: src/samples/README.md +[product_documentation]: https://docs.microsoft.com/en-us/azure/cosmos-db/table-storage-overview +[rest_api]: https://docs.microsoft.com/en-us/rest/api/storageservices/table-service-rest-api [samples]: src/samples/java/ [source_code]: src +[storage_account_create_cli]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-cli +[storage_account_create_portal]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Ftables%2Fazure-data-tables%2FREADME.png) \ No newline at end of file +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Ftables%2Fazure-data-tables%2FREADME.png)