Клиентская библиотека таблиц Azure для Python версии 12.4.4

Таблицы Azure — это служба хранилища данных NoSQL, доступ к которому можно получить из любой точки мира через вызовы с проверкой подлинности по протоколу HTTP или HTTPS. Таблицы масштабируются по мере необходимости для поддержки объема вставленных данных и позволяют хранить данные при несложном доступе. Клиент таблиц Azure можно использовать для доступа к учетным записям службы хранилища Azure или Cosmos. В этом документе рассматривается azure-data-tables.

Обратите внимание, что этот пакет является заменой, для azure-cosmosdb-tables которого теперь не рекомендуется. Дополнительные сведения см. в руководстве по миграции .

Исходный код | Пакет (PyPI) | Пакет (Conda) | Справочная документация по | APIОбразцы

Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. в https://github.com/Azure/azure-sdk-for-python/issues/20691 статье Python 3.7 или более поздней версии, необходимой для использования этого пакета. Дополнительные сведения см. в статье Политика поддержки версий пакета Azure SDK для Python.

Начало работы

Пакет SDK таблиц Azure может получить доступ к учетной записи службы хранилища Azure или CosmosDB.

Предварительные требования

• Для использования этого пакета требуется Python 3.7 или более поздней версии.
• У вас должна быть подписка Azure и один из следующих вариантов:
  • учетная запись хранения Azure или
  • учетная запись Azure Cosmos.

Создание учетной записи

• Чтобы создать учетную запись хранения, можно использовать портал Azure, Azure PowerShell или Azure CLI:
• Чтобы создать учетную запись хранения Cosmos, можно использовать Azure CLI или портал Azure.

Установка пакета

Установите клиентую библиотеку таблиц Azure для Python с помощью pip:

pip install azure-data-tables

Создание клиента

Библиотека таблиц Azure позволяет взаимодействовать с двумя типами ресурсов:

• таблицы в вашей учетной записи
• сущностей в этих таблицах. Взаимодействие с этими ресурсами начинается с экземпляра клиента. Чтобы создать объект клиента, потребуется URL-адрес конечной точки службы таблиц учетной записи и учетные данные, позволяющие получить доступ к учетной записи. Можно endpoint найти на странице учетной записи хранения на портале Azure в разделе "Ключи доступа" или с помощью следующей команды Azure CLI:

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

Получив URL-адрес учетной записи, его можно использовать для создания клиента службы:

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

Дополнительные сведения об URL-адресах службы таблиц и настройке имен личных доменов для службы хранилища Azure проверка в официальной документации.

Типы учетных данных

Параметр credential может предоставляться в различных формах в зависимости от типа авторизации, которую вы хотите использовать. Библиотека таблиц поддерживает следующие разрешения:

• Общий ключ
• Строка подключения
• Маркер подписанного URL-адреса

Создание клиента на основе общего ключа

Чтобы использовать общий ключ учетной записи (ключ учетной записи или ключ доступа), укажите ключ в виде строки. Его можно найти в учетной записи хранения на портале Azure в разделе "Ключи доступа" или с помощью следующей команды Azure CLI:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Используйте ключ в качестве параметра учетных данных для проверки подлинности клиента:

from azure.core.credentials import AzureNamedKeyCredential
from azure.data.tables import TableServiceClient

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")

service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=credential)

Создание клиента из строки подключения

В зависимости от варианта использования и метода авторизации можно инициализировать экземпляр клиента с помощью строки подключения, а не указывать URL-адрес учетной записи и учетные данные отдельно. Для этого передайте строку подключения в метод класса клиента from_connection_string . Строку подключения можно найти в учетной записи хранения на портале Azure в разделе "Ключи доступа" или с помощью следующей команды Azure CLI:

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

from azure.data.tables import TableServiceClient
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)

Создание клиента из маркера SAS

Чтобы использовать маркер подписанного URL-адреса (SAS), укажите маркер в виде строки. Если URL-адрес учетной записи содержит маркер SAS, опустите параметр учетных данных. Вы можете создать маркер SAS на портале Azure в разделе Подписанный URL-адрес или использовать одну из generate_*_sas() функций для создания маркера SAS для учетной записи или таблицы:

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

table_service_client = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token))

Основные понятия

Ниже перечислены распространенные варианты использования службы таблиц.

• Хранение терабайтов структурированных данных с возможностью обслуживания приложений с веб-масштабированием.
• Хранение наборов данных, которые не требуют сложных соединений, внешних ключей или хранимых процедур и могут быть денормализованы для быстрого доступа
• Быстрый запрос данных с помощью кластерного индекса.
• Доступ к данным с помощью протокола OData и выражений фильтра LINQ

Служба таблиц Azure состоит из следующих компонентов:

• Учетная запись
• Таблица в учетной записи, содержащая набор сущностей.
• Сущность в таблице в виде словаря

Клиентская библиотека таблиц Azure для Python позволяет взаимодействовать с каждым из этих компонентов с помощью выделенного клиентского объекта.

Клиенты

Для взаимодействия с различными компонентами службы таблиц предоставляются два разных клиента:

1. TableServiceClient -
   • Получение и настройка параметра учетной записи
   • Запрашивать, создавать и удалять таблицы в учетной записи.
   • TableClient Получите для доступа к определенной таблице с помощью get_table_client метода .
2. TableClient -
   • Взаимодействует с определенной таблицей (которая еще не должна существовать).
   • Создание, удаление, запрос и upsert сущностей в указанной таблице.
   • Создайте или удалите указанную таблицу.

Сущности

Сущности аналогичны строкам. Сущность имеет PartitionKey, RowKeyи набор свойств. Свойство — это пара значений имени, аналогичная столбцу. У каждой сущности в таблице не обязательно должны быть одинаковые свойства. Сущности можно представить в виде словарей, например:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}

• create_entity — добавление сущности в таблицу.
• delete_entity — удаление сущности из таблицы.
• update_entity — обновление сведений о сущности путем слияния или замены существующей сущности.
  • UpdateMode.MERGE добавит новые свойства к существующей сущности, но не удалит существующие свойства.
  • UpdateMode.REPLACE заменит существующую сущность заданной, удалив все существующие свойства, не включенные в отправленную сущность
• query_entities . Запрос существующих сущностей в таблице с помощью фильтров OData.
• get_entity — получение определенной сущности из таблицы по разделу и ключу строки.
• upsert_entity — слияние или замена сущности в таблице или, если сущность не существует, вставляет сущность.
  • UpdateMode.MERGE добавит новые свойства к существующей сущности, но не удалит существующие свойства.
  • UpdateMode.REPLACE заменит существующую сущность заданной, удалив все существующие свойства, не включенные в отправленную сущность

Примеры

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач таблицы, в том числе:

• Создание таблицы
• Создание сущностей
• Запрос сущностей

Создание таблицы

Создайте таблицу в своей учетной TableClient записи и получите для выполнения операций с созданной таблицей:

from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_name = "myTable"
table_client = table_service_client.create_table(table_name=table_name)

Создание сущностей

Создайте сущности в таблице:

from azure.data.tables import TableServiceClient
from datetime import datetime

PRODUCT_ID = u'001234'
PRODUCT_NAME = u'RedMarker'

my_entity = {
    u'PartitionKey': PRODUCT_NAME,
    u'RowKey': PRODUCT_ID,
    u'Stock': 15,
    u'Price': 9.99,
    u'Comments': u"great product",
    u'OnSale': True,
    u'ReducedPrice': 7.99,
    u'PurchaseDate': datetime(1973, 10, 4),
    u'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")

entity = table_client.create_entity(entity=my_entity)

Запрашивание сущностей

Запрос сущностей в таблице:

from azure.data.tables import TableClient
my_filter = "PartitionKey eq 'RedMarker'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="myTable")
entities = table_client.query_entities(my_filter)
for entity in entities:
    for key in entity.keys():
        print("Key: {}, Value: {}".format(key, entity[key]))

Дополнительная настройка

Необязательные аргументы ключевое слово можно передавать на уровне клиента и для каждой операции. В справочной документации azure-Core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.

Конфигурация политики повторных попыток

Используйте следующие аргументы ключевое слово при создании экземпляра клиента для настройки политики повторных попыток:

• retry_total (int): общее количество разрешенных повторных попыток. Имеет приоритет над другими счетчиками. retry_total=0 Передайте, если вы не хотите повторять запросы. Значение по умолчанию равно 10.
• retry_connect (int): количество ошибок, связанных с подключением, для выполнения повторных попыток. Значение по умолчанию — 3.
• retry_read (int): количество повторов при ошибках чтения. Значение по умолчанию — 3.
• retry_status (int): количество повторных попыток при выполнении недопустимых кодов состояния. Значение по умолчанию — 3.
• retry_to_secondary (логическое значение) — указывает, следует ли повторно выполнять запрос в дополнительный, если это возможно. Это должно быть включено только для учетных записей RA-GRS, и могут обрабатываться потенциально устаревшие данные. По умолчанию — False.

Другая конфигурация клиента или каждой операции

Другая необязательная конфигурация ключевое слово аргументы, которые можно указать на клиенте или для каждой операции.

Аргументы ключевое слово клиента:

• connection_timeout (int). При необходимости задает значение времени ожидания подключения и чтения в секундах.
• transport (Любой): предоставленный пользователем транспорт для отправки HTTP-запроса.

Аргументы ключевое слово для каждой операции:

• raw_response_hook (вызываемый): данный обратный вызов использует ответ, возвращенный службой.
• raw_request_hook (вызываемый): данный обратный вызов использует запрос перед отправкой в службу.
• client_request_id (str): необязательный идентификатор запроса, указанный пользователем.
• user_agent (str): добавляет пользовательское значение в заголовок user-agent для отправки вместе с запросом.
• logging_enable (bool): включает ведение журнала на уровне DEBUG. Значение по умолчанию — False. Также можно передать на уровне клиента, чтобы включить его для всех запросов.
• headers (dict). Передайте пользовательские заголовки в виде пар "ключ— значение". Например, headers={'CustomValue': value}

Устранение неполадок

Общие сведения

Клиенты таблиц Azure вызывают исключения, определенные в Azure Core. При взаимодействии с библиотекой таблиц Azure с помощью пакета SDK для Python ошибки, возвращаемые службой, отвечают на те же коды состояния HTTP для запросов REST API . Операции службы таблиц будут вызывать исключение при сбое HttpResponseError с полезными кодами ошибок.

Например, при попытке создать уже существующую таблицу возвращается ошибка с сообщением 409 "Конфликт".

from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

# Create the table if it does not already exist
tc = service_client.create_table_if_not_exists(table_name)

try:
    service_client.create_table(table_name)
except HttpResponseError:
    print("Table with name {} already exists".format(table_name))

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :

import sys
import logging
from azure.data.tables import TableServiceClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = TableServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Аналогичным logging_enable образом можно включить подробное ведение журнала для одной операции, даже если она не включена для клиента:

service_client.create_entity(entity=my_entity, logging_enable=True)

Дальнейшие действия

Начните работу с примерами таблиц.

Несколько примеров пакета SDK для Python для таблиц Azure доступны в репозитории GitHub пакета SDK. В этих примерах приведен пример кода для дополнительных сценариев, часто встречающихся при работе с таблицами.

Распространенные сценарии

В этих примерах кода показаны распространенные операции сценария с клиентской библиотекой таблиц Azure. Асинхронные версии примеров (файлы примеров Python, добавленные с помощью _async) отображают асинхронные операции.

• Создание и удаление таблиц: sample_create_delete_table.py (асинхронная версия)
• Список таблиц и запросов: sample_query_tables.py (асинхронная версия)
• Вставка и удаление сущностей: sample_insert_delete_entities.py (асинхронная версия)
• Запрос и перечисление сущностей: sample_query_table.py (асинхронная версия)
• Обновление, upsert и слияние сущностей: sample_update_upsert_merge_entities.py (асинхронная версия)
• Фиксация нескольких запросов в одной транзакции: sample_batching.py (асинхронная версия)

Дополнительная документация

Более подробную документацию по таблицам Azure см. в документации по таблицам Azure по docs.microsoft.com.

Известные проблемы

Список известных в настоящее время проблем, связанных с конечными точками таблиц Cosmos DB, можно найти здесь.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.