Руководство. Запрос Azure Cosmos DB с помощью API для таблицы

Статья
08/15/2024

Область применения: Таблица

Azure Cosmos DB для таблицы поддерживает запросы OData и LINQ к данным key/value (table).

В этой статье рассматриваются следующие задачи:

Запрос данных с помощью API для таблицы

Запросы в этой статье используют следующий пример таблицы People:

PartitionKey	RowKey	Эл. почта	PhoneNumber
Harp	Николай	Walter@contoso.com	425-555-0101
Иванов	Ben	Ben@contoso.com	425-555-0102
Иванов	Jeff	Jeff@contoso.com	425-555-0104

Дополнительные сведения о том, как запрашивать с помощью API для таблицы, см. в статье "Запросы таблиц и сущностей".

Необходимые компоненты

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

Запросы PartitionKey и RowKey

Так как свойства PartitionKey и RowKey образуют первичный ключ сущности, вы можете использовать специальный синтаксис, чтобы идентифицировать сущность:

Запрос

https://<mytableendpoint>/People(PartitionKey='Harp',RowKey='Walter')

Результаты

PartitionKey	RowKey	Эл. почта	PhoneNumber
Harp	Николай	Walter@contoso.com	425-555-0104

В качестве альтернативы вы можете указать эти свойства как часть параметра $filter, как показано в следующем разделе. Имена ключевых свойств и константные значения чувствительны к регистру. Свойства PartitionKey и RowKey относятся к типу String.

Запрос с помощью фильтра OData

При построении строки фильтра помните о следующих правилах.

Используйте логические операторы, определенные спецификацией протокола OData, чтобы сравнить свойство со значением. Невозможно сравнить свойство с динамическим значением. Одна часть выражения должна быть константой.
Пробелы, закодированные URL-адресом, должны разделять имя свойства, оператор и константное значение. Пробелы кодируются в формате URL-адреса как %20.
Во всех частях строки фильтра учитывается регистр.
Для получения допустимых результатов фильтра значения константы и свойства должны иметь одинаковый тип данных. Дополнительные сведения о поддерживаемых типах свойств см. в разделе "Общие сведения о модели данных службы таблиц".

Вот пример запроса, который показывает, как выполнить фильтрацию по свойствам PartitionKey и свойству Email с помощью $filter OData.

Запрос

https://<mytableapi-endpoint>/People()?$filter=PartitionKey%20eq%20'Smith'%20and%20Email%20eq%20'Ben@contoso.com'

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

Результаты

PartitionKey	RowKey	Эл. почта	PhoneNumber
Иванов	Ben	Ben@contoso.com	425-555-0102

Запросы к свойствам datetime не возвращают данные при выполнении в API Azure Cosmos DB для таблицы. Хотя в хранилище таблиц Azure хранятся значения даты с степенью детализации тиков, API для таблицы в Azure Cosmos DB использует _ts это свойство. Свойство _ts находится на втором уровне детализации, который не является фильтром OData. Azure Cosmos DB блокирует запросы по свойствам метки времени. В качестве обходного решения можно определить свойство пользовательского типа DateTime или long и задать значение даты для клиента.

Запросы с помощью LINQ

Вы также можете выполнить запрос с помощью LINQ, который преобразуется в соответствующие выражения запроса OData. Ниже приведен пример создания запросов с использованием пакета SDK .NET.

IQueryable<CustomerEntity> linqQuery = table.CreateQuery<CustomerEntity>()
            .Where(x => x.PartitionKey == "4")
            .Select(x => new CustomerEntity() { PartitionKey = x.PartitionKey, RowKey = x.RowKey, Email = x.Email });

Следующие шаги

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

Настройка глобального распределения Azure Cosmos DB с помощью API для таблицы

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