Tworzenie zapytań w celu wydajnego wyświetlania listy zasobów usługi Batch

Większość aplikacji usługi Azure Batch wykonuje monitorowanie lub inne operacje, które wysyłają zapytania do usługi Batch. Takie zapytania dotyczące listy często odbywają się w regularnych odstępach czasu. Na przykład przed sprawdzeniem podzadań w kolejce w zadaniu należy pobrać dane dotyczące każdego zadania w tym zadaniu. Zmniejszenie ilości danych zwracanych przez usługę Batch dla zapytań zwiększa wydajność aplikacji. W tym artykule wyjaśniono, jak tworzyć i wykonywać takie zapytania w wydajny sposób. Możesz tworzyć filtrowane zapytania dotyczące zadań Batch, operacji, węzłów obliczeniowych i innych zasobów za pomocą biblioteki Batch .NET.

Określanie poziomu szczegółów

W produkcyjnej aplikacji usługi Batch mogą istnieć tysiące jednostek, takich jak prace, zadania i węzły obliczeniowe. Dla każdego zapytania dotyczącego zasobów potencjalnie duża ilość danych jest kierowana z usługi Batch do aplikacji. Ogranicz liczbę elementów i informacje zwracane przez zapytanie w celu zwiększenia wydajności.

Ten fragment kodu interfejsu API platformy .NET usługi Batch zawiera listę wszystkich zadań skojarzonych z zadaniem wraz ze wszystkimi właściwościami każdego zadania.

// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
    batchClient.JobOperations.ListTasks("job-001");

Zastosuj poziom szczegółowości do swojego zapytania, aby efektywniej wyświetlać informacje. Podaj obiekt ODATADetailLevel metodzie JobOperations.ListTasks . Ten fragment kodu zwraca tylko właściwości ID, wiersza poleceń i informacji o węźle obliczeniowym ukończonych zadań.

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

W tym przykładowym scenariuszu, jeśli w zadaniu znajdują się tysiące zadań, wyniki z drugiego zapytania są zwykle zwracane szybciej niż z pierwszego zapytania. Aby uzyskać więcej informacji na temat używania ODATADetailLevel przy wymienianiu elementów z interfejsem Batch .NET API, zobacz sekcję Wydajne wykonywanie zapytań w Batch .NET.

Używanie ciągów zapytania

Można używać interfejsów API Batch .NET i Batch REST do zmniejszenia liczby elementów zwracanych przez zapytanie oraz ilości informacji zwracanych dla każdego elementu. Istnieją trzy typy ciągów zapytania, których można użyć do zawężenia zapytania: $filter, $select i $expand.

Aby zapoznać się z interfejsem API platformy .NET usługi Batch, zobacz właściwości klasy ODATADetailLevel. Zapoznaj się także z sekcją Efektywne zapytania w Batch .NET.

Aby zapoznać się z interfejsem API REST usługi Batch, zobacz dokumentację interfejsu API REST usługi Batch. Znajdź odwołanie do listy zasobu, którego chcesz wykonać zapytanie. Następnie przejrzyj sekcję Parametry identyfikatora URI, aby uzyskać szczegółowe informacje dotyczące $filter, $select i $expand. Zobacz na przykład parametry identyfikatora URI dla puli — lista. Zobacz również , jak wydajnie wykonywać zapytania usługi Batch za pomocą interfejsu wiersza polecenia platformy Azure.

Filter

Ciąg $filter wyrażenia zmniejsza liczbę zwracanych elementów. Można na przykład wyświetlić listę tylko uruchomionych zadań dla zadania lub wyświetlić listę tylko węzłów obliczeniowych, które są gotowe do uruchamiania zadań.

Ten ciąg składa się z co najmniej jednego wyrażenia z wyrażeniem składającym się z nazwy właściwości, operatora i wartości. Właściwości, które można określić, są specyficzne dla każdego typu jednostki, którego zapytujesz, podobnie jak obsługiwane operatory dla każdej właściwości. Wiele wyrażeń można łączyć przy użyciu operatorów and logicznych i or.

W tym przykładzie wymieniono tylko uruchomione zadania renderowania: (state eq 'running') and startswith(id, 'renderTask').

Select

Ciąg $select wyrażenia ogranicza wartości właściwości zwracane dla każdego elementu. Należy określić listę nazw właściwości rozdzielonych przecinkami, a tylko te wartości właściwości są zwracane dla elementów w wynikach zapytania. Możesz określić dowolną z właściwości dla typu jednostki, do którego wysyłasz zapytanie.

W tym przykładzie określono, że dla każdego zadania powinny być zwracane tylko trzy wartości właściwości: id, state, stateTransitionTime.

Expand

Ciąg $expand wyrażenia zmniejsza liczbę wywołań interfejsu API wymaganych do uzyskania określonych informacji. Możesz użyć tego ciągu, aby uzyskać więcej informacji o każdym elemencie z jednym wywołaniem interfejsu API. Ta metoda pomaga zwiększyć wydajność, zmniejszając liczbę wywołań interfejsu API. $expand Użyj ciągu zamiast pobierania listy jednostek i żądania informacji o każdym elemencie listy.

Podobnie jak $select, $expand kontroluje, czy określone dane są uwzględniane w wynikach zapytania listy. Jeśli wszystkie właściwości są wymagane i nie określono żadnego wybranego ciągu, $expandnależy użyć go do uzyskania informacji statystycznych. Jeśli wybrany ciąg jest używany do uzyskania podzestawu właściwości, stats można określić w ciągu zaznaczenia i $expand nie trzeba określać.

Obsługiwane zastosowania tego ciągu obejmują wyświetlanie listy zadań, harmonogramów zadań, zadań i pul. Obecnie ciąg znaków obsługuje tylko informacje statystyczne.

W tym przykładzie określono, że informacje statystyczne powinny być zwracane dla każdego elementu na liście: stats.

Reguły filtrowania, wybierania i rozwijania ciągów

• Upewnij się, że nazwy właściwości w ciągach filtr, select i expand pojawiają się tak, jak w interfejsie API Batch REST. Ta reguła ma zastosowanie nawet w przypadku korzystania z Batch .NET lub jednego z innych zestawów SDK usługi Batch.
• Nazwy właściwości są rozróżniane pod względem wielkości liter, ale wartości właściwości są niewrażliwe na wielkość liter.
• Ciągi daty/godziny mogą być w jednym z dwóch formatów i muszą być poprzedzone znakiem DateTime.
  • przykład formatu W3C-DTF: creationTime gt DateTime'2011-05-08T08:49:37Z'
  • Przykład formatu RFC 1123: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
• Ciągi logiczne są albo true, albo false.
• Jeśli określono nieprawidłową właściwość lub operator, wystąpi błąd 400 (Bad Request).

Wydajne wykonywanie zapytań w Batch .NET

W interfejsie API Batch .NET klasa ODATADetailLevel udostępnia ciągi filtrujące, wybierające i rozszerzające dla operacji listowania. Klasa ODataDetailLevel ma trzy właściwości ciągów publicznych. Można określić te właściwości w konstruktorze lub ustawić właściwości bezpośrednio w obiekcie. Następnie przekaż ODataDetailLevel obiekt jako parametr do różnych operacji listy, takich jak ListPools, ListJobs i ListTasks.

• ODATADetailLevel.FilterClause: Ogranicz liczbę zwracanych elementów.
• ODATADetailLevel.SelectClause: określ, które wartości właściwości są zwracane z każdym elementem.
• ODATADetailLevel.ExpandClause: pobieranie danych dla wszystkich elementów w jednym wywołaniu interfejsu API zamiast oddzielnych wywołań dla każdego elementu.

Poniższy fragment kodu używa interfejsu API .NET usługi Batch do wydajnego wykonywania zapytań dotyczących usługi Batch pod kątem statystyk określonego zestawu pul. Użytkownik usługi Batch ma pule testowe i produkcyjne. Identyfikatory puli testów mają prefiks "test", a identyfikatory puli produkcyjnej mają prefiks "prod". myBatchClient to prawidłowo zainicjowane wystąpienie klasy 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();

Mapowania interfejsów API Batch REST do platformy .NET

Nazwy właściwości w ciągach filtr, select i expand muszą odzwierciedlać swoje odpowiedniki w REST API, zarówno ich nazwę, jak i wielkość liter. W poniższych tabelach przedstawiono mapowania między odpowiednikami platformy .NET i interfejsu API REST.

Mapowania ciągów filtrów

• Metody listy platformy .NET: Każda z metod interfejsu API platformy .NET w tej kolumnie akceptuje obiekt ODATADetailLevel jako parametr.
• Żądania listy REST: każda strona interfejsu API REST wymieniona w tej kolumnie zawiera tabelę z właściwościami i operacjami dozwolonymi w ciągach filtru. Te nazwy właściwości i operacje można użyć podczas konstruowania ciągu ODATADetailLevel.FilterClause .

Mapowania dla wybranych stringów

• Typy .NET usługi Batch: typy interfejsu API .NET dla usługi Batch.
• Jednostki interfejsu API REST: każda strona w tej kolumnie zawiera co najmniej jedną tabelę zawierającą nazwy właściwości interfejsu API REST dla typu. Te nazwy właściwości są używane podczas konstruowania wybranych ciągów. Te same nazwy właściwości są używane podczas konstruowania ciągu ODATADetailLevel.SelectClause .

Przykład: konstruowanie ciągu filtru

Aby utworzyć ciąg filtru dla funkcji ODATADetailLevel.FilterClause, znajdź odpowiednią stronę interfejsu API REST. Właściwości możliwe do wybrania i ich obsługiwane operatory znajdują się w pierwszej tabeli z wieloma wierszami. Aby na przykład pobrać wszystkie zadania, których kod zakończenia był inny niż zero, sprawdź Listę zadań skojarzonych z projektem dla odpowiedniego ciągu właściwości i dozwolonych operatorów:

Powiązany ciąg filtru to:

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

Przykład: konstruowanie ciągu wyboru

Aby utworzyć obiekt ODATADetailLevel.SelectClause, znajdź odpowiednią stronę interfejsu API REST dla jednostki, którą wymieniasz. Właściwości możliwe do wybrania i ich obsługiwane operatory znajdują się w pierwszej tabeli z wieloma wierszami. Aby na przykład pobrać tylko identyfikator i wiersz polecenia dla każdego zadania na liście, zobacz Pobieranie informacji o zadaniu:

Powiązany ciąg wyboru to:

id, commandLine

Przykłady kodu

Wydajne zapytania dotyczące listy

Przykładowy projekt EfficientListQueries pokazuje, jak wydajne wykonywanie zapytań dotyczących listy wpływa na wydajność aplikacji. Ta aplikacja konsolowa języka C# tworzy i dodaje dużą liczbę zadań do zadania. Następnie aplikacja wykonuje wiele wywołań metody JobOperations.ListTasks i przekazuje obiekty ODATADetailLevel . Te obiekty są konfigurowane z różnymi wartościami właściwości, aby zmieniać ilość zwracanych danych. Ten przykład generuje dane wyjściowe podobne do następujących:

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...

W przykładzie pokazano, że można znacznie obniżyć czasy odpowiedzi zapytania, ograniczając właściwości i liczbę zwracanych elementów. Te i inne przykładowe projekty można znaleźć w repozytorium azure-batch-samples w witrynie GitHub.

Biblioteka usługi BatchMetrics

Poniższy przykładowy projekt BatchMetrics pokazuje, jak efektywnie monitorować postęp zadania usługi Azure Batch przy użyciu interfejsu API usługi Batch.

Ten przykład zawiera projekt biblioteki klas platformy .NET, który można uwzględnić we własnych projektach. Istnieje również prosty program wiersza polecenia do ćwiczenia i zademonstrowania korzystania z biblioteki.

Przykładowa aplikacja w projekcie demonstruje następujące operacje:

• Wybieranie określonych atrybutów w celu pobrania tylko potrzebnych właściwości
• Filtrowanie czasów przejścia stanu w celu pobrania tylko zmian od ostatniego zapytania

Na przykład poniższa metoda jest wyświetlana w bibliotece BatchMetrics. Zwraca on element ODATADetailLevel, który określa, że tylko id i state właściwości powinny zostać uzyskane dla jednostek, które są przedmiotem zapytania. Określa również, że powinny zostać zwrócone tylko jednostki, których stan uległ zmianie od czasu określonego przez DateTime parametr.

internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
    return new ODATADetailLevel(
        selectClause: "id, state",
        filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
    );
}

Dalsze kroki

• Maksymalizuj użycie zasobów obliczeniowych usługi Azure Batch przy użyciu współbieżnych zadań węzłów. Niektóre typy obciążeń mogą korzystać z wykonywania zadań równoległych na większych (ale mniej) węzłach obliczeniowych. Zapoznaj się z przykładowym scenariuszem w artykule, aby uzyskać szczegółowe informacje na temat takiego scenariusza.
• Monitorowanie rozwiązań w usłudze Batch poprzez zliczanie zadań i węzłów w zależności od ich stanu