Partager via


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'
  • Les chaînes booléennes ont la valeur true ou false.
  • 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.

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.
Méthodes de liste .NET Requêtes de liste REST
CertificateOperations.ListCertificates Création de la liste des certificats dans un compte
CloudTask.ListNodeFiles Création de la liste des fichiers associés à une tâche
JobOperations.ListJobPreparationAndReleaseTaskStatus Création de la liste des états de préparation du travail et des tâches de lancement d’un travail
JobOperations.ListJobs Création de la liste des travaux dans un compte
JobOperations.ListNodeFiles Création de la liste des fichiers sur un nœud
JobOperations.ListTasks Création de la liste des tâches associées à un travail
JobScheduleOperations.ListJobSchedules Création de la liste des planifications de travaux dans un compte
JobScheduleOperations.ListJobs Création de la liste des travaux associés à une planification de travail
PoolOperations.ListComputeNodes Création de la liste des nœuds de calcul dans un pool
PoolOperations.ListPools Création de la liste des pools d’un compte

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.
Types .NET Batch Entités de l’API REST
Certificate Obtenir des informations sur un certificat
CloudJob Obtenir des informations sur un travail
CloudJobSchedule Obtenir des informations sur la planification d’un travail
ComputeNode Obtenir des informations sur un nœud
CloudPool Obtenir des informations sur un pool
CloudTask Obtenir des informations sur une tâche

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