Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

tweaking readme from user studies #15548

Merged
merged 8 commits into from
Dec 4, 2020
Merged

tweaking readme from user studies #15548

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
00f6a5d
tweaking readme from user studies
seankane-msft Nov 25, 2020
ff68caf
updating based on annas comments
seankane-msft Nov 25, 2020
d8aa02c
removing odata link
seankane-msft Nov 25, 2020
9d6a224
adding table on building query filters
seankane-msft Nov 25, 2020
8792cd8
changing odata link to link directly to table in samples readme
seankane-msft Nov 25, 2020
76dd89c
adding a test for multiple parameters in a query statement
seankane-msft Nov 30, 2020
626c7f8
addressing annas comments part 2, added direct links to snippets on w…
seankane-msft Dec 1, 2020
dd95bb6
fixed a typo in the creating/querying entities sections
seankane-msft Dec 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 77 additions & 77 deletions sdk/tables/azure-data-tables/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,66 +7,56 @@ The Azure Data Tables client can be used to access Azure Storage or Cosmos accou
[Source code][source_code] | [Package (PyPI)][Tables_pypi] | [API reference documentation][Tables_ref_docs] | [Samples][Tables_samples]

## Getting started
The Azure Data Tables can be accessed using an Azure Storage or a CosmosDB account.
The Azure Data Tables SDK can access an Azure Storage or CosmosDB account.

### Prerequisites
* Python 2.7, or 3.5 or later is required to use this package.
* You must have an [Azure subscription][azure_subscription] and either
* an [Azure storage account][azure_storage_account] or
* an [Azure Storage account][azure_storage_account] or
* an [Azure Cosmos Account][azure_cosmos_account].

#### Create a storage account
#### Create account
If you wish to create a new storage account, you can use [Azure Portal][azure_portal_create_account],
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
[Azure PowerShell][azure_powershell_create_account], or [Azure CLI][azure_cli_create_account]:

```bash
# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name MyResourceGroup --location westus2
# Create the storage account
az storage account create -n MyStorageAccount -g MyResourceGroup
```

#### Creating a Cosmos DB
If you wish to create a new cosmos storage account, you can use [Azure Cosmos DB][azure_create_cosmos].
Create a Cosmos DB account `MyCosmosDBDatabaseAccount` in resource group `MyResourceGroup` in the subscription `MySubscription` and a table named `MyTableName` in the account.
```bash
az cosmosdb create --name MyCosmosDBDatabaseAccount --resource-group MyResourceGroup --subscription MySubscription
az cosmosdb table create --name MyTableName --resource-group MyResourceGroup --acount-name MyCosmosDBDatabaseAccount
```

If you wish to create a new cosmos storage account, you can use [Azure Cosmos DB][azure_cli_create_cosmos].
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved

### Install the package
Install the Azure Data Tables client library for Python with [pip][pip_link]:

```bash
pip install --pre azure-data-tables
```


#### Create the client
The Azure Data Tables client library for Python allows you to interact with two types of resources: the
tables in your account, and the entities within the 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:

```python
from azure.data.tables import TableServiceClient
service = TableServiceClient(account_url="https://<myaccount>.table.core.windows.net/", credential=credential)
```
The Azure Data 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 account name portion of the `account_url` 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:
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved

```bash
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"
```

seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
```python
from azure.data.tables import TableServiceClient
service = TableServiceClient(account_url="https://<my_account_name>.table.core.windows.net/", credential=credential)
```

For more information about table service URL's and how to configure custom domain names for Azure Storage check out the [official documentation](azure_portal_account_url)

#### Types of credentials
The `credential` parameter may be provided in a number of different forms, depending on the type of authorization you wish to use:
The `credential` parameter may be provided in a number of different forms, depending on the type of authorization you wish to use. The Tables library supports the following authorizations:
* Shared Key
* Connection String
* Shared Access Signature Token
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved

##### Creating the client from a shared key
To use an account [shared key][azure_shared_key] (aka account key or access key), provide the key as a string. This can be found in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or by running the following Azure CLI command:
To use an account [shared key][azure_shared_key] (aka account key or access key), provide the key as a string. This can be found in your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or by running the following Azure CLI command:

```az storage account keys list -g MyResourceGroup -n MyStorageAccount```
```bash
az storage account keys list -g MyResourceGroup -n MyStorageAccount
```

Use the key as the credential parameter to authenticate the client:
```python
Expand All @@ -75,21 +65,21 @@ Use the key as the credential parameter to authenticate the client:
```

##### Creating the client from a connection string
Depending on your use case and authorization method, you may prefer to initialize a client instance with a
connection string instead of providing the account URL and credential separately. To do this, pass the
connection string to the client's `from_connection_string` class method:
Depending on your use case and authorization method, you may prefer to initialize a client instance with a connection string instead of providing the account URL and credential separately. To do this, pass the
connection string to the client's `from_connection_string` class method. The connection string can be found in your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or with the following Azure CLI command:

```bash
az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount
```

```python
from azure.data.tables import TableServiceClient
connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
connection_string = "DefaultEndpointsProtocol=https;AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=core.windows.net"
service = TableServiceClient.from_connection_string(conn_str=connection_string)
```

The connection string to your account can be found in the Azure Portal under the "Access Keys" section or by running the following CLI command:
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved

```bash
az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount
```

##### Creating the client from a SAS token
To use a [shared access signature (SAS) token][azure_sas_token], provide the token as a string. If your account URL includes the SAS token, omit the credential parameter. You can generate a SAS token from the Azure Portal under [Shared access signature](https://docs.microsoft.com/rest/api/storageservices/create-service-sas) or use one of the `generate_*_sas()`
Expand All @@ -110,16 +100,6 @@ To use a [shared access signature (SAS) token][azure_sas_token], provide the tok
table_service_client = TableServiceClient(account_url="https://<my_account_name>.table.core.windows.net", credential=sas_token)
```

#### Looking up the account URL
You can find the account's table service URL using the
[Azure Portal][azure_portal_account_url],
[Azure PowerShell][azure_powershell_account_url],
or [Azure CLI][azure_cli_account_url]:

```bash
# Get the table service URL for the account
az storage account show -n MyStorageAccount -g MyResourceGroup --query "primaryEndpoints.table"
```

## Key concepts
Common uses of the Table service included:
Expand All @@ -139,18 +119,18 @@ use of a dedicated client object.
### Clients
Two different clients are provided to interact with the various components of the Table Service:
1. **`TableServiceClient`** -
this client represents interaction with the Azure account itself, and allows you to acquire preconfigured
client instances to access the tables within. It provides operations to retrieve and configure the account
properties as well as query, create, and delete tables within the account. To perform operations on a specific table,
retrieve a client using the `get_table_client` method.
* Interacts with the Azure account itself
* Allows you to acquire preconfigured client instances to access the tables within.
* Provides operations to retrieve and configure the account
* Query, create, and delete tables within the account.
* To perform operations on a specific table, retrieve a client using the `get_table_client` method.
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
2. **`TableClient`** -
this client represents interaction with a specific table (which need not exist yet). It provides operations to
create, delete, or update a table and includes operations to query, get, and upsert entities
within it.
* Interacts with a specific table (which need not exist yet).
* Provides operations to create or delete a table
* Create, delete, query, get, and upsert entities within a table
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved

### Entities
Entities are similar to rows. An entity has a **`PartitionKey`**, a **`RowKey`** and a set of properties. A property is a name value pair, similar to a column.
Entities can be represented as dictionaries like this as an example:
Entities are similar to rows. An entity has a **`PartitionKey`**, a **`RowKey`**, and a set of properties. A property is a name value pair, similar to a column. Every entity in a table does not need to have the same properties. Entities can be represented as dictionaries like this as an example:
```python
entity = {
'PartitionKey': 'color',
Expand All @@ -160,12 +140,16 @@ entity = {
'price': '5'
}
```
* **Create** - Adds an entity to the table.
* **Delete** - Deletes an entity from the table.
* **Update** - Updates an entities information by either merging or replacing the existing entity.
* **Query** - Queries existing entities in a table based off of the QueryOptions (OData).
* **Get** - Gets a specific entity from a table by partition and row key.
* **Upsert** - Merges or replaces an entity in a table, or if the entity does not exist, inserts the entity.
* **Create** - Add an entity to the table.
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
* **Delete** - Delete an entity from the table.
* **Update** - Update an entity's information by either merging or replacing the existing entity.
* `UpdateMode.MERGE` will add new properties to an existing entity it will not delete an existing properties
* `UpdateMode.REPLACE` will replace the existing entity with the given one, deleting any existing properties not included in the submitted entity
* **Query** - Query existing entities in a table based off of the QueryOptions (OData).
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
* **Get** - Get a specific entity from a table by partition and row key.
* **Upsert** - Merge or replace an entity in a table, or if the entity does not exist, inserts the entity.
* `UpdateMode.MERGE` will add new properties to an existing entity it will not delete an existing properties
* `UpdateMode.REPLACE` will replace the existing entity with the given one, deleting any existing properties not included in the submitted entity

## Examples

Expand All @@ -177,21 +161,34 @@ The following sections provide several code snippets covering some of the most c


### Creating a table
Create a table in your account
Create a table in your account and get a `TableClient` to perform operations on the newly created table:

```python
from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_service_client.create_table(table_name="myTable")
table_name = "myTable
table_service_client.create_table(table_name=table_name)
table_client = table_service_client.get_table_client(table_name=table_name)
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
```

### Creating entities
Create entities in the table
Create entities in the table. The properties
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved

```python
from azure.data.tables import TableServiceClient

my_entity = {'PartitionKey':'part','RowKey':'row'}
from datetime import datetime

my_entity = {
'PartitionKey': 'product_name',
'RowKey': 'product_id'
seankane-msft marked this conversation as resolved.
Show resolved Hide resolved
'Stock': 15,
'Price': 9.99,
'Comments': "great product",
'OnSale': True,
'ReducedPrice': 7.99,
'PurchaseDate': datetime(1973, 10, 4),
'BinaryRepresentation': b'product_name
}

table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_client = table_service_client.get_table_client(table_name="myTable")
Expand All @@ -204,14 +201,15 @@ Querying entities in the table

```python
from azure.data.tables import TableClient
my_filter = "text eq 'Marker'"
my_filter = "RowKey eq 'product_id'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="mytable")
entity = table_client.query_entities(filter=my_filter)
entities = table_client.query_entities(filter=my_filter)
for entity in entities:
for key in entity.keys():
print("Key: {}, Value: {}".format(key, entity[key]))
```


## Optional Configuration

Optional keyword arguments can be passed in at the client and per-operation level. The azure-core [reference documentation][azure_core_ref_docs] describes available configurations for retries, logging, transport protocols, and more.


Expand Down Expand Up @@ -258,7 +256,7 @@ For examples, if you try to create a table that already exists, a `409` error is
```python
from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

Expand All @@ -270,6 +268,7 @@ try:
except HttpResponseError:
print("Table with name {} already exists".format(table_name))
```

### Logging
This library uses the standard
[logging][python_logging] library for logging.
Expand All @@ -295,8 +294,8 @@ service_client = TableServiceClient.from_connection_string("your_connection_stri
```

Similarly, `logging_enable` can enable detailed logging for a single operation,
even when it isn't enabled for the client:
```py
even when it is not enabled for the client:
```python
service_client.create_entity(entity=my_entity, logging_enable=True)
```

Expand Down Expand Up @@ -342,6 +341,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][msft_oss_co
[pip_link]:https://pypi.org/project/pip/

[azure_create_cosmos]:https://docs.microsoft.com/azure/cosmos-db/create-cosmosdb-resources-portal
[azure_cli_create_cosmos]:https://docs.microsoft.com/en-us/azure/cosmos-db/scripts/cli/table/create?toc=/cli/azure/toc.json
[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
Expand Down