Эффективное создание запросов для перечисления ресурсов пакетной обработки.

Большинство приложений пакетная служба Azure выполняют мониторинг или другие операции, запрашивающие службу Batch. Такие запросы списков часто выполняются через регулярные интервалы. Например, прежде чем проверять наличие задач в очереди в задании, необходимо получить данные о каждой задаче в этом задании. Уменьшение объема данных, возвращаемых пакетной службой для запросов, повышает производительность приложения. В этой статье объясняется, как создавать и выполнять такие запросы наиболее эффективно. Вы можете создавать фильтрованные запросы для заданий Batch, задач, вычислительных узлов и других ресурсов с помощью библиотеки Azure.Compute.Batch.

Примечание.

Служба пакетной обработки предоставляет поддержку API для распространенных сценариев подсчета задач в задании и вычислительных узлов в пуле Batch. Вместо того чтобы использовать запрос на вывод списка, вы можете вызвать операции "Получить количество задач" и "Вывести количество узлов в пуле". Однако эти более эффективные операции возвращают более ограниченную информацию, которая может быть неактуальной. Подробнее см. в разделе Подсчет задач и вычислительных узлов по состоянию.

Определение уровня детализации

В производственном приложении для пакетной обработки такие сущности, как задания, задачи и вычислительные узлы, могут исчисляться тысячами. Для каждого запроса, который вы делаете о ресурсах, потенциально большой объем данных передается из пакетной службы в приложение. Ограничьте количество элементов и сведения, возвращаемые запросом, чтобы повысить производительность.

Этот фрагмент кода API Azure.Compute.Batch перечисляет все задачи, связанные с заданием, а также все свойства каждой задачи.

// Get a collection of all of the tasks and all of their properties for job-001
AsyncPageable<BatchTask> allTasks = batchClient.GetTasksAsync("job-001");

Применяйте к запросу уровень детализации для более эффективного перечисления сведений. Передайте строки filter, select и expand в метод BatchClient.GetTasks. Этот фрагмент кода возвращает только идентификатор, командную строку и свойства вычислительного узла завершенных задач.

// Specify filter and select strings to return only a subset of tasks and their properties.
AsyncPageable<BatchTask> completedTasks = batchClient.GetTasksAsync(
    jobId: "job-001",
    filter: "state eq 'completed'",
    select: new[] { "id", "commandLine", "nodeInfo" });

Если, как в данном примере сценария, задание состоит из тысяч задач, результаты для второго запроса обычно возвращаются быстрее, чем для первого. Дополнительные сведения об использовании filter, select и параметрах expand с Azure. API Compute.Batch см. в разделе Эффективные запросы в Azure. Compute.Batch.

Внимание

Мы настоятельно рекомендуем всегда передавать строки filter, select и (при необходимости) expand при вызовах получения списков через ваш API .NET для максимальной эффективности и производительности приложения. Указание уровня детализации может помочь снизить время ответа Службы пакетной обработки, повысить эффективность использования сети и минимизировать использование памяти клиентскими приложениями.

Использование строк запроса

Вы можете использовать Azure. Compute.Batch и Batch REST, чтобы уменьшить количество элементов, возвращаемых запросом, и сколько сведений возвращает запрос для каждого элемента. Существует три типа строк запроса, которые можно использовать для сужения запроса: $filter, $select и $expand.

Сведения об API Azure.Compute.Batch см. в справочнике по BatchClient для метода list, параметры filter, select и expand которого вы хотите использовать. Кроме того, просмотрите раздел Эффективные запросы в Azure. Compute.Batch.

Сведения об API пакетной службы REST см. в справочнике по API пакетной службы REST. Найдите ссылку на список для ресурса, который требуется запросить. Затем просмотрите раздел "Параметры URI" для получения дополнительных сведений о $filter, $select, и $expand. Например, см. параметры URI для пула — список. Кроме того, узнайте как эффективно выполнять пакетные запросы с помощью Azure CLI.

Примечание.

При создании какого-либо из трех типов строк запроса необходимо убедиться, что имена и регистр свойств совпадают с аналогичными элементами REST API. Например, при работе с классом .NET BatchTask, необходимо указать state вместо State, даже если свойство .NET BatchTask.State. Дополнительные сведения см. в сопоставлении свойств между .NET и REST API.

Фильтр

Строка выражения $filter уменьшает число возвращаемых элементов. Например, можно вывести список только выполняющихся задач в задании или только вычислительных узлов, которые готовы к выполнению задач.

Строка состоит из одного или нескольких выражений, каждое из которых состоит из имени свойства, оператора и значения. Для каждого опрашиваемого типа сущности можно указать только определенные свойства, а также только определенные операторы, поддерживаемые каждым свойством. Несколько выражений можно объединить с помощью логических операторов and и or.

В этом примере выводятся только запущенные задачи отрисовки: (state eq 'running') and startswith(id, 'renderTask').

Выбрать

Строка выражения $select ограничивает значения свойств, возвращаемых для каждого элемента. Вы указываете список имен свойств через запятую, после чего в результатах запроса возвращаются только значения указанных свойств для соответствующих элементов. Для запрашиваемого типа сущности можно указать любые свойства.

В этом примере показано, что для каждой задачи необходимо вернуть значения только трех свойств: id, state, stateTransitionTime.

Разверните

Строка выражения $expand сокращает количество вызовов API, необходимое для получения определенных сведений. Эту строку можно использовать для получения дополнительных сведений о каждом элементе с помощью одного вызова API. Этот метод помогает повысить производительность за счет сокращения вызовов API. Используйте строку $expand вместо получения списка сущностей и запроса сведений о каждом элементе списка.

Как и $select, $expand определяет, какие данные нужно включить в результаты запроса списка. Если требуются все свойства и строка выбора не указана, $expandнеобходимо использовать для получения сведений о статистике. Если для получения подмножества свойств используется строка выборки, то в ней можно указать stats и не указывать $expand.

Поддерживаемые варианты использования этой строки включают перечисление заданий, расписаний заданий, задач и пулов. В настоящее время строка поддерживает только статистические данные.

В этом примере показано, что для каждого элемента в списке необходимо вернуть статистические данные: stats.

Правила фильтрации, выбора и развертывания строк

  • Убедитесь, что имена свойств в строках фильтрации, выбора и развертывания отображаются так же, как в Batch REST API. Это правило применяется даже если вы используете Azure.Compute.Batch или один из других пакетов SDK Batch.
  • Имена всех свойств чувствительны к регистру, но для значений свойств регистр значения не имеет.
  • Строки даты и времени могут иметь один из двух форматов и должны начинаться с DateTime.
    • Пример формата W3C-DTF: creationTime gt DateTime'2011-05-08T08:49:37Z'
    • Пример формата RFC 1123: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
  • Булевые строки являются true или false.
  • Если задано недопустимое свойство или оператор, отобразится ошибка 400 (Bad Request) .

Эффективное выполнение запросов в Azure. Compute.Batch

В API Azure.Compute.Batch методы получения списка у BatchClient напрямую принимают параметры filter, select и expand:

  • filter: ограничение количества возвращаемых элементов.
  • select: укажите, какие значения свойств возвращаются с каждым элементом.
  • expand: извлеките данные для всех элементов в одном вызове API вместо отдельных вызовов для каждого элемента.

В следующем фрагменте кода используется API Azure.Compute.Batch для эффективного запроса к службе Batch статистики по конкретному набору пулов. У пользователя Batch есть как тестовые, так и продуктивные пулы. Идентификаторы тестовых пулов имеют префикс "test", а рабочих пулов — "prod". myBatchClient является правильно инициализированным экземпляром класса BatchClient.

// Pull only the "test" pools, and limit the data crossing the wire by selecting only
// the Id and Statistics properties. Use expand="stats" so the .NET API pulls the
// statistics for the BatchPools in a single underlying REST API call. Note that we
// use the pool's REST API element name "stats" here as opposed to "Statistics" as it
// appears in the .NET API (BatchPool.Statistics).
List<BatchPool> testPools = new List<BatchPool>();
await foreach (BatchPool pool in myBatchClient.GetPoolsAsync(
    filter: "startswith(id, 'test')",
    select: new[] { "id", "stats" },
    expand: new[] { "stats" }))
{
    testPools.Add(pool);
}

Совет

Те же параметры filter, select и expand также можно передавать соответствующим методам Get, таким как BatchClient.GetPool, чтобы ограничить объём возвращаемых данных.

Сопоставление пакетных REST операций с API .NET

Имена свойств в строках фильтрации, выбора и расширения должны точно соответствовать своим аналогам в REST API, как по названию, так и по регистру. В таблицах ниже приведено сопоставление элементов API в .NET и REST.

Сопоставления для строк фильтрации

  • Методы списка .NET: Каждый из методов API .NET в этом столбце принимает строковые параметры filter, select и expand.
  • Запросы списка REST— каждая страница REST API, связанная с этим столбцом, содержит таблицу со свойствами и операциями, разрешенными в строках фильтрации. Эти имена свойств и операции можно использовать при создании filter строки.
Методы списка .NET Запросы списка REST
BatchAccountResource.GetBatchAccountCertificates Перечисление сертификатов в учетной записи
BatchClient.GetTaskFiles Получение списка файлов, связанных с задачей
BatchClient.GetJobPreparationAndReleaseTaskStatuses Перечислить состояние задач подготовки и выпуска задания для работы
BatchClient.GetJobs Список работ в учетной записи
BatchClient.GetNodeFiles Получение списка файлов в узле
BatchClient.GetTasks Список задач, связанных с работой
BatchClient.GetJobSchedules Список расписаний заданий в учетной записи
BatchClient.GetJobsFromSchedule Список заданий, связанных с расписанием работ
BatchClient.GetNodes Список вычислительных узлов в пуле
BatchClient.GetPools Перечислите пулы в учетной записи

Сопоставления для выбранных строк

  • Типы Azure.Compute.Batch: типы API Azure.Compute.Batch.
  • Сущности REST API— каждая страница в этом столбце содержит одну или несколько таблиц с именами свойств API REST для соответствующих типов. Эти имена свойств используются при создании строк выборки . Эти же имена свойств используются при создании select строки.
Типы Azure.Compute.Batch Сущности REST API
BatchJob Получение информации о задании
BatchJobSchedule Получение информации о расписании задания
BatchNode Получение информации об узле
BatchPool Получите информацию о пуле
BatchTask Получение информации о задаче

Пример. Создание строки фильтрации

Чтобы создать строку фильтра для параметра метода filter списка, найдите соответствующую страницу REST API. Доступные для выбора свойства и их поддерживаемые операторы находятся в первой многострочной таблице. Например, чтобы получить все задачи с ненулевым кодом завершения, проверьте "Перечень задач, связанных с заданием", чтобы найти подходящую строку свойства и допустимые операторы.

Свойство Разрешенные операции Тип
executionInfo/exitCode eq, ge, gt, le , lt Int

Связанная строка фильтрации:

(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)

Пример. Создание строки выборки

Чтобы создать select строку, найдите соответствующую страницу REST API для сущности, которую вы перечисляете. Доступные для выбора свойства и их поддерживаемые операторы находятся в первой многострочной таблице. Например, вы хотите получить только идентификатор и командную строку для каждой задачи в списке. Выберите Получение информации о задаче":

Свойство Тип Примечания.
id String The ID of the task.
commandLine String The command line of the task.

Связанная строка выборки:

id, commandLine

Примеры кода

Эффективные запросы списка

На примере проекта EfficientListQueries показано, как эффективные запросы на получение списков могут повлиять на производительность приложения. Это консольное приложение C# создает и добавляет большое количество задач в задание. Затем приложение выполняет несколько вызовов метода BatchClient.GetTasks и передает разные filterselectзначения параметров, expand чтобы изменить объем возвращаемых данных. В данном примере показан результат схожий со следующим:

Adding 5000 tasks to job jobEffQuery...
5000 tasks added in 00:00:47.3467587, hit ENTER to query tasks...

4943 tasks retrieved in 00:00:04.3408081 (ExpandClause:  | FilterClause: state eq 'active' | SelectClause: id,state)
0 tasks retrieved in 00:00:00.2662920 (ExpandClause:  | FilterClause: state eq 'running' | SelectClause: id,state)
59 tasks retrieved in 00:00:00.3337760 (ExpandClause:  | FilterClause: state eq 'completed' | SelectClause: id,state)
5000 tasks retrieved in 00:00:04.1429881 (ExpandClause:  | FilterClause:  | SelectClause: id,state)
5000 tasks retrieved in 00:00:15.1016127 (ExpandClause:  | FilterClause:  | SelectClause: id,state,environmentSettings)
5000 tasks retrieved in 00:00:17.0548145 (ExpandClause: stats | FilterClause:  | SelectClause: )

Sample complete, hit ENTER to continue...

В примере показано как путем ограничения свойств и количества возвращаемых элементов можно значительно уменьшить время отклика на запрос. Этот и другие примеры проектов находятся в репозитории azure-batch-samples на сервисе GitHub.

Библиотека BatchMetrics

Пример проекта BatchMetrics демонстрирует, как эффективно отслеживать ход выполнения задания пакетной службы Azure с помощью API пакетной службы.

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

В примере приложения проекта демонстрируются следующие операции:

  • Выбор определенных атрибутов для загрузки только необходимых свойств
  • Фильтрация времени смены состояния для загрузки только изменений, отправленных с момента последнего запроса

Например, в библиотеке BatchMetrics используется приведенный ниже метод. Он возвращает кортеж, содержащий строки select и filter, указывающие, что для запрашиваемых сущностей должны быть получены только свойства id и state, а также что должны возвращаться только те сущности, состояние которых изменилось с момента, указанного в параметре DateTime.

return (
    Filter: string.Format("stateTransitionTime gt DateTime'{0:o}'", time),
    Select: new[] { "id", "state" });

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

  • Last updated on