Erstellen von Abfragen zum effizienten Auflisten von Batch-Ressourcen

Die meisten Azure Batch-Anwendungen führen Überwachungen durch oder andere Vorgänge, die den Batch-Dienst abfragen. Solche Listenabfragen erfolgen häufig in regelmäßigen Abständen. Bevor Sie beispielsweise Aufgaben in einem Auftrag in der Warteschlange überprüfen können, müssen Sie Daten zu jeder Aufgabe 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 mit der Bibliothek Azure.Compute.Batch gefilterte Abfragen für Batchaufträge, Aufgaben, Computeknoten und andere Ressourcen erstellen.

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.

Dieser Azure.Compute.Batch-API-Codeausschnitt listet jede Aufgabe auf, die einem Auftrag zugeordnet ist, sowie alle Eigenschaften jeder Aufgabe.

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

Wenden Sie eine Detailebene auf Ihre Abfrage an, um Informationen effizienter aufzulisten. Übergeben filter, selectund expand Zeichenfolgen an die BatchClient.GetTasks-Methode . Dieser Codeausschnitt gibt nur die ID-, Befehlszeilen- und Computeknoteneigenschaften abgeschlossener Aufgaben zurück.

// 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" });

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 der Parameter filter, select und expand mit der Azure.Compute.Batch-API finden Sie im Abschnitt Effiziente Abfragen in Azure.Compute.Batch.

Verwenden Sie Abfragezeichenfolgen.

Sie können die Azure.Compute.Batch- und Batch REST-APIs verwenden, um die Anzahl der von einer Abfrage zurückgegebenen Elemente sowie die Menge der zu jedem Element zurückgegebenen Informationen zu verringern. Es gibt drei Arten von Abfragezeichenfolgen, mit denen Sie Ihre Abfrage eingrenzen können: $filter, $select und $expand.

Für die Azure.Compute.Batch-API siehe die BatchClient-Referenz für die Methode „list“, deren Parameter filter, select und expand Sie verwenden möchten. Lesen Sie auch den Abschnitt Effiziente Abfragen in Azure.Compute.Batch.

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.

Filter

Die $filter Ausdruckszeichenfolge verringert die Anzahl der zurückgegebenen Elemente. Sie können beispielsweise nur die derzeit ausgeführten Aufgaben für einen Auftrag auflisten oder nur Rechenknoten 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 listet nur die laufenden 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 Kommas getrennten Eigenschaftsnamen an, und nur die Werte dieser Eigenschaften werden für die Elemente in den Abfrageergebnissen zurückgegeben. 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 kontrolliert $expand, ob bestimmte Daten in die Ergebnisse von Listenabfragen 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 unterstützt die Zeichenfolge nur 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 dann, wenn Sie Azure verwenden. Compute.Batch oder einer der anderen Batch-SDKs.
• 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'
• Boolesche Zeichenfolgen sind entweder true oder false.
• Bei Angabe einer ungültigen Eigenschaft oder eines ungültigen Operators tritt der Fehler 400 (Bad Request) auf.

Effiziente Abfrage in Azure. Compute.Batch

Im Azure. Compute.Batch-API, die Listenmethoden für BatchClient akzeptieren filter, select und expand Parameter direkt:

• filter: Beschränken Sie die Anzahl der zurückgegebenen Elemente.
• select: Geben Sie an, welche Eigenschaftswerte mit jedem Element zurückgegeben werden.
• expand: Abrufen von Daten für alle Elemente in einem einzelnen API-Aufruf anstelle separater Aufrufe für jedes Element.

Der folgende Codeausschnitt verwendet die Azure. Compute.Batch-API zum effizienten Abfragen des Batchdiensts für die Statistiken einer bestimmten Gruppe von Pools. 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.

// 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);
}

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 filter, select und expand Zeichenfolgenparameter.
• 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 verwenden, wenn Sie eine filter Zeichenfolge erstellen.

Zuordnungen für bestimmte Zeichenfolgen

• Azure. Compute.Batch-Typen: Azure. Compute.Batch-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. Beim Erstellen einer select Zeichenfolge verwenden Sie dieselben Eigenschaftsnamen.

Beispiel: Erstellen einer Filterzeichenfolge

Um eine Filterzeichenfolge für den Parameter einer Listenmethode filter zu 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:

Die zugehörige Filterzeichenfolge lautet:

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

Beispiel: Erstellen einer Auswählzeichenfolge

Um eine select Zeichenfolge zu 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:

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 an die BatchClient.GetTasks-Methode durch und übergibt unterschiedliche filterWerte selectund expand Parameterwerte, um die menge der zurückgegebenen 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 Ausprobieren 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. Es gibt ein Tupel zurück, das die Zeichenfolgen select und filter enthält, die angeben, dass für die abgefragten Entitäten nur die Eigenschaften id und state abgerufen werden sollen und dass nur Entitäten zurückgegeben werden sollen, deren Zustand sich seit dem angegebenen Parameter DateTime geändert hat.

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

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