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

  • Článek

Většina Azure Batch aplikací provede monitorování nebo jiné operace, které dotazují službu Batch. Takové dotazy na seznam se často provádějí v pravidelných intervalech. Abyste například mohli zkontrolovat úkoly zařazené do fronty v úloze, musíte získat data o všech úkolech 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 tyto dotazy efektivně vytvářet a spouštět. Pomocí knihovny Batch .NET můžete vytvářet filtrované dotazy pro úlohy, úkoly, výpočetní uzly a další prostředky služby Batch.

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. Operace Get Task Counts (Získat počty úkolů) a List Pool Counts (Výpis počtu uzlů fondu ) můžete místo použití dotazu na seznam volat. Tyto efektivnější operace ale vrací omezené informace, které nemusí být aktuální. Další informace najdete v tématu Počet úkolů a výpočetních uzlů podle stavu.

Určení úrovně podrobností

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

Tento fragment kódu rozhraní Api služby Batch pro .NET obsahuje seznam všech úkolů přidružených 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
IPagedEnumerable<CloudTask> allTasks =
    batchClient.JobOperations.ListTasks("job-001");

Použijte u dotazu úroveň podrobností, abyste mohli vypisovat informace efektivněji. Do metody JobOperations.ListTasks zadejte objekt ODATADetailLevel. Tento fragment kódu vrátí pouze vlastnosti informací o ID, příkazovém řádku a výpočetním uzlu dokončených úkolů.

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

V tomto ukázkovém scénáři platí, že pokud jsou v úloze tisíce úkolů, výsledky z druhého dotazu se obvykle vrátí rychleji než z prvního dotazu. Další informace o použití ODATADetailLevel při výpisu položek pomocí rozhraní Batch .NET API najdete v části Efektivní dotazování ve službě Batch .NET.

Důležité

Pro zajištění maximální efektivity a výkonu ODATADetailLevel vaší aplikace důrazně doporučujeme do seznamu volání rozhraní .NET API vždy zadat objekt. 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ů dotazů

Pomocí rozhraní Batch .NET a Batch REST API můžete snížit počet 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í Batch .NET API najdete ve vlastnostech třídy ODATADetailLevel. Projděte si také část Efektivní dotazování ve službě Batch .NET.

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. Pak si projděte část Parametry identifikátoru URI , kde najdete podrobnosti o parametrech $filter, $selecta $expand. Podívejte se například na parametry identifikátoru URI pro Fond – Seznam. Podívejte se také, jak provádět efektivní dotazy služby Batch pomocí Azure CLI.

Poznámka

Při vytváření libovolného ze tří typů řetězců dotazů musíte zajistit, aby se názvy vlastností a malá a malá písmena shodovaly s jejich protějšky elementů REST API. Například při práci s třídou .NET CloudTask musíte místo State zadat state, i když vlastnost .NET je CloudTask.State. Další informace najdete v tématu mapování vlastností mezi rozhraními .NET a REST API.

Filtrovat

Řetězec $filter výrazu snižuje počet vrácených položek. Můžete například zobrazit pouze spuštěné úkoly pro úlohu nebo pouze 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é je možné zadat, jsou specifické pro každý typ entity, na který se dotazujete, stejně jako operátory podporované pro každou vlastnost. Více výrazů je možné 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í. Pro typ entity, který dotazujete, můžete zadat libovolnou z vlastností.

Tento příklad určuje, že pro každou úlohu 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 jedním voláním rozhraní API. Tato metoda pomáhá zlepšit výkon tím, že snižuje počet volání rozhraní API. $expand Místo získání seznamu entit a vyžádání informací o jednotlivých položkách seznamu použijte řetězec.

Podobně jako nástroj $selecturčuje, $expand jestli se určitá data zahrnou do výsledků dotazu seznamu. Pokud jsou požadovány všechny vlastnosti a není zadán žádný řetězec výběru, $expandmusí se použít k získání informací o statistikách. Pokud se k získání podmnožiny vlastností používá řetězec výběru, stats je možné ho zadat ve vybraném řetězci a $expand není nutné ho zadávat.

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 statistické informace.

Tento příklad určuje, že se mají pro každou položku v seznamu vrátit statistické informace: stats.

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

  • Ujistěte se, že se názvy vlastností ve filtru, výběru a rozbalení řetězců zobrazují stejně jako v rozhraní Rest API služby Batch . Toto pravidlo platí i v případě, že používáte Batch .NET nebo některou z dalších sad SDK služby Batch.
  • Ve všech názvech vlastností se rozlišují malá a velká písmena, ale v hodnotách vlastností se nerozlišují malá a velká písmena.
  • Řetězce data a času můžou mít jeden 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í ve službě Batch .NET

V rozhraní Batch .NET API třída ODATADetailLevel poskytuje filtrování, výběr a rozbalení řetězců pro výpis operací. Třída ODataDetailLevel má tři vlastnosti veřejného řetězce. Tyto vlastnosti můžete zadat v konstruktoru nebo nastavit vlastnosti přímo u objektu. Pak předejte ODataDetailLevel objekt jako parametr různým operacím seznamu, jako jsou ListPools, ListJobs a ListTasks.

Následující fragment kódu používá rozhraní Batch .NET API k efektivnímu dotazování služby Batch na statistiku konkrétní sady fondů. Uživatel služby Batch má testovací i produkční fond. 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 .

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

Tip

Instance ODATADetailLevel nakonfigurovaná s klauzulemi Select a Expand lze také předat příslušným metodám Get, jako je PoolOperations.GetPool, aby se omezilo množství vrácených dat.

Mapování batch REST na .NET API

Názvy vlastností ve filtrech, výběrech a rozbalení řetězců musí odrážet jejich protějšky rozhraní REST API, a to jak v názvu, tak v malých a velkých písmenech. Následující tabulky poskytují mapování mezi protějšky rozhraní .NET a REST API.

Mapování pro řetězce filtru

  • Metody seznamu .NET: Každá z metod rozhraní .NET API v tomto sloupci přijímá jako parametr objekt ODATADetailLevel .
  • Požadavky na seznam REST: Každá stránka rozhraní REST API uvedená v tomto sloupci obsahuje tabulku s vlastnostmi a operacemi povolenými v řetězcích filtru. Tyto názvy vlastností a operace můžete použít při vytváření řetězce ODATADetailLevel.FilterClause .
Metody seznamu .NET Požadavky na seznam REST
CertificateOperations.ListCertificates Výpis certifikátů v účtu
CloudTask.ListNodeFiles Výpis souborů přidružených k úkolu
JobOperations.ListJobPreparationAndReleaseTaskStatus Výpis stavu úkolů přípravy a uvolnění úlohy pro úlohu
JobOperations.ListJobs Výpis úloh v účtu
JobOperations.ListNodeFiles Výpis souborů v uzlu
JobOperations.ListTasks Výpis úkolů přidružených k úloze
JobScheduleOperations.ListJobSchedules Výpis plánů úloh v účtu
JobScheduleOperations.ListJobs Výpis úloh přidružených k plánu úloh
PoolOperations.ListComputeNodes Výpis výpočetních uzlů ve fondu
PoolOperations.ListPools Výpis fondů v účtu

Mapování pro vybrané řetězce

  • Typy batch .NET: Typy rozhraní API batch .NET.
  • Entity rozhraní REST API: Každá stránka v tomto sloupci obsahuje jednu nebo více tabulek, které uvádějí názvy vlastností rozhraní 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í řetězce ODATADetailLevel.SelectClause se používají stejné názvy vlastností.
Typy batch .NET Entity rozhraní REST API
Certifikát Získání informací o certifikátu
CloudJob Získání informací o úloze
CloudJobSchedule Získání informací o plánu úloh
Výpočetní uzel Získání informací o uzlu
CloudPool Získání informací o fondu
CloudTask Získání informací o úkolu

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

Pokud chcete vytvořit řetězec filtru pro ODATADetailLevel.FilterClause, vyhledejte odpovídající stránku rozhraní REST API. Vybratelné vlastnosti a jejich podporované operátory jsou v první tabulce s více řádky. Pokud například chcete načíst všechny úkoly, jejichž ukončovací kód byl nenulový, zaškrtněte políčko 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: Vytvoření řetězce select

Pokud chcete vytvořit ODATADetailLevel.SelectClause, vyhledejte odpovídající stránku rozhraní REST API pro entitu, kterou vypisujete. Vybratelné vlastnosti a jejich podporované operátory jsou v první tabulce s více řádky. Pokud například chcete načíst jenom 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ódů

Efektivní seznamové dotazy

Ukázkový projekt EfficientListQueries ukazuje, jak efektivní dotazování na seznamy ovlivňuje výkon aplikace. Tato konzolová aplikace jazyka C# vytvoří a přidá do úlohy velký počet úloh. Pak aplikace provádí více volání JobOperations.ListTasks metoda a předává ODATADetailLevel objekty. Tyto objekty jsou nakonfigurovány s různými hodnotami vlastností, aby se střídá množství vrácených dat. Tato ukázka vytvoří výstup podobný následujícímu:

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 dotazů 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 Azure Batch pomocí rozhraní Batch API.

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 rámci projektu demonstruje tyto operace:

  • Výběr konkrétních atributů, aby se stáhly jenom vlastnosti, které potřebujete
  • Filtrování časů přechodu stavu ke stažení pouze změn od posledního dotazu

Například následující metoda se zobrazí v knihovně BatchMetrics. Vrátí ODATADetailLevel, který určuje, že pouze id vlastnosti a state by měly být získány pro entity, které jsou dotazovány. Určuje také, že by měly být vráceny pouze entity, jejichž stav se od zadaného DateTime parametru změnil.

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

Další kroky