Creación de consultas para enumerar los recursos de Batch con eficacia
La mayor parte de las aplicaciones de Azure Batch supervisan o realizan otras operaciones que consultan el servicio Batch. Estas consultas de lista suelen producirse a intervalos regulares. Por ejemplo, para poder buscar tareas en cola en un trabajo, debe obtener datos sobre cada tarea de ese trabajo. La reducción de la cantidad de datos que devuelve el servicio Batch para las consultas mejora el rendimiento de la aplicación. En este artículo, se explica cómo ejecutar este tipo de consultas de la manera más eficaz. Puede crear consultas filtradas para trabajos, tareas, nodos de proceso y otros recursos de Batch con la biblioteca .NET de Batch.
Nota
El servicio Batch proporciona compatibilidad con la API para los escenarios comunes de recuento de tareas en un trabajo y recuento de nodos de ejecución en el grupo de Batch. Puede llamar a las operaciones Get Task Counts y List Pool Node Counts, en lugar de usar una consulta de lista. Sin embargo, estas operaciones más eficaces devuelven información más limitada que podría no estar actualizada. Para más información, consulte el tema de recuento de las tareas y los nodos de ejecución por estado.
Especificación de un nivel de detalle
Puede haber miles de entidades como trabajos, tareas y nodo de ejecución en una aplicación de Batch. Para cada consulta que realice sobre los recursos, una cantidad potencialmente grande de datos va desde el servicio Batch a la aplicación. Limite el número de elementos y la información que devuelve la consulta para mejorar el rendimiento.
Este fragmento de código de la API de .NET de Batch enumera todas las tareas asociadas a un trabajo, junto con todas las propiedades de cada tarea.
// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
batchClient.JobOperations.ListTasks("job-001");
Aplique un nivel de detalle a la consulta para mostrar información de forma más eficaz. Suministre un objeto ODATADetailLevel al método JobOperations.ListTasks. Este fragmento de código devuelve solo las propiedades de identificador, línea de comandos e información de nodo de proceso para las tareas completadas.
// Configure an ODATADetailLevel specifying a subset of tasks and
// their properties to return
ODATADetailLevel detailLevel = new ODATADetailLevel();
detailLevel.FilterClause = "state eq 'completed'";
detailLevel.SelectClause = "id,commandLine,nodeInfo";
// Supply the ODATADetailLevel to the ListTasks method
IPagedEnumerable<CloudTask> completedTasks =
batchClient.JobOperations.ListTasks("job-001", detailLevel);
En este caso de ejemplo, si hay miles de tareas en el trabajo, los resultados de la segunda consulta normalmente se devuelven más rápido que en la primera consulta. Para obtener más información sobre el uso de ODATADetailLevel al enumerar elementos con la API de .NET de Batch, consulte la sección Consultas eficaces en .NET de Batch.
Importante
Es muy recomendable suministrar siempre un objeto ODATADetailLevel a las llamadas de la lista de la API de .NET para una eficacia y un rendimiento máximos de la aplicación. La especificación de un nivel de detalle puede ayudarle a reducir los tiempos de respuesta del servicio de Batch, a mejorar la utilización de la red y a minimizar el uso de la memoria por parte de las aplicaciones cliente.
Uso de las cadenas de consultas
Puede usar las API de REST de.NET de Batch y Batch para reducir el número de elementos que devuelve una consulta y la cantidad de información que devuelve la consulta para cada elemento. Hay tres tipos de cadena de consulta que puede usar para restringir la consulta: $filter, $selecty $expand.
Para la API de .NET de Batch, consulte las propiedades de la clase ODATADetailLevel. Revise también la sección Consultas eficaces en Batch para .NET.
Para la API DE REST de Batch, consulte la referencia sobre la API de REST de Batch. Busque la referencia de lista del recurso que desea consultar. A continuación, revise la sección Parámetros de URI para obtener más información sobre $filter, $select y $expand. Por ejemplo, consulte los parámetros URI de Pool - List. Consulte también cómo realizar consultas eficaces de Batch con la CLI de Azure.
Nota
Al construir cualquiera de los tres tipos de cadena de consulta, debe asegurarse de que los nombres de las propiedades y el uso de mayúsculas y minúsculas coinciden con los elementos homólogos de la API de REST. Por ejemplo, si trabaja con la clase .NET CloudTask, debe especificar state en lugar de State, aunque la propiedad de .NET sea CloudTask.State. Para obtener más información, consulte las asignaciones de propiedad entre la API de REST y la de .NET.
Filter
La cadena de expresión $filter reduce el número de elementos que se devuelven. Por ejemplo, puede mostrar solo las tareas en ejecución de un trabajo o solo los nodos de ejecución que estén listos para ejecutar tareas.
La cadena se compone de una o varias expresiones, una de la cuales consta de un nombre de propiedad, un operador y un valor. Las propiedades que se pueden indicar son específicas de cada tipo de entidad que consulta, al igual que los operadores compatibles con cada propiedad. Puede combinar varias expresiones con los operadores lógicos and y or.
Este ejemplo solo muestra las tareas render en ejecución: (state eq 'running') and startswith(id, 'renderTask').
Seleccionar
La cadena de expresión $select limita los valores de propiedad que se devuelven para cada elemento. Especifique una lista de nombres de propiedad separados por comas y se devolverán únicamente los valores de propiedad devueltos para los elementos de los resultados de la consulta. Puede especificar cualquiera de las propiedades del tipo de entidad que está consultando.
Este ejemplo especifica que solo se deben devolver tres valores de propiedades para cada tarea: id, state, stateTransitionTime.
Expanda
La cadena de expresión $expand reduce el número de llamadas API necesarias para obtener determinada información. Puede usar esta cadena para obtener más información sobre cada elemento con una sola llamada API. Este método ayuda a mejorar el rendimiento mediante la reducción de las llamadas API. Use una cadena $expand en lugar de obtener la lista de entidades y solicitar información sobre cada elemento de lista.
De forma similar a $select, $expand controla si se incluyen determinados datos en los resultados de la consulta de lista. Cuando se requieren todas las propiedades y no se especifica ninguna cadena select, se $expanddebe usar para obtener información estadística. Si se usa una cadena select para obtener un subconjunto de propiedades, se puede especificar stats en la cadena select y no es preciso especificar $expand.
Entre los usos admitidos de esta cadena se incluyen la enumeración de trabajos, programaciones de trabajos, tareas y grupos. En la actualidad, la cadena solo admite información estadística.
Este ejemplo especifica que se debe devolver información estadística de cada elemento de la lista: stats.
Reglas de las cadenas filter, select y expand
- Asegúrese de que los nombres de propiedades de las cadenas filter, select y expand aparezcan exactamente igual que en la API de REST de Batch. Esta regla se aplica incluso cuando se usa Batch .NET o uno de los otros SDK de Batch.
- Todos los nombres de propiedades distinguen mayúsculas y minúsculas, pero los valores de propiedad no lo hacen.
- Las cadenas de fecha y hora pueden tener uno de los dos formatos y deben ir precedidas por
DateTime.- Ejemplo de formato W3C-DTF:
creationTime gt DateTime'2011-05-08T08:49:37Z' - Ejemplo de formato RFC 1123:
creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
- Ejemplo de formato W3C-DTF:
- Las cadenas booleanas son
trueofalse. - Si se especifica una propiedad o un operador no válidos, aparecerá el error
400 (Bad Request).
Consultas eficaces en .NET de Batch
En la API de .NET de Batch, la clase ODATADetailLevel proporciona las cadenas filter, select y expand a las operaciones de lista. La clase ODataDetailLevel tiene tres propiedades de cadena pública. Puede especificar estas propiedades en el constructor o establecer las propiedades directamente en el objeto. Luego el objeto ODataDetailLevel pasa como parámetro a las distintas operaciones de lista como ListPools, ListJobs y ListTasks.
- ODATADetailLevel.FilterClause: limita el número de elementos que se devuelven.
- ODATADetailLevel.SelectClause: especifica los valores de propiedad devueltos con cada elemento.
- ODATADetailLevel.ExpandClause: recupera datos para todos los elementos en una sola llamada a la API en lugar de en llamadas independientes para cada elemento.
El siguiente fragmento de código usa la API de .NET de Batch para consultar de forma eficaz las estadísticas de un conjunto específico de grupos en el servicio Batch. El usuario de Batch tiene grupos de prueba y de producción. Los identificadores del grupo de prueba tienen el prefijo "test", mientras que los del grupo de producción tienen el prefijo "prod". myBatchClient es una instancia de la clase BatchClient inicializada correctamente.
// First we need an ODATADetailLevel instance on which to set the filter, select,
// and expand clause strings
ODATADetailLevel detailLevel = new ODATADetailLevel();
// We want to pull only the "test" pools, so we limit the number of items returned
// by using a FilterClause and specifying that the pool IDs must start with "test"
detailLevel.FilterClause = "startswith(id, 'test')";
// To further limit the data that crosses the wire, configure the SelectClause to
// limit the properties that are returned on each CloudPool object to only
// CloudPool.Id and CloudPool.Statistics
detailLevel.SelectClause = "id, stats";
// Specify the ExpandClause so that the .NET API pulls the statistics for the
// CloudPools 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 (CloudPool.Statistics)
detailLevel.ExpandClause = "stats";
// Now get our collection of pools, minimizing the amount of data that is returned
// by specifying the detail level that we configured above
List<CloudPool> testPools =
await myBatchClient.PoolOperations.ListPools(detailLevel).ToListAsync();
Sugerencia
Para limitar la cantidad de datos devueltos, también se puede pasar una instancia de ODATADetailLevel configurada con las cláusulas Select y Expand a los métodos Get apropiados, como PoolOperations.GetPool.
Asignaciones de la API de Batch de REST y la de .NET
Los nombres de propiedades en las cadenas filter, select y expand deben reflejar sus homólogos en la API de REST, tanto en el nombre en sí como en el uso de mayúsculas y minúsculas. En las tablas siguientes, se proporcionan asignaciones entre los homólogos de la API de .NET y la de REST.
Asignaciones de las cadenas filter
- Métodos de lista de .NET: todos los métodos de la API de .NET de esta columna aceptan un objeto ODATADetailLevel como parámetro.
- Solicitudes de lista de REST: todas las páginas de la API de REST de esta columna contienen una tabla con las propiedades y operaciones permitidas en las cadenas filter. Puede usar estos nombres de propiedad y estas operaciones se usan al construir una cadena ODATADetailLevel.FilterClause.
Asignaciones de las cadenas select
- Tipos de .NET de Batch: Tipos de API de .NET de Batch.
- Entidades de la API REST: todas las páginas de esta columna contienen una o varias tablas que enumeran los nombres de propiedades de la API REST para el tipo. Estos nombres de propiedades se usan al construir cadenas select . Estos mismos nombres se usan al construir una cadena ODATADetailLevel.SelectClause.
Ejemplo: construcción de una cadena filter
Para construir una cadena de filtro para ODATADetailLevel.FilterClause,busque la página de API de REST correspondiente. Las propiedades seleccionables y sus operadores admitidos se encuentran en la primera tabla de varias filas. Por ejemplo, si desea recuperar todas las tareas cuyo código de salida era distinto de cero, consulte la Lista de las tareas asociadas a un trabajo para la cadena de propiedad aplicable y los operadores permitidos:
| Propiedad | Operaciones permitidas | Tipo |
|---|---|---|
executionInfo/exitCode |
eq, ge, gt, le , lt |
Int |
La cadena de filtro relacionada es:
(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)
Ejemplo: construcción de una cadena select
Para construir ODATADetailLevel.SelectClause,busque la página de API de REST correspondiente para la entidad que está enumerando. Las propiedades seleccionables y sus operadores admitidos se encuentran en la primera tabla de varias filas. Por ejemplo, para recuperar solo el identificador y la línea de comandos de cada tarea de una lista, active Obtener información sobre una tarea:
| Propiedad | Tipo | Notas |
|---|---|---|
id |
String |
The ID of the task. |
commandLine |
String |
The command line of the task. |
La cadena de selección relacionada es:
id, commandLine
Ejemplos de código
Consultas de listas eficaces
El proyecto de ejemplo EfficientListQueries muestra ver cómo una consulta de lista eficaz afecta al rendimiento de una aplicación. Esta aplicación de consola de C# crea y agrega un gran número de tareas a un trabajo. A continuación, la aplicación realiza varias llamadas al método JobOperations.ListTasks y pasa los objetos ODATADetailLevel. Estos objetos se configuran con valores de propiedad diferentes para variar la cantidad de datos que se van a devolver. Este ejemplo genera una salida similar a la siguiente:
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...
El ejemplo muestra que se pueden reducir considerablemente los tiempos de respuesta, para lo que es preciso limitar las propiedades y el número de elementos que se devuelven. Puede encontrar este y otros proyectos de ejemplo en el repositorio azure-batch-samples de GitHub.
Biblioteca BatchMetrics
El siguiente ejemplo BatchMetrics demuestra cómo supervisar de forma eficiente el progreso del trabajo de Azure Batch mediante la API de Batch.
Este ejemplo incluye un proyecto de biblioteca de clases .NET, que puede incorporar a sus propios proyectos. También hay un sencillo programa de línea de comandos para realizar ejercicios y demostrar el uso de la biblioteca.
La aplicación de ejemplo del proyecto muestra estas operaciones:
- Selección de atributos específicos para descargar solo las propiedades que necesita
- Filtrado en tiempo de transición de estado para descargar solo los cambios desde la última consulta
Por ejemplo, el siguiente método aparece en la biblioteca BatchMetrics. Devuelve un objeto ODATADetailLevel que establece que solo deben obtenerse las propiedades id y state en las consultas realizadas. También especifica que solo las entidades cuyo estado ha cambiado desde que se ha especificado el parámetro DateTime se deben devolver.
internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
return new ODATADetailLevel(
selectClause: "id, state",
filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
);
}
Pasos siguientes
- Maximizar el uso de recursos de proceso de Azure Batch con tareas simultáneas de nodo. Algunos tipos de cargas de trabajo pueden beneficiarse de la ejecución de tareas paralelas en una menor cantidad de nodos de ejecución que, sin embargo, sean de mayor tamaño. Consulte la sección Escenario de ejemplo en el artículo para obtener detalles sobre dicho escenario.
- Supervisión de las soluciones de Batch realizando un recuento de las tareas y los nodos por estado