Efektivní vytváření dotazů pro výpis prostředků služby Batch

Většina aplikací Azure Batch provádí monitorování nebo jiné operace, které se dotazují na službu Batch. K těmto dotazům v seznamu často dochází v pravidelných intervalech. Než například budete moct zkontrolovat úkoly zařazené do fronty v úloze, musíte získat data pro každý úkol v této úloze. Snížení množství dat, která služba Batch vrací pro dotazy, zlepšuje výkon vaší aplikace. Tento článek vysvětluje, jak efektivně vytvářet a spouštět takové dotazy. Pomocí Azure můžete vytvářet filtrované dotazy pro úlohy, úlohy, výpočetní uzly a další prostředky služby Batch. Compute.Batch knihovna

Poznámka:

Služba Batch poskytuje podporu rozhraní API pro běžné scénáře počítání úkolů v úloze a počítání výpočetních uzlů ve fondu Batch. Místo použití dotazu seznamu můžete volat operace Získat počty úkolů a Vypsat počty uzlů fondu. Tyto efektivnější operace ale vrací omezenější informace, které nemusí být aktuální. Další informace najdete v tématu Počet úkolů a výpočetních uzlů podle stavu.

Zadání úrovně podrobností

V produkční aplikaci Batch můžou existovat tisíce entit, jako jsou úlohy, úkoly a výpočetní uzly. U každého dotazu, který o prostředcích provedete, se potenciálně velké množství dat dostane ze služby Batch do vaší aplikace. Omezte počet položek a informací, které dotaz vrací, aby se zlepšil výkon.

Tento fragment kódu rozhraní API Azure.Compute.Batch vypisuje každý úkol přidružený k úloze spolu se všemi vlastnostmi každého úkolu.

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

Efektivnějším použitím úrovně podrobností na dotaz zobrazíte seznam informací. Předejte řetězce filter, select a expand metodě BatchClient.GetTasks. Tento fragment vrátí pouze ID, příkazový řádek a informace o výpočetním uzlu dokončených úloh.

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

Pokud v tomto ukázkovém scénáři existují tisíce úkolů v úloze, výsledky druhého dotazu se obvykle vrátí rychleji než z prvního dotazu. Další informace o použití parametrů filter, select a expand s rozhraním API Azure.Compute.Batch naleznete v části Efektivní dotazování v Azure.Compute.Batch.

Důležité

Důrazně doporučujeme, abyste při voláních seznamu rozhraní API .NET vždy předávali řetězce filter, select a (v případě potřeby) expand, aby byla zajištěna maximální efektivita a výkon vaší aplikace. Zadáním úrovně podrobností můžete pomoct snížit dobu odezvy služby Batch, zlepšit využití sítě a minimalizovat využití paměti klientskými aplikacemi.

Použití řetězců dotazu

Můžete použít rozhraní API Azure.Compute.Batch a Batch REST k omezení počtu položek vrácených dotazem a množství informací vrácených dotazem pro každou položku. K zúžení dotazu můžete použít tři typy řetězců dotazu: $filter, $select a $expand.

Informace o rozhraní API Azure.Compute.Batch najdete v referenční dokumentaci ke třídě BatchClient, konkrétně u metody list, jejíž parametry filter, select a expand chcete použít. Projděte si také část Efektivní dotazy v Azure.Compute.Batch.

Informace o rozhraní REST API služby Batch najdete v referenčních informacích k rozhraní REST API služby Batch. Vyhledejte referenční informace k seznamu pro prostředek, který chcete dotazovat. Poté si v části Parametry URI projděte podrobnosti o $filter, $select a $expand. Podívejte se například na parametry identifikátoru URI pro pool – seznam. Podívejte se také, jak provádět efektivní dotazy batch pomocí Azure CLI.

Poznámka:

Při vytváření některého ze tří typů řetězců dotazu musíte zajistit, aby názvy vlastností a jejich velikost písmen odpovídaly jejich obdobám v prvcích REST API. Například při práci se třídou .NET BatchTask musíte zadat state místo State, i když vlastnost .NET je BatchTask.State. Další informace najdete v mapování vlastností mezi rozhraními .NET a ROZHRANÍMI REST API.

Filtrovat

Řetězec $filter výrazu snižuje počet vrácených položek. Můžete například vypsat jenom spuštěné úkoly pro úlohu nebo vypsat jenom výpočetní uzly, které jsou připravené ke spuštění úkolů.

Tento řetězec se skládá z jednoho nebo více výrazů s výrazem, který se skládá z názvu vlastnosti, operátoru a hodnoty. Vlastnosti, které lze zadat, jsou specifické pro každý typ entity, který dotazujete, stejně jako operátory, které jsou podporovány pro každou vlastnost. Více výrazů lze kombinovat pomocí logických operátorů and a or.

Tento příklad uvádí pouze spuštěné úlohy vykreslování: (state eq 'running') and startswith(id, 'renderTask').

Vyberte

Řetězec $select výrazu omezuje hodnoty vlastností vrácené pro každou položku. Zadáte seznam názvů vlastností oddělených čárkami a pro položky ve výsledcích dotazu se vrátí pouze tyto hodnoty vlastností. Můžete zadat libovolné vlastnosti pro typ entity, který dotazujete.

Tento příklad určuje, že pro každý úkol by měly být vráceny pouze tři hodnoty vlastností: id, state, stateTransitionTime.

Rozbalit

Řetězec $expand výrazu snižuje počet volání rozhraní API, která jsou nutná k získání určitých informací. Tento řetězec můžete použít k získání dalších informací o každé položce pomocí jednoho volání rozhraní API. Tato metoda pomáhá zlepšit výkon snížením volání rozhraní API. Místo získání seznamu entit a vyžádání informací o jednotlivých položkách seznamu použijte řetězec $expand.

Podobně jako $select, $expand určuje, zda jsou zahrnuta určitá data do výsledků dotazu seznamu. Pokud jsou požadovány všechny vlastnosti a není zadán žádný výběrový řetězec, $expandje nutné použít k získání informací o statistikách. Pokud se k získání podmnožiny vlastností používá výběrový řetězec, stats můžete ho zadat v řetězci select a $expand není nutné ho zadat.

Mezi podporované použití tohoto řetězce patří výpis úloh, plánů úloh, úkolů a fondů. V současné době řetězec podporuje pouze informace o statistikách.

Tento příklad určuje, že informace o statistikách by měly být vráceny pro každou položku v seznamu: stats.

Pravidla pro filtrování, výběr a rozšíření řetězců

  • Ujistěte se, že se názvy vlastností v řetězcích filtru, výběru a rozbalení zobrazují tak, jak se objevují v Batch REST API. Toto pravidlo platí i v případě, že používáte Azure. Compute.Batch nebo jednu z dalších sad SDK služby Batch
  • Názvy všech vlastností jsou citlivé na velikost písmen, ale hodnoty vlastností nikoli.
  • Řetězce data a času mohou být jedním ze dvou formátů a musí předcházet DateTime.
    • Příklad formátu W3C-DTF: creationTime gt DateTime'2011-05-08T08:49:37Z'
    • Příklad formátu RFC 1123: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
  • Logické řetězce jsou buď true nebo false.
  • Pokud je zadána neplatná vlastnost nebo operátor, dojde k 400 (Bad Request) chybě.

Efektivní dotazování v Azure Compute.Batch

V rozhraní API Azure.Compute.Batch přijímají metody pro výpis na BatchClient parametry filter, select a expand přímo:

  • filter: Omezte počet vrácených položek.
  • select: Určete, které hodnoty vlastností se vrátí s každou položkou.
  • expand: Načtěte data pro všechny položky v jednom volání rozhraní API místo samostatných volání pro každou položku.

Následující fragment kódu používá rozhraní API Azure.Compute.Batch k efektivnímu dotazování služby Batch na statistiky konkrétní sady fondů. Batch uživatel má testovací i produkční pooly. ID testovacího fondu mají předponu "test" a ID produkčního fondu mají předponu "prod". myBatchClient je správně inicializovaná instance třídy BatchClient .

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

Tip

Stejné filter, selecta expand parametry lze také předat příslušným metodám Get, jako je BatchClient.GetPool, aby se omezilo množství vrácených dat.

Mapování rozhraní REST batch na rozhraní .NET API

Názvy vlastností ve filtrech, výběrech a rozšíření řetězců musí odpovídat svým protějškům v rozhraní REST API, a to jak názvem, tak i velikostí písmen. Následující tabulky poskytují mapování mezi protějšky rozhraní .NET a REST API.

Mapování řetězců filtru

  • .NET metody seznamu: Každá z metod rozhraní API .NET v tomto sloupci přijímá parametry řetězce filter, select a expand.
  • Požadavky na seznam REST: Každá stránka rozhraní REST API uvedená v tomto sloupci obsahuje tabulku s vlastnostmi a operacemi povolenými ve filtrovacích řetězcích. Tyto názvy vlastností a operace můžete použít při vytváření filter řetězce.
Metody seznamu .NET Požadavky na seznam REST
BatchAccountResource.GetBatchAccountCertificates Výpis certifikátů v účtu
BatchClient.GetTaskFiles Zobrazení seznamu souborů přidružených k úkolu
BatchClient.GetJobPreparationAndReleaseTaskStatuses Seznamte stav úkolů přípravy a uvolnění úlohy
BatchClient.GetJobs Výpis úloh v účtu
BatchClient.GetNodeFiles Výpis souborů na uzlu
BatchClient.GetTasks Výpis úkolů přidružených k úloze
BatchClient.GetJobSchedules Výpis plánů úloh v účtu
BatchClient.GetJobsFromSchedule Výpis úloh přidružených k plánu úloh
BatchClient.GetNodes Výpis výpočetních uzlů ve fondu
BatchClient.GetPools Výpis fondů v účtu

Mapování pro vybrané řetězce

  • Typy Azure.Compute.Batch: typy rozhraní API Azure.Compute.Batch.
  • Entity REST API: Každá stránka v tomto sloupci obsahuje jednu nebo více tabulek, které uvádějí názvy vlastností pro REST API pro daný typ. Tyto názvy vlastností se používají při vytváření výběrových řetězců. Při vytváření select řetězce použijete stejné názvy vlastností.
typy Azure.Compute.Batch Entity rozhraní REST API
BatchJob Získání informací o úloze
BatchJobSchedule Získání informací o plánu úloh
BatchNode Získání informací o uzlu
BatchPool Získání informací o fondu
BatchTask Získání informací o úkolu

Příklad: Vytvoření řetězce filtru

Pokud chcete vytvořit řetězec filtru pro parametr metody filter seznamu, vyhledejte odpovídající stránku rozhraní REST API. Výběrové vlastnosti a jejich podporované operátory jsou v první tabulce s více řádky. Pokud chcete například načíst všechny úkoly, jejichž ukončovací kód byl nenulový, zkontrolujte seznam úkolů přidružených k úloze pro příslušný řetězec vlastnosti a povolené operátory:

Vlastnost Povolené operace Typ
executionInfo/exitCode eq, ge, gt, le , lt Int

Související řetězec filtru je:

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

Příklad: Sestavte výběrový řetězec

Chcete-li sestavit řetězec select, najděte odpovídající stránku rozhraní REST API pro entitu, kterou uvádíte. Výběrové vlastnosti a jejich podporované operátory jsou v první tabulce s více řádky. Pokud například chcete načíst pouze ID a příkazový řádek pro každý úkol v seznamu, zaškrtněte políčko Získat informace o úkolu:

Vlastnost Typ Poznámky
id String The ID of the task.
commandLine String The command line of the task.

Související výběrový řetězec je:

id, commandLine

Ukázky kódu

Efektivní seznamové dotazy

Ukázkový projekt EfficientListQueries ukazuje, jak efektivní dotazování seznamu ovlivňuje výkon aplikace. Tato konzolová aplikace jazyka C# vytvoří a přidá do úlohy velký počet úkolů. Poté aplikace několikrát zavolá metodu BatchClient.GetTasks a předá různé hodnoty parametrů filter, select a expand, aby se měnilo množství vracených dat. Tato ukázka vytvoří výstup podobný tomuto:

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

Příklad ukazuje, že můžete výrazně snížit dobu odezvy dotazu omezením vlastností a počtu vrácených položek. Tento a další ukázkové projekty najdete v úložišti azure-batch-samples na GitHubu.

Knihovna BatchMetrics

Následující ukázkový projekt BatchMetrics ukazuje, jak efektivně monitorovat průběh úloh služby Azure Batch pomocí rozhraní API služby Batch.

Tato ukázka zahrnuje projekt knihovny tříd .NET, který můžete začlenit do vlastních projektů. K dispozici je také jednoduchý program příkazového řádku pro cvičení a předvedení použití knihovny.

Ukázková aplikace v projektu ukazuje tyto operace:

  • Výběr konkrétních atributů pro stažení jenom požadovaných vlastností
  • Filtrování časů přechodu stavu pro stahování pouze změn od posledního dotazu

Například následující metoda se zobrazí v knihovně BatchMetrics. Vrátí uspořádanou n-tici obsahující řetězce select a filter, které určují, že se mají získat pouze vlastnosti id a state u dotazovaných entit a že se mají vrátit pouze entity, jejichž stav se od hodnoty zadané parametrem DateTime změnil.

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

Další kroky

  • Last updated on