Tables readme update (#5940)
* tables readme update * oopsie * replace service name * updates per PR comments * rfwerwer * missing links * PR changes * erwerwe * entity1 * links
This commit is contained in:
gearama
GitHub
parent
ea3f1442b2
commit
0e2f5b630d
@ -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 `<your-resource-group-name>` and `<your-tables-name>` with your own, unique names:
|
||||
|
||||
```PowerShell
|
||||
az login
|
||||
az storage table create create --resource-group <your-resource-group-name> --name <your-tables-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 \<Service-Name> package via vcpkg:
|
||||
To add the Azure \<Service-Name> 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(<your project name> 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 <your-storage-account> -g <your-resource-group-name> --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 <azure/data/tables.hpp>
|
||||
...
|
||||
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 <azure/data/tables.hpp>
|
||||
...
|
||||
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<TransactionStep> 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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user