From 0e2f5b630d60513bb4dfdec5495b6a1faa340eed Mon Sep 17 00:00:00 2001 From: gearama <50641385+gearama@users.noreply.github.com> Date: Thu, 5 Sep 2024 13:13:04 -0700 Subject: [PATCH] Tables readme update (#5940) * tables readme update * oopsie * replace service name * updates per PR comments * rfwerwer * missing links * PR changes * erwerwe * entity1 * links --- sdk/tables/azure-data-tables/README.md | 189 ++++++++++++++----------- 1 file changed, 106 insertions(+), 83 deletions(-) diff --git a/sdk/tables/azure-data-tables/README.md b/sdk/tables/azure-data-tables/README.md index 5e2ed157a..bdf2627f0 100644 --- a/sdk/tables/azure-data-tables/README.md +++ b/sdk/tables/azure-data-tables/README.md @@ -4,35 +4,61 @@ Azure Data Tables is a NoSQL data storage service that can be accessed from anyw Tables scales as needed to support the amount of data inserted, and allows for the storing of data with non-complex accessing. The Azure Tables client can be used to access Azure Storage or Cosmos accounts. -[Source code][source_code] | [API reference documentation][source_code] - +[Source code][source_code] | [Package (vcpkg)](https://vcpkg.io/en/package/azure-data-tables-cpp) | [API reference documentation](https://azuresdkdocs.blob.core.windows.net/$web/cpp/azure-data-tables/latest/index.html) | [Product documentation](https://learn.microsoft.com/azure/storage/tables/) | [Samples](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/tables/azure-data-tables/samples) ## Getting started -The Azure Tables SDK can access an Azure Storage or CosmosDB account. ### Prerequisites +- [vcpkg](https://learn.microsoft.com/vcpkg/get_started/overview) for package acquisition and dependency management +- [CMake](https://cmake.org/download/) for project build +- An [Azure subscription][azure_sub] +- An existing Azure Storage Tables resource. If you need to create an Azure Storage Tables, you can use the Azure Portal or [Azure CLI][azure_cli]. * You must have an [Azure subscription][azure_subscription] and either * an [Azure Storage account][azure_storage_account] or * an [Azure Cosmos Account][azure_cosmos_account]. -#### Create account +If you use the Azure CLI, replace `` and `` with your own, unique names: + +```PowerShell +az login +az storage table create create --resource-group --name +``` +### Create account * To create a new Storage account, you can use [Azure Portal][azure_portal_create_account], [Azure PowerShell][azure_powershell_create_account], or [Azure CLI][azure_cli_create_account]: * To create a new Cosmos storage account, you can use the [Azure CLI][azure_cli_create_cosmos] or [Azure Portal][azure_portal_create_cosmos]. +### Install the package +The easiest way to acquire the C++ SDK is leveraging the vcpkg package manager and CMake. See the corresponding [Azure SDK for C++ readme section][azsdk_vcpkg_install]. We'll use vcpkg in manifest mode. To start a vcpkg project in manifest mode use the following command at the root of your project: -#### Create the client -The Azure Tables library allows you to interact with two types of resources: -* the tables in your account -* the entities within those tables. -Interaction with these resources starts with an instance of a [client](#clients). To create a client object, you will need the account's table service endpoint URL and a credential that allows you to access the account. The `endpoint` can be found on the page for your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or by running the following Azure CLI command: - -```bash -# Log in to Azure CLI first, this opens a browser window -az login -# Get the table service URL for the account -az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table" +```batch +vcpkg new --application ``` +To install the Azure \ package via vcpkg: +To add the Azure \ package to your vcpkg enter the following command (We'll also add the Azure Identity library for authentication): + +```batch +vcpkg add port azure-data-tables-cpp azure-identity-cpp +``` + +Then, add the following in your CMake file: + +```CMake +find_package(azure-data-tables-cpp CONFIG REQUIRED) +find_package(azure-identity-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-data-tables Azure::azure-identity) +``` + +Remember to set `CMAKE_TOOLCHAIN_FILE` to the path to `vcpkg.cmake` either by adding the following to your `CMakeLists.txt` file before your project statement: + +```CMake +set(CMAKE_TOOLCHAIN_FILE "vcpkg-root/scripts/buildsystems/vcpkg.cmake") +``` + +Or by specifying it in your CMake commands with the `-DCMAKE_TOOLCHAIN_FILE` argument. + +There is more than one way to acquire and install this library. Check out [our samples on different ways to set up your Azure C++ project][project_set_up_examples]. + ## Key concepts Common uses of the table service include: * Storing TBs of structured data capable of serving web scale applications @@ -48,29 +74,36 @@ The following components make up the Azure Tables Service: The Azure Tables client library for C++ allows you to interact with each of these components through the use of a dedicated client object. +### Create the client +The Azure Tables library allows you to interact with two types of resources: +* the tables in your account +* the entities within those tables. +Interaction with these resources starts with an instance of a [client](#clients). To create a client object, you will need the account's table service endpoint URL and a credential that allows you to access the account. The `endpoint` can be found on the page for your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or by running the following Azure CLI command: + +```bash +# Get the table service URL for the account +az storage account show -n -g --query "primaryEndpoints.table" +``` + +### Credentials + +We'll be using the `DefaultAzureCredential` to authenticate which will pick up the credentials we used when logging in with the Azure CLI earlier. `DefaultAzureCredential` can pick up on a number of Credential types from your environment and is ideal when getting started and developing. Check out our section on [DefaultAzureCredentials](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/identity/azure-identity#defaultazurecredential) to learn more. + ### Clients Two different clients are provided to interact with the various components of the Table Service: -1. **`TableClient`** - - * Interacts with a specific table (which need not exist yet). - * Create, delete, query, and upsert entities within the specified table. - * Submit transactional batch operations. -2. **`TableServiceClient`** - +1. **`TableServiceClient`** - * Get and set account settings * Query tables within the account. * Create or delete the specified table. -### Entities -Entities are similar to rows. An entity has a set of properties, including a **`PartitionKey`** and **`RowKey`** which form the primary key of the entity. A property is a name value pair, similar to a column. Every entity in a table does not need to have the same properties. +2. **`TableClient`** - + * Interacts with a specific table (which need not exist yet). + * Create, delete, query, and upsert entities within the specified table. + * Submit transactional batch operations. -## Examples -The following sections provide several code snippets covering some of the most common Table tasks, including: +#### TableServiceClient -* [Creating and deleting a table](#creating-and-deleting-a-table "Creating and deleting a table") -* [Manipulating entities](#manipulating-entities "Manipulating entities") -* [Table Service Operations](#table-service-operations "Table Service Operations") -* [Table Transactions Success](#table-transactions-success "Table Transactions Success") -* [Table Transactions Error](#table-transactions-error "Table Transactions Error") -### Creating and deleting a table +##### Creating and deleting a table In order to Create/Delete a table we need to create a TablesClient first. @@ -91,9 +124,38 @@ In order to Delete a table we need to call the delete method on the previously c // delete existing table tableServiceClient.DeleteTable(TableName); ``` +##### Table Service Operations -### Manipulating entities +To get the service properties we call the GetProperties method on the table service client. +```cpp + auto properties = tableServiceClient.GetProperties(); +``` +To list the tables in the account we call the ListTables method on the table service client. +```cpp + auto tables = tableServiceClient.ListTables(); +``` + +To get the statistics of the account we call the GetStatistics method on the table service client. +```cpp + auto statistics = tableServiceClient.GetStatistics(); +``` + +#### TableClient + +The TableClient is used to interact with table entities and perform operations on them. + +##### Get the table client from the service client +We create a table on which we run the transaction and get a table client. +```cpp +// create table +tableServiceClient.CreateTable(TableName); +// get table client from table service client +auto tableClient = tableServiceClient.GetTableClient(TableName); +``` +N.B. Here we are obtaining the table client from the table service client using the credentials that were passed to the table service client. + +##### Create a client with a connection string In order to Create/Update/Merge/Delete entities we need to create a TablesClient first. ```cpp @@ -103,9 +165,13 @@ using namespace Azure::Data::Tables; const std::string TableName = "sample1"; ... auto tableClient = TableClient::CreateFromConnectionString(..., TableName); -tableServiceClient.CreateTable(TableName); ``` +##### Entities +Entities are similar to rows. An entity has a set of properties, including a **`PartitionKey`** and **`RowKey`** which form the primary key of the entity. A property is a name value pair, similar to a column. Every entity in a table does not need to have the same properties. + +##### Manipulating entities + Then we initialize and populate an entity. ```cpp // init new entity @@ -136,53 +202,6 @@ To delete the entity, we call the DeleteEntity method on the table client. tableClient.DeleteEntity(entity); ``` -### Table Service Operations - -In order to get the service properties we need to create a TableServiceClient first. - -```cpp -#include -... -using namespace Azure::Data::Tables; -... -auto tableServiceClient = TableServiceClient::CreateFromConnectionString(...); -``` - -To get the service properties we call the GetProperties method on the table service client. -```cpp - auto properties = tableServiceClient.GetProperties(); -``` - -To list the tables in the account we call the ListTables method on the table service client. -```cpp - auto tables = tableServiceClient.ListTables(); -``` - -To get the statistics of the account we call the GetStatistics method on the table service client. -```cpp - auto statistics = tableServiceClient.GetStatistics(); -``` - -### Table Transactions Success - -In order to get the service properties we need to create a TableServiceClient first. - -```cpp -#include -... -using namespace Azure::Data::Tables; -... -auto tableServiceClient = TableServiceClient::CreateFromConnectionString(...); -``` - -We create a table on which we run the transaction and get a table client. -```cpp -// create table -tableServiceClient.CreateTable(TableName); -// get table client from table service client -auto tableClient = tableServiceClient.GetTableClient(TableName); -``` -N.B. Here we are obtaining the table client from the table service client using the credentials that were passed to the table service client. We initialize and populate the entities. ```cpp @@ -203,7 +222,7 @@ We create a transaction batch and add the operations to the transaction. ```cpp // Create a transaction with two steps std::vector steps; -steps.emplace_back(TransactionStep{TransactionActionType::Add, entity}); +steps.emplace_back(TransactionStep{TransactionActionType::Add, entity1}); steps.emplace_back(TransactionStep{TransactionActionType::Add, entity2}); ``` @@ -226,12 +245,12 @@ The output of this sample is: Transaction completed successfully. ``` -### Table Transactions Error +##### Table Transactions Error The difference from the previous example is that we are trying to add two entities with the same PartitionKey and RowKey. ```cpp // Create two table entities -TableEntity entity; +TableEntity entity1; TableEntity entity2; entity.SetPartitionKey("P1"); entity.SetRowKey("R1"); @@ -275,7 +294,8 @@ additional questions or comments. [coc_contact]: mailto:opencode@microsoft.com [source_code]:https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/ [Tables_product_doc]:https://docs.microsoft.com/azure/cosmos-db/table-introduction - +[azure_sub]: https://azure.microsoft.com/free/ +[azure_cli]: https://docs.microsoft.com/cli/azure [azure_subscription]:https://azure.microsoft.com/free/ [azure_storage_account]:https://docs.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal [azure_cosmos_account]:https://docs.microsoft.com/azure/cosmos-db/create-cosmosdb-resources-portal @@ -285,3 +305,6 @@ additional questions or comments. [azure_portal_create_account]:https://docs.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal [azure_powershell_create_account]:https://docs.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-powershell [azure_cli_create_account]: https://docs.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-cli +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#getting-started +[project_set_up_examples]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration +