Erstellen von Abfragen zum effizienten Auflisten von Batch-Ressourcen
Die meisten Azure Batch Anwendungen überwachen oder andere Vorgänge, die den Batch-Dienst abfragen. Solche Listenabfragen erfolgen häufig in regelmäßigen Abständen. Bevor Sie beispielsweise in einem Auftrag in der Warteschlange nach Aufgaben in der Warteschlange suchen können, müssen Sie Daten zu jedem Task in diesem Auftrag abrufen. Die Reduzierung der Datenmenge, die der Batch-Dienst für Abfragen zurückgibt, verbessert die Leistung Ihrer Anwendung. In diesem Artikel wird erläutert, wie diese Abfragen auf effiziente Weise erstellt und ausgeführt werden. Sie können gefilterte Abfragen für Batch-Aufträge, Tasks, Computeknoten und andere Ressourcen mit der Batch .NET-Bibliothek erstellen.
Hinweis
Der Batch-Dienst bietet API-Unterstützung für allgemeine Szenarios, in denen Tasks in einem Auftrag und Compute-Knoten in einem Batch-Pool gezählt werden. Sie können Sie die Vorgänge Get Task Counts (Aufgabenanzahl abrufen) und List Pool Node Counts (Poolknotenanzahl auflisten) aufrufen, anstatt eine Listenabfrage zu verwenden. Diese effizienteren Vorgänge geben jedoch eingeschränktere Informationen zurück, die möglicherweise nicht auf dem neuesten Stand sind. Weitere Informationen finden Sie unter Count tasks and compute nodes by state (Zählen von Tasks und Computeknoten nach Status).
Angeben einer Detailebene
In einer Batch-Produktionsanwendung kann die Anzahl von Entitäten wie Aufträgen, Aufgaben und Computeknoten leicht in die Tausende gehen. Für jede Abfrage, die Sie zu den Ressourcen ausführen, wird eine potenziell große Datenmenge vom Batch-Dienst an Ihre Anwendung fließen. Begrenzen Sie, wie viele Elemente und welche Informationen Ihre Abfrage zurückgibt, um die Leistung zu verbessern.
Der folgende Batch .NET-API-Codeausschnitt listet jede Aufgabe im Zusammenhang mit einem Auftrag sowie alle Eigenschaften der einzelnen Aufgaben auf.
// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
batchClient.JobOperations.ListTasks("job-001");
Wenden Sie eine Detailebene auf Ihre Abfrage an, um Informationen effizienter aufzulisten. Übergeben Sie ein ODATADetailLevel-Objekt an die JobOperations.ListTasks-Methode. Dieser Codeausschnitt gibt nur die ID-, Befehlszeilen- und Computeknoteneigenschaften abgeschlossener Aufgaben zurück.
// 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);
Wenn der Auftrag wie in diesem Beispielszenario Tausende von Aufgaben umfasst, werden die Ergebnisse der zweiten Abfrage meist viel schneller als die der ersten zurückgegeben. Weitere Informationen zur Verwendung von beim Auflisten von ODATADetailLevel Elementen mit der Batch .NET-API finden Sie im Abschnitt Effiziente Abfrage in Batch.
Wichtig
Es wird dringend empfohlen, immer ein ODATADetailLevel Objekt für Ihre .NET-API-Listenaufrufe zu verwenden, um eine maximale Effizienz und optimale Leistung der Anwendung zu gewährleisten. Das Angeben einer Detailebene hilft dem Batch-Dienst beim Verkürzen von Antwortzeiten, Verbessern der Netzwerkauslastung und Minimieren der Speicherbelegung von Clientanwendungen.
Verwenden Sie Abfragezeichenfolgen.
Sie können die APIs Batch .NET und Batch REST verwenden, um zu reduzieren, wie viele Elemente eine Abfrage zurückgibt und wie viele Informationen die Abfrage für jedes Element zurückgibt. Es gibt drei Arten von Abfragezeichenfolgen, mit denen Sie Ihre Abfrage eingrenzen können: $filter, $select und $expand.
Informationen zur Batch .NET-API finden Sie in den Eigenschaften der ODATADetailLevel-Klasse. Lesen Sie auch den Abschnitt Effizientes Abfragen in Batch .NET.
Informationen zur Batch-REST-API finden Sie in der Referenz zur Batch-REST-API. Suchen Sie die List-Referenz für die Ressource, die Sie abfragen möchten. Lesen Sie dann den Abschnitt URI-Parameter, um Details zu $filter, $select und $expand zu erhalten. Ein Beispiel hierzu finden Sie unter URI-Parameter für Pool – Liste. Außerdem erfahren Sie, wie Sie effiziente Batch-Abfragen mit dem Azure CLI erstellen.
Hinweis
Beim Erstellen dieser drei Typen von Abfragezeichenfolgen müssen Sie sicherstellen, dass die Namen und die Groß-/Kleinschreibung der Eigenschaften mit den entsprechenden REST-API-Elementen übereinstimmen. Wenn Sie beispielsweise mit der .NET-Klasse CloudTask arbeiten, müssen Sie state anstelle von State angeben, obwohl die .NET-Eigenschaft CloudTask.State lautet. Weitere Informationen finden Sie unter Eigenschaftszuordnungen zwischen der .NET- und der REST-API.
Filtern
Die $filter Ausdruckszeichenfolge ist ein Ausdruck, der die Anzahl der zurückgegebenen Elemente reduziert. Sie können beispielsweise die derzeit ausgeführten Aufgaben für einen Auftrag oder nur Computeknoten auflisten, die zum Ausführen von Aufgaben bereit sind.
Diese Zeichenfolge besteht aus mindestens einem Ausdruck, wobei ein Ausdruck aus einem Eigenschaftsnamen, einem Operator und einem Wert besteht. Die Eigenschaften, die angegeben werden können, sind spezifisch für jeden Entitätstyp, den Sie abfragen. Dies gilt auch für die für jede Eigenschaft unterstützten Operatoren. Mehrere Ausdrücke können mithilfe der logischen Operatoren and und or kombiniert werden.
Dieses Beispiel für eine Filterzeichenfolge listet nur die aktuell ausgeführten Renderaufgaben auf: (state eq 'running') and startswith(id, 'renderTask').
Auswählen
Die $select Ausdruckszeichenfolge begrenzt die Eigenschaftswerte, die für jedes Element zurückgegeben werden. Sie geben eine Liste mit durch Trennzeichen Eigenschaftsnamen an, woraufhin nur diese Eigenschaftswerte für die Elemente in den Abfrageergebnissen zurückgegeben werden. Sie können beliebige Eigenschaften für den Entitätstyp angeben, den Sie abfragen möchten.
Das folgende Beispiel gibt an, dass für jede Aufgabe nur drei Eigenschaftswerte zurückgegeben werden sollen: id, state, stateTransitionTime.
Expand
Die $expand Ausdruckszeichenfolge verringert die Anzahl der API-Aufrufe, die zum Abrufen bestimmter Informationen erforderlich sind. Sie können diese Zeichenfolge verwenden, um mit einem einzelnen API-Aufruf weitere Informationen zu jedem Element abzurufen. Diese Methode trägt zur Verbesserung der Leistung bei, indem API-Aufrufe reduziert werden. Verwenden Sie eine $expand Zeichenfolge, anstatt die Liste der Entitäten zu erhalten und Informationen zu jedem Listenelement anzufordern.
Ähnlich wie $select, $expand steuert die Erweiterungszeichenfolge, ob bestimmte Daten in die Listenabfrageergebnisse einbezogen werden. Wenn alle Eigenschaften erforderlich sind und keine Auswählzeichenfolge angegeben wurde, $expandmuss zum Abrufen von Statistikinformationen verwendet werden. Wenn eine Auswählzeichenfolge zum Abrufen einer Teilmenge der Eigenschaften verwendet wird, stats kann in der Auswählzeichenfolge angegeben werden, und $expand muss nicht angegeben werden.
Zu den unterstützten Verwendungsmöglichkeiten dieser Zeichenfolge gehören das Auflisten von Aufträgen, Auftragszeitplänen, Tasks und Pools. Derzeit bietet das Zeichenfolge nur Unterstützung für Statistikinformationen.
Das folgende Beispiel gibt an, dass für jedes Element in der Liste Statistikinformationen zurückgegeben werden sollen: stats.
Regeln für Filter-, Auswähl- und Erweiterungszeichenfolgen
- Stellen Sie sicher, dass Eigenschaftsnamen in Filter-, Auswähl- und Erweiterungszeichenfolgen so angezeigt werden, wie sie in der Batch REST-API erscheinen. Diese Regel gilt auch, wenn Sie Batch .NET oder eines der anderen Batch SDKs verwenden.
- Bei allen Eigenschaftsnamen muss die Groß- und Kleinschreibung beachtet werden, bei Eigenschaftswerten dagegen nicht.
- Datums-/Uhrzeitzeichenfolgen können eines von zwei Formaten besitzen, und ihnen muss
DateTimevorangestellt sein.- Beispiel für das W3C-DTF-Format:
creationTime gt DateTime'2011-05-08T08:49:37Z' - Beispiel für das RFC 1123-Format:
creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
- Beispiel für das W3C-DTF-Format:
- Boolesche Zeichenfolgen sind entweder
trueoderfalse. - Bei Angabe einer ungültigen Eigenschaft oder eines ungültigen Operators tritt der Fehler
400 (Bad Request)auf.
Effizientes Abfragen in Batch .NET
In der Batch .NET-API stellt die ODATADetailLevel-Klasse Filter-, Auswähl- und Erweiterungszeichenfolgen für Listenvorgänge bereit. Die ODataDetailLevel Klasse verfügt über drei öffentliche Zeichenfolgeneigenschaften. Sie können diese Eigenschaften im Konstruktor angeben oder die Eigenschaften direkt für das Objekt festlegen. Das ODataDetailLevel-Objekt wird dann als Parameter an die verschiedenen Listenvorgänge wie ListPools, ListJobs oder ListTasks übergeben.
- ODATADetailLevel.FilterClause: Begrenzt die Anzahl der zurückgegebenen Elemente.
- ODATADetailLevel.SelectClause: Gibt an, welche Eigenschaftswerte mit jedem Element zurückgegeben werden sollen.
- ODATADetailLevel.ExpandClause: Ruft Daten für alle Elemente in einem einzigen API-Aufruf statt mit separaten Aufrufen für jedes Element ab.
Im folgenden Codeausschnitt wird die Batch .NET-API verwendet, um den Batch-Dienst effizient auf die Statistik zu einer bestimmten Gruppe von Pools abzufragen. Der Batch-Benutzer verfügt über Test- und Produktionspools. Den Testpool-IDs ist das Präfix „test“ vorangestellt, und den Produktionspool-IDs ist das Präfix „prod“ vorangestellt. myBatchClient ist eine ordnungsgemäß initialisierte Instanz der BatchClient-Klasse.
// 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();
Tipp
Eine Instanz von ODATADetailLevel, die mit „Select“- und „Expand“-Klauseln konfiguriert wurde, kann auch an entsprechende „Get“-Methoden, z.B. PoolOperations.GetPool übergeben werden, um die Menge der zurückgegebenen Daten zu begrenzen.
Zuordnungen zwischen der Batch REST-API und .NET-API
Eigenschaftsnamen in Filter-, Auswähl- und Erweiterungszeichenfolgen müssen ihren Gegenstücken in der REST-API hinsichtlich Name und Groß-/Kleinschreibung entsprechen. Die folgenden Tabellen enthalten die Zuordnungen zwischen den .NET-APIs und ihren REST-API-Entsprechungen.
Zuordnungen für Filterzeichenfolgen
- .NET-Listenmethoden: Jede der .NET API-Methoden in dieser Spalte akzeptiert ein ODATADetailLevel-Objekt als Parameter.
- REST-Listenanforderungen: Jede in dieser Spalte aufgeführte REST-API-Seite enthält eine Tabelle mit den Eigenschaften und Vorgängen, die in Filterzeichenfolgen zulässig sind. Sie können diese Eigenschaftsnamen und Vorgänge beim Erstellen einer ODATADetailLevel.FilterClause-Zeichenfolge verwenden.
Zuordnungen für Auswählzeichenfolgen
- Batch .NET-Typen: Batch .NET-API-Typen.
- REST-API-Entitäten: Jede Seite in dieser Spalte enthält mindestens eine Tabelle mit den Namen der REST-API-Eigenschaften für den Typ. Diese Eigenschaftsnamen werden beim Erstellen von Auswählzeichenfolgen verwendet. Sie verwenden dieselben Eigenschaftsnamen, wenn Sie eine ODATADetailLevel.SelectClause-Zeichenfolge erstellen.
Beispiel: Erstellen einer Filterzeichenfolge
Um eine Filterzeichenfolge für ODATADetailLevel.FilterClausezu erstellen, suchen Sie die entsprechende REST-API-Seite. Auswählbare Eigenschaften und deren unterstützte Operatoren befinden sich in der ersten Mehrzeilentabelle. Um beispielsweise alle Aufgaben abzurufen, deren Exitcode ungleich Null war, aktivieren Sie Auflisten der einem Auftrag zugeordneten Aufgaben für die entsprechende Eigenschaftszeichenfolge und zulässigen Operatoren:
| Eigenschaft | Zulässige Vorgänge | type |
|---|---|---|
executionInfo/exitCode |
eq, ge, gt, le , lt |
Int |
Die zugehörige Filterzeichenfolge lautet:
(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)
Beispiel: Erstellen einer Auswählzeichenfolge
Um ODATADetailLevel.SelectClausezu erstellen, suchen Sie die entsprechende REST-API-Seite für die Entität, die Sie auflisten. Auswählbare Eigenschaften und deren unterstützte Operatoren befinden sich in der ersten Mehrzeilentabelle. Um beispielsweise nur die ID und die Befehlszeile für jede Aufgabe in einer Liste abzurufen, aktivieren Sie Informationen zu einer Aufgabe abrufen:
| Eigenschaft | type | Notizen |
|---|---|---|
id |
String |
The ID of the task. |
commandLine |
String |
The command line of the task. |
Die zugehörige Select-Zeichenfolge lautet:
id, commandLine
Codebeispiele
Effiziente Listenabfragen
Das Beispielprojekt EfficientListQueries auf GitHub zeigt, wie sich effiziente Listenabfragen auf die Anwendungsleistung auswirken. Diese C#-Konsolenanwendung erstellt eine große Anzahl von Aufgaben und fügt sie einem Auftrag hinzu. Anschließend führt die Anwendung mehrere Aufrufe der JobOperations.ListTasks-Methode aus und übergibt ODATADetailLevel-Objekte. Diese Objekte werden mit unterschiedlichen Eigenschaftswerten konfiguriert, um die Menge der zurückzugebenden Daten zu variieren. Dieses Beispiel erzeugt eine Ausgabe ähnlich der:
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...
Das Beispiel zeigt, dass Sie die Antwortzeiten von Abfragen erheblich verkürzen können, indem Sie die Eigenschaften und die Anzahl der zurückgegebenen Elemente einschränken. Sie finden dieses Beispielprojekt und weitere Beispielprojekte im azure-batch-samples-Repository auf GitHub.
BatchMetrics-Bibliothek
Das BatchMetrics-Beispielprojekt veranschaulicht die effiziente Überwachung des Azure Batch-Auftragsstatus mithilfe der Batch-API.
Dieses Beispiel enthält ein .NET-Klassenbibliotheksprojekt, das Sie in Ihre eigenen Projekte integrieren können. Es gibt auch ein einfaches Befehlszeilenprogramm zum Ausführen und Veranschaulichen der Verwendung der Bibliothek.
Die Beispielanwendung innerhalb des Projekts veranschaulicht diese Vorgänge:
- Auswählen bestimmter Attribute, um nur die benötigten Eigenschaften herunterzuladen
- Filtern nach Statusübergangszeiten, um nur Änderungen seit der letzten Abfrage herunterzuladen
Die BatchMetrics-Bibliothek enthält beispielsweise die folgende Methode. Diese gibt ein ODATADetailLevel-Objekt zurück, mit dem angegeben wird, dass für die abgefragten Entitäten nur die Eigenschaften id und state abgerufen werden sollen. Außerdem gibt es an, dass nur Entitäten zurückgegeben werden sollen, deren Status sich seit dem angegebenen DateTime -Parameter geändert hat.
internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
return new ODATADetailLevel(
selectClause: "id, state",
filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
);
}
Nächste Schritte
- Maximieren der Azure Batch Compute-Ressourcenauslastung mit parallelen Knotenaufgaben. Einige Arten von Workloads profitieren von der Ausführung paralleler Aufgaben auf größeren (und dafür weniger) Computeknoten. Ausführlichere Informationen zu einem solchen Szenario finden Sie im Beispielszenario des Artikels.
- Überwachen von Batch-Lösungen durch Zählen von Tasks und Knoten nach Status