Créer des requêtes pour répertorier les ressources Batch efficacement
La plupart des applications Azure Batch effectuent un monitoring ou d’autres opérations qui interrogent le service Batch. Ces requêtes de liste se produisent souvent à intervalles réguliers. Par exemple, avant de pouvoir vérifier les tâches mises en file d’attente dans un travail, vous devez obtenir des données sur chacune des tâches de ce travail. En réduisant la quantité de données retournées par le service Batch pour les requêtes, vous pouvez améliorer les performances de votre application. Cet article explique comment créer et exécuter ces requêtes de manière efficace. Vous pouvez créer des requêtes filtrées pour des travaux, des tâches, des nœuds de calcul et d’autres ressources Batch à l’aide de la bibliothèque Batch .NET.
Notes
Le service Batch fournit une prise en charge des API pour des scénarios courants, comme le comptage des tâches d’un travail et le comptage des nœuds dans un pool Batch. Au lieu d’utiliser une requête de liste, vous pouvez appeler les opérations Obtenir le nombre de tâches et Répertorier le nombre de nœuds des pools. Toutefois, ces opérations, certes plus efficaces, retournent des informations plus limitées qui peuvent ne pas être à jour. Pour plus d’informations, consultez Compter les tâches et les nœuds de calcul par état.
Spécifier un niveau de détail
Dans une application Batch de production, les entités telles que les travaux, les tâches et les nœuds de calcul peuvent se compter par milliers. Pour chaque requête que vous exécutez sur les ressources, un volume potentiellement important de données peut passer du service Batch à votre application. Limitez le nombre d’éléments ainsi que les types d’informations que votre requête retourne pour améliorer les performances.
Cet extrait de code de l’API Batch .NET liste chaque tâche qui est associée à un travail, ainsi que toutes les propriétés de chaque tâche.
// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
batchClient.JobOperations.ListTasks("job-001");
Appliquez un niveau de détail à votre requête pour lister les informations de manière plus efficace. Fournissez un objet ODATADetailLevel à la méthode JobOperations.ListTasks. Cet extrait de code retourne uniquement les propriétés d’ID, de ligne de commande et d’informations du nœud de calcul pour les tâches terminées.
// 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);
Si, dans l’exemple de scénario, les tâches associées au travail se comptent par milliers, les résultats de la deuxième requête sont généralement retournés bien plus rapidement que ceux de la première requête. Pour plus d’informations sur l’utilisation de ODATADetailLevel lorsque vous listez des éléments avec l’API Batch .NET, consultez la section Interrogation efficace dans Batch .NET.
Important
Nous vous recommandons vivement de toujours fournir un objet ODATADetailLevel à vos appels de liste d’API .NET afin de garantir une efficacité et des performances maximales pour votre application. En spécifiant un niveau de détail, vous pouvez réduire les délais de réponse du service Batch, améliorer le taux d’utilisation du réseau et réduire l’utilisation de la mémoire par les applications clientes.
Utiliser des chaînes de requête
Vous pouvez utiliser les API Batch .NET et Batch REST pour réduire le nombre d’éléments retournés par une requête, ainsi que la quantité d’informations retournées par la requête pour chaque élément. Il existe trois types de chaîne de requête que vous pouvez utiliser pour affiner votre requête : $filter, $select et $expand.
Pour l’API Batch .NET, consultez les propriétés de la classe ODATADetailLevel. Consultez également la section Interrogation efficace dans Batch .NET.
Pour l’API Batch REST, consultez les informations de référence sur l’API Batch REST. Recherchez la référence Liste pour la ressource que vous souhaitez interroger. Consultez ensuite la section Paramètres d’URI pour plus d’informations sur $filter, $select et $expand. Par exemple, consultez Paramètres d’URI pour le pool - Liste. Découvrez également comment exécuter des requêtes Batch efficaces avec Azure CLI.
Notes
Lors de la construction de l’un des trois types de chaînes de requête, vous devez vous assurer que les noms de propriété et la casse correspondent à ceux de leurs homologues dans l’API REST. Par exemple, lorsque vous utilisez la classe CloudTask .NET, vous devez spécifier état et non État même si la propriété .NET est CloudTask.State. Pour plus d’informations, consultez les mappages de propriété entre les API .NET et REST.
Filtrer
La chaîne d’expression $filter réduit le nombre d’éléments retournés. Par exemple, vous pouvez lister uniquement les tâches en cours d’exécution pour un travail ou lister uniquement les nœuds de calcul prêts à exécuter des tâches.
Cette chaîne se compose d’une ou de plusieurs expressions dont l’une se compose d’un nom de propriété, d’un opérateur et d’une valeur. Les propriétés spécifiables sont propres à chaque type d’entité que vous interrogez, de même que les opérateurs pris en charge pour chaque propriété. Plusieurs expressions peuvent être combinées à l’aide des opérateurs logiques and et or.
Cet exemple liste uniquement les tâches de rendu en cours d’exécution : (state eq 'running') and startswith(id, 'renderTask').
Sélectionnez
La chaîne d’expression $select limite les valeurs de propriété qui sont retournées pour chaque élément. Vous pouvez spécifier une liste de noms de propriétés séparés par des virgules. Seules ces valeurs de propriétés seront retournées pour les éléments dans les résultats de la requête. Vous pouvez spécifier n’importe quelle propriété pour le type d’entité que vous interrogez.
Cet exemple spécifie que seules trois valeurs de propriété doivent être retournées pour chaque tâche : id, state, stateTransitionTime.
Développez
La chaîne d’expression $expand réduit le nombre d’appels d’API nécessaires pour obtenir certaines informations. Vous pouvez utiliser cette chaîne pour obtenir plus d’informations sur chacun des éléments avec un seul appel d’API. Cette méthode permet d’améliorer les performances en réduisant les appels d’API. Utilisez une chaîne $expand au lieu d’obtenir la liste des entités et de demander des informations sur chaque élément de la liste.
Tout comme $select, $expand contrôle si certaines données doivent être incluses dans les résultats de la requête de liste. Quand toutes les propriétés sont obligatoires et qu’aucune chaîne select n’est spécifiée, $expanddoit être utilisé pour obtenir les informations statistiques. Si une chaîne select est utilisée pour obtenir un sous-ensemble de propriétés, stats peut être spécifié dans la chaîne select. Il est alors inutile de spécifier $expand.
Les utilisations prises en charge de cette chaîne incluent les listes de travaux, les planifications de travaux, les tâches et les pools. Actuellement, la chaîne ne prend en charge que les informations statistiques.
Cet exemple spécifie que les informations statistiques doivent être retournées pour chaque élément de la liste : stats.
Règles des chaînes filter, select et expand
- Vérifiez que les noms des propriétés des chaînes filter, select et expand s’affichent bien comme dans l’API Batch REST. Cette règle s’applique même lorsque vous utilisez Batch .NET ou l’un des autres SDK Batch.
- Les noms de propriété respectent la casse contrairement aux valeurs de propriété.
- Les chaînes de date/heure peuvent être d’un format ou de l’autre et doivent être précédées de
DateTime.- Exemple de format W3C-DTF :
creationTime gt DateTime'2011-05-08T08:49:37Z' - Exemple de format RFC 1123 :
creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
- Exemple de format W3C-DTF :
- Les chaînes booléennes ont la valeur
trueoufalse. - Si une propriété ou un opérateur non valide est spécifié, une erreur
400 (Bad Request)se produit.
Interrogation efficace dans Batch.NET
Dans l’API Batch .NET, la classe ODATADetailLevel fournit les chaînes filter, select et expand aux opérations de liste. La classe ODataDetailLevel a trois propriétés de chaîne publiques. Vous pouvez spécifier ces propriétés dans le constructeur ou définir directement les propriétés dans l’objet. Ensuite, passez l’objet ODataDetailLevel en tant que paramètre à plusieurs opérations de liste comme ListPools, ListJobs et ListTasks.
- ODATADetailLevel.FilterClause : limitez le nombre d’éléments qui sont retournés.
- ODATADetailLevel.SelectClause : spécifiez les valeurs de propriété retournées avec chaque élément.
- ODATADetailLevel.ExpandClause : récupèrez les données de tous les éléments en utilisant un seul appel d’API et non des appels distincts pour chaque élément.
L’extrait de code suivant utilise l’API .NET Batch afin d’interroger efficacement le service Batch concernant les statistiques d’un ensemble spécifique de pools. L’utilisateur Batch a à la fois des pools de test et des pools de production. Les ID de pool de test sont précédés du préfixe « test » et les ID de production sont précédés de « prod ». myBatchClient est une instance initialisée correctement de la classe BatchClient.
// 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();
Conseil
Une instance d’ODATADetailLevel configurée avec les clauses Select et Expand peut également être transmise aux méthodes Get appropriées telles que PoolOperations.GetPool pour limiter la quantité de données retournées.
Mappages entre les API Batch REST et .NET
Les noms de propriété dans les chaînes filter, select et expand doivent refléter leurs homologues dans l’API REST, aussi bien au niveau du nom que de la casse. Les tableaux ci-dessous fournissent les correspondances existant entre les homologues .NET et REST.
Mappages pour les chaînes filter
- Méthodes de liste .NET : chacune des méthodes de l’API .NET de cette colonne accepte un objet ODATADetailLevel en tant que paramètre.
- Requêtes de liste REST : chaque page de l’API REST listée dans cette colonne contient une table spécifiant les propriétés et les opérations autorisées dans les chaînes filter. Vous pouvez utiliser ces noms de propriétés et ces opérations lors de la construction d’une chaîne ODATADetailLevel.FilterClause.
Mappages pour les chaînes select
- Types .NET Batch : types d’API .NET Batch.
- Entités de l’API REST : chaque page de cette colonne contient une ou plusieurs tables qui listent les noms des propriétés de l’API REST correspondant au type. Ces noms de propriétés sont utilisés lorsque vous construisez des chaînes select . Vous devez utiliser ces mêmes noms de propriétés lors de la construction d’une chaîne ODATADetailLevel.SelectClause.
Exemple : Construire une chaîne filter
Si vous souhaitez construire une chaîne filter pour ODATADetailLevel.FilterClause, recherchez la page correspondante de l’API REST. Les propriétés sélectionnables et leurs opérateurs pris en charge se trouvent dans la première table multiligne. Par exemple, si vous souhaitez récupérer toutes les tâches ayant un code de sortie non nul, consultez Création de la liste des tâches associées à un travail pour la chaîne de propriétés applicable et les opérateurs autorisés :
| Propriété | Opérations autorisées | Type |
|---|---|---|
executionInfo/exitCode |
eq, ge, gt, le , lt |
Int |
La chaîne filter associée est la suivante :
(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)
Exemple : Construire une chaîne select
Pour construire ODATADetailLevel.SelectClause, recherchez la page de l’API REST correspondante pour l’entité que vous listez. Les propriétés sélectionnables et leurs opérateurs pris en charge se trouvent dans la première table multiligne. Par exemple, pour récupérer uniquement l’ID et la ligne de commande de chaque tâche d’une liste, consultez Obtenir des informations sur une tâche :
| Propriété | Type | Notes |
|---|---|---|
id |
String |
The ID of the task. |
commandLine |
String |
The command line of the task. |
La chaîne select associée est la suivante :
id, commandLine
Exemples de code
Requêtes de liste efficaces
L’exemple de projet EfficientListQueries montre comment une interrogation de liste efficace peut affecter les performances d’une application. Cette application de console C# crée et ajoute de nombreuses tâches à un travail. Ensuite, l’application émet plusieurs appels vers la méthode JobOperations.ListTasks et passe des objets ODATADetailLevel. Ces objets sont configurés avec des valeurs de propriété différentes pour varier la quantité de données à retourner. Cet exemple produit une sortie semblable à celle-ci :
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...
Cet exemple montre comment vous pouvez réduire de façon significative les temps de réponse de requête en limitant les propriétés et le nombre d’éléments retournés. Cet exemple et d’autres exemples de projet sont disponibles dans le dépôt azure-batch-samples sur GitHub.
Bibliothèque BatchMetrics
L’exemple de projet BatchMetrics suivant montre comment monitorer efficacement la progression d’un travail Azure Batch à l’aide de l’API Batch.
Cet exemple inclut un projet de bibliothèque de classes .NET, que vous pouvez incorporer dans vos propres projets. Il existe également un programme de ligne de commande simple à utiliser qui permet de montrer l’utilisation de la bibliothèque.
L’exemple d’application au sein du projet illustre les opérations suivantes :
- Sélection d’attributs spécifiques afin de ne télécharger que les propriétés nécessaires
- Filtrage basé sur les heures de transition d’état afin de ne télécharger que les modifications apportées depuis la dernière requête
Par exemple, la méthode suivante apparaît dans la bibliothèque BatchMetrics. Elle retourne un objet ODATADetailLevel qui spécifie que seules les propriétés id et state doivent être obtenues pour les entités interrogées. Elle indique également que seules les entités dont l’état a changé depuis le paramètre DateTime spécifié doivent être retournées.
internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
return new ODATADetailLevel(
selectClause: "id, state",
filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
);
}
Étapes suivantes
- Optimiser l’utilisation des ressources de calcul Azure Batch avec les tâches de nœud simultanées. Certains types de charge de travail peuvent tirer parti de l’exécution de tâches parallèles sur des nœuds de calcul plus volumineux (mais moins nombreux). Découvrez l’exemple de scénario de l’article pour en connaître les détails.
- Surveiller les solutions Batch en comptant les tâches et les nœuds par état