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

Статья
03/17/2023

ПРИМЕНИМО К: Таблица

Azure Cosmos DB для таблицы поддерживает запросы OData и LINQ к данным типа "ключ-значение" (таблица).

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

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

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

PartitionKey	RowKey	Email	PhoneNumber
Harp	Walter	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	Email	PhoneNumber
Harp	Walter	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	Email	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 для таблиц

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