Поделиться через

Использование хранилища таблиц Azure и Azure Cosmos DB для таблиц с Ruby

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: Таблица

Предупреждение

Этот проект находится на этапе поддержки сообщества в его жизненном цикле. В конечном итоге все связанные клиентские библиотеки будут выведены из эксплуатации окончательно. Дополнительные сведения о прекращении поддержки и альтернативах использованию этого проекта см. в статье Уведомление о прекращении поддержки: клиентские библиотеки PHP службы хранилища Azure.

Совет

Содержимое этой статьи относится к хранилищу таблиц Azure и Azure Cosmos DB для таблиц. API для таблиц — это предложение уровня "Премиум" для хранилища таблиц, которое предлагает оптимизированные для пропускной способности таблицы, глобальное распределение и автоматические вторичные индексы.

В этой статье показано, как создавать таблицы, сохранять данные и выполнять операции CRUD с данными. Выберите службу таблиц Azure или Azure Cosmos DB для таблицы. В приведенных в этой статье примерах, написанных на Ruby, используется клиентская библиотека таблиц службы хранилища Azure для Ruby. Рассматриваемые сценарии включают в себя создание таблицы, удаление таблицы, вставку сущностей и запрос сущностей из таблицы.

Создание учетной записи службы Azure

Вы можете работать с таблицами, используя хранилище таблиц Azure или Azure Cosmos DB. Дополнительные сведения о различиях между предложениями таблиц в этих двух службах см. в статье Общие сведения об API для таблиц. Необходимо создать учетную запись для службы, которую вы собираетесь использовать. В следующих разделах показано, как создать и хранилище таблиц Azure, и учетную запись Azure Cosmos DB, однако можно использовать что-то одно.

Хранилище таблиц Azure

Самый простой способ создать учетную запись хранения Azure — воспользоваться порталом Azure. Дополнительную информацию см. в статье Об учетных записях хранения Azure.

Учетную запись хранения Azure можно создать также с помощью Azure PowerShell или Azure CLI.

Если вы не хотите сейчас создавать учетную запись хранения, код можно запустить и протестировать в локальной среде с помощью эмулятора хранения Azure. Дополнительные сведения см. в статье Использование Эмулятора службы хранилища Azure для разработки и тестирования.

Azure Cosmos DB for Table

Инструкции по созданию учетной записи Azure Cosmos DB для таблицы см. в статье Создание учетной записи базы данных.

Добавление доступа к службе хранилища Azure или Azure Cosmos DB

Чтобы использовать службу хранилища Azure или Azure Cosmos DB, скачайте и используйте пакет Azure Ruby. Этот пакет включает набор удобных библиотек, взаимодействующих со службами REST таблиц.

Использование RubyGems для получения пакета

  1. Используйте интерфейс командной строки, например PowerShell (Windows), Terminal (Mac) или Bash (Unix).
  2. Введите gem install azure-storage-table в окне командной строки, чтобы установить пакет gem и зависимости.

Импорт пакета

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

require "azure/storage/table"

Добавление строки подключения

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

Добавление подключения к службе хранилища Azure

Модуль службы хранилища Azure считывает переменные среды AZURE_STORAGE_ACCOUNT и AZURE_STORAGE_ACCESS_KEY, чтобы получить информацию, необходимую для подключения к учетной записи хранения Azure. Если эти переменные среды не заданы, необходимо указать сведения об учетной записи перед использованием Azure::Storage::TableService со следующим кодом:

Azure.config.storage_account_name = "<your Azure Storage account>"
Azure.config.storage_access_key = "<your Azure Storage access key>"

Вот как можно получить эти значения из классический учетной записи хранения или учетной записи хранения Resource Manager на портале Azure.

  1. Войдите на портал Azure.
  2. Перейдите к учетной записи хранения, которая будет использоваться.
  3. На странице Параметры выберите Ключи доступа.
  4. На странице Ключи доступа просмотрите ключи доступа 1 и ключ доступа 2. Вы можете использовать любой из этих ключей.
  5. Щелкните значок копирования, чтобы скопировать ключ в буфер обмена.

Добавление подключения к Azure Cosmos DB

Чтобы подключиться к Azure Cosmos DB, скопируйте первичную строку подключения c портала Azure и с ее помощью создайте объект Client. Объект Client можно передать при создании объекта TableService.

common_client = Azure::Storage::Common::Client.create(storage_account_name:'myaccount', storage_access_key:'mykey', storage_table_host:'mycosmosdb_endpoint')
table_client = Azure::Storage::Table::TableService.new(client: common_client)

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

Объект Azure::Storage::Table::TableService позволяет работать с таблицами и сущностями. Чтобы создать таблицу, используйте метод create_table() . В следующем примере создается таблица или выводится ошибка, если она есть.

azure_table_service = Azure::Storage::Table::TableService.new
begin
    azure_table_service.create_table("testtable")
rescue
    puts $!
end

Добавление сущности в таблицу

Чтобы добавить сущность, сначала создайте хэш-объект, который определяет свойства сущности. Для каждой сущности необходимо указать PartitionKey и RowKey. Эти сущности являются уникальными идентификаторами сущностей и представляют собой значения, которые можно запрашивать быстрее, чем другие свойства. Служба хранилища Azure использует PartitionKey , чтобы автоматически распространять сущности таблицы на множество узлов хранилища. Сущности с одним значением PartitionKey хранятся на одном узле. RowKey — это уникальный идентификатор сущности в разделе, которому она принадлежит.

entity = { "content" => "test entity",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.insert_entity("testtable", entity)

Обновление сущности

Для обновления имеющейся сущности доступно несколько методов:

Описание
update_entity() обновляет имеющуюся сущность путем ее замены.
merge_entity() обновляет сущность посредством объединения новых значений свойств с имеющейся сущностью.
insert_or_merge_entity() обновляет имеющуюся сущность путем ее замены. Если сущности не существует, вставляется новая.
insert_or_replace_entity() обновляет сущность посредством объединения новых значений свойств с имеющейся сущностью. Если сущности не существует, вставляется новая.

В следующем примере показано обновление сущности с помощью метода update_entity() .

entity = { "content" => "test entity with updated content",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.update_entity("testtable", entity)

При использовании update_entity() и merge_entity(), если обновляемая сущность не существует, операция обновления завершается ошибкой. Поэтому, если вы хотите сохранить сущность независимо от того, существует она или нет, используйте метод insert_or_replace_entity() или insert_or_merge_entity() .

Работа с группами сущностей

Иногда имеет смысл отправлять совместно несколько операций в пакете для атомарной обработки сервером. Для этого сначала требуется создать объект Batch, а затем использовать метод execute_batch() для TableService. В следующем примере показана отправка двух сущностей с RowKey 2 и 3 в пакете. Обратите внимание, что пример работает только для сущностей с одинаковым значением PartitionKey.

azure_table_service = Azure::TableService.new
batch = Azure::Storage::Table::Batch.new("testtable",
    "test-partition-key") do
    insert "2", { "content" => "new content 2" }
    insert "3", { "content" => "new content 3" }
end
results = azure_table_service.execute_batch(batch)

Запрос сущности

Чтобы отправить запрос к сущности в таблице, используйте метод get_entity() : передайте имя таблицы, PartitionKey и RowKey.

result = azure_table_service.get_entity("testtable", "test-partition-key",
    "1")

Запрос набора сущностей

Чтобы отправить запрос к набору сущностей в таблице, создайте хэш-объект запроса и используйте метод query_entities() . В следующем примере показано, как получить все сущности с одним значением PartitionKey:

query = { :filter => "PartitionKey eq 'test-partition-key'" }
result, token = azure_table_service.query_entities("testtable", query)

Примечание

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

Запрос подмножества свойств сущности

Запрос к таблице может получить лишь несколько свойств сущности. Этот метод "проекции" снижает пропускную способность и может повысить производительность запросов, особенно для крупных сущностей. Используйте предложение select и передайте имена свойств, которые необходимо передать клиенту.

query = { :filter => "PartitionKey eq 'test-partition-key'",
    :select => ["content"] }
result, token = azure_table_service.query_entities("testtable", query)

Удаление сущности

Чтобы удалить сущность, используйте метод delete_entity() . Передайте имя таблицы, содержащей сущность, а также свойства PartitionKey и RowKey сущности.

azure_table_service.delete_entity("testtable", "test-partition-key", "1")

Удаление таблицы

Чтобы удалить таблицу, используйте метод delete_table() и передайте имя удаляемой таблицы.

azure_table_service.delete_table("testtable")

См. также