Sdílet prostřednictvím

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

  • Článek

Většina aplikací Azure Batch monitoruje 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í knihovny Batch .NET můžete vytvářet filtrované dotazy pro úlohy, úlohy, výpočetní uzly a další prostředky.

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 dotazu seznamu můžete volat operace Získat počty úkolů a Počet uzlů fondu seznamů. 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 služby Batch .NET obsahuje seznam všech úloh 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");

Efektivnějším použitím úrovně podrobností na dotaz zobrazíte seznam informací. 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 úloh.

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

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í ODATADetailLevel při výpisu položek pomocí rozhraní API služby Batch .NET najdete v části Efektivní dotazování ve službě Batch .NET.

Důležité

Důrazně doporučujeme vždy zadat ODATADetailLevel objekt do seznamu rozhraní .NET API pro maximální efektivitu 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

Rozhraní REST API služby Batch .NET a Batch můžete použít ke snížení počtu položek, které dotaz vrátí, a množství informací, které dotaz vrátí 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 služby Batch .NET naleznete 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. Potom si v části Parametry identifikátoru URI projděte podrobnosti o $filterparametrech , $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 batch pomocí Azure CLI.

Poznámka:

Při vytváření některého ze tří typů řetězců dotazu je nutné zajistit, aby názvy vlastností a malá a velká písmena odpovídaly jejich protějškům elementů ROZHRANÍ REST API. Například při práci s .NET CloudTask třídy, musíte zadat stav místo State, i když je vlastnost .NET CloudTask.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. $expand Místo získání seznamu entit a vyžádání informací o jednotlivých položkách seznamu použijte řetězec.

$selectPodobně jako v ovládacích prvcích určuje, $expand jestli jsou určitá data zahrnutá do výsledků dotazu seznamu. Pokud jsou požadovány všechny vlastnosti a není zadán žádný výběrový řetězec, $expand je 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 filtr, výběr a rozbalení řetězců

  • Ujistěte se, že se názvy vlastností ve filtru zobrazují, vyberou a rozbalí řetězce tak, jak to dělají v rozhraní REST API služby Batch. Toto pravidlo platí i v případě, že používáte Batch .NET nebo jednu z dalších sad SDK služby Batch.
  • U všech názvů vlastností se rozlišují malá a velká písmena, ale hodnoty vlastností nerozlišují malá a velká písmena.
  • Ř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í ve službě Batch .NET

V rozhraní API služby Batch .NET poskytuje třída ODATADetailLevel filtr, 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 na 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í API služby Batch .NET k efektivnímu dotazování služby Batch na statistiku konkrétní sady fondů. Uživatel batch má testovací i produkční fondy. 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

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

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

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

Mapování řetězců filtru

  • Metody seznamu .NET: Každá z metod rozhraní .NET API v tomto sloupci přijímá objekt ODATADetailLevel jako parametr.
  • 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 a operace vlastností 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 Zobrazení seznamu souborů přidružených k úkolu
JobOperations.ListJobPreparationAndReleaseTaskStatus Výpis stavu úkolů přípravy úlohy a uvolnění úlohy pro úlohu
JobOperations.ListJobs Výpis úloh v účtu
JobOperations.ListNodeFiles Výpis souborů na 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 služby 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ů. Tyto stejné názvy vlastností použijete při vytváření řetězce ODATADetailLevel.SelectClause .
Typy Batch .NET Entity rozhraní REST API
Certifikát Získání informací o certifikátu
CloudOvá úloha Získání informací o úloze
CloudJobSchedule Získání informací o plánu úloh
ComputeNode 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

Chcete-li vytvořit řetězec filtru pro ODATADetailLevel.FilterClause, 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: Vytvoření řetězce select

Chcete-li vytvořit ODATADetailLevel.SelectClause, vyhledejte 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 Type Notes
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ů. Aplikace pak provede více volání JobOperations.ListTasks metoda a předá ODATADetailLevel objekty. Tyto objekty jsou nakonfigurovány s různými hodnotami vlastností, aby se liší množství dat, která se mají vrátit. 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í ODATADetailLevel, který určuje, že pouze id vlastnosti a state vlastnosti by měly být získány pro entity, které jsou dotazovány. Určuje také, že se mají vrátit 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