Udostępnij za pośrednictwem

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

  • Artykuł

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. Zapytania filtrowane dla zadań usługi Batch, zadań, węzłów obliczeniowych i innych zasobów można tworzyć za pomocą biblioteki platformy .NET usługi Batch.

Uwaga

Usługa Batch zapewnia obsługę interfejsu API dla typowych scenariuszy zliczania zadań w zadaniu i zliczania węzłów obliczeniowych w puli usługi Batch. Operacje Pobierz liczby zadań i Liczby węzłów puli listy można wywołać zamiast przy użyciu zapytania listy. Jednak te bardziej wydajne operacje zwracają bardziej ograniczone informacje, które mogą nie być aktualne. Aby uzyskać więcej informacji, zobacz Liczba zadań i węzłów obliczeniowych według stanu.

Określanie poziomu szczegółów

W produkcyjnej aplikacji usługi Batch mogą istnieć tysiące jednostek, takich jak zadania, 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ółów do zapytania, aby wydajniej wyświetlić informacje o liście. Podaj obiekt ODATADetailLevel metodzie JobOperations.ListTasks. Ten fragment kodu zwraca tylko właściwości identyfikatora, wiersza polecenia i węzła obliczeniowego 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 elementów listy przy użyciu ODATADetailLevel interfejsu API platformy .NET usługi Batch, zobacz sekcję Wydajne wykonywanie zapytań na platformie .NET usługi Batch.

Ważne

Zdecydowanie zalecamy, aby zawsze dostarczać ODATADetailLevel obiekt do listy interfejsów API platformy .NET w celu uzyskania maksymalnej wydajności i wydajności aplikacji. Określając poziom szczegółowości, możesz pomóc zmniejszyć czasy odpowiedzi usługi Batch, poprawić wykorzystanie sieci i zminimalizować użycie pamięci przez aplikacje klienckie.

Używanie ciągów zapytania

Za pomocą interfejsów API REST platformy .NET i usługi Batch można zmniejszyć liczbę elementów zwracanych przez zapytanie oraz ilość informacji zwracanych przez zapytanie 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ę również z sekcją Wydajne wykonywanie zapytań na platformie .NET usługi Batch.

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 o $filterelementach , $selecti $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.

Uwaga

Podczas konstruowania dowolnego z trzech typów ciągów zapytania należy upewnić się, że nazwy właściwości i wielkość liter są zgodne z ich odpowiednikami elementów interfejsu API REST. Na przykład podczas pracy z klasą .NET CloudTask należy określić stan zamiast State, mimo że właściwość .NET to CloudTask.State. Aby uzyskać więcej informacji, zobacz mapowania właściwości między platformą .NET i interfejsami API REST.

Filtr

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óry wykonasz zapytanie, podobnie jak operatory obsługiwane 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').

Wybierz pozycję

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.

Rozwiń

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 $selectw przypadku elementu , $expand określa, czy niektóre dane znajdują się w wynikach zapytania listy. Jeśli wszystkie właściwości są wymagane i nie określono żadnego wybranego ciągu, $expand należ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 go określić w ciągu zaznaczenia i $expand nie trzeba go określać.

Obsługiwane zastosowania tego ciągu obejmują wyświetlanie listy zadań, harmonogramów zadań, zadań i pul. Obecnie ciąg 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 filtrze, zaznacz i rozwiń ciągi wyświetlane tak jak w interfejsie API REST usługi Batch. Ta reguła ma zastosowanie nawet w przypadku korzystania z platformy .NET usługi Batch lub jednego z innych zestawów SDK usługi Batch.
  • W nazwach właściwości uwzględniana jest wielkość liter, ale w wartościach właściwości jest rozróżniana wielkość liter.
  • Ciągi daty/godziny mogą być jednym z dwóch formatów i muszą być poprzedzone ciągami 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 false.
  • Jeśli określono nieprawidłową właściwość lub operator, 400 (Bad Request) zostanie wyświetlony błąd.

Wydajne wykonywanie zapytań na platformie .NET usługi Batch

W interfejsie API .NET usługi Batch klasa ODATADetailLevel udostępnia filtr, wybierz i rozwiń ciągi, aby wyświetlić listę operacji. 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.

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

Napiwek

Wystąpienie klasy ODATADetailLevel skonfigurowane przy użyciu klauzul Select i Expand można również przekazać do odpowiednich metod Get, takich jak PoolOperations.GetPool, aby ograniczyć ilość zwracanych danych.

Mapowania interfejsu API rest usługi Batch na platformę .NET

Nazwy właściwości w filtrze, zaznacz i rozwiń ciągi muszą odzwierciedlać ich odpowiedniki interfejsu API REST, zarówno w nazwie, jak i wielkości 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 Żądania listy REST
CertificateOperations.ListCertificates Wyświetlanie listy certyfikatów na koncie
CloudTask.ListNodeFiles Wyświetlanie listy plików skojarzonych z zadaniem
JobOperations.ListJobPreparationAndReleaseTaskStatus Wyświetlanie stanu zadań podrzędnych przygotowania zadania i zwolnienia zadania dla zadania
JobOperations.ListJobs Wyświetlanie listy zadań na koncie
JobOperations.ListNodeFiles Wyświetlanie listy plików w węźle
JobOperations.ListTasks Wyświetlanie listy zadań skojarzonych z zadaniem
JobScheduleOperations.ListJobSchedules Wyświetlanie listy harmonogramów zadań na koncie
JobScheduleOperations.ListJobs Wyświetlanie listy zadań skojarzonych z harmonogramem zadań
PoolOperations.ListComputeNodes Wyświetlanie listy węzłów obliczeniowych w puli
PoolOperations.ListPools Wyświetlanie listy pul na koncie

Mapowania dla wybranych ciągów

  • Typy platformy .NET usługi Batch: typy interfejsu API .NET 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 .
Typy platformy .NET usługi Batch Jednostki interfejsu API REST
Certyfikat Uzyskiwanie informacji o certyfikacie
CloudJob Uzyskiwanie informacji o zadaniu
CloudJobSchedule Uzyskiwanie informacji o harmonogramie zadań
ComputeNode Uzyskiwanie informacji o węźle
Pula chmury Uzyskiwanie informacji o puli
CloudTask Uzyskiwanie informacji o zadaniu

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żzerowy, zaznacz listę zadań skojarzonych z zadaniem dla odpowiedniego ciągu właściwości i dozwolonych operatorów:

Właściwości Dozwolone operacje Typ
executionInfo/exitCode eq, ge, gt, le , lt Int

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:

Właściwość Type Uwagi
id String The ID of the task.
commandLine String The command line of the task.

Powiązany ciąg wyboru to:

id, commandLine

Przykłady kodu

Wydajne zapytania dotyczące list

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 właściwości i state powinny zostać uzyskane dla jednostek, których dotyczy zapytanie. Określa również, że powinny zostać zwrócone tylko jednostki, których stan uległ zmianie od czasu zwrócenia określonego DateTime parametru.

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

Następne kroki