Skapa frågor för att lista Batch-resurser effektivt

  • Artikel

De flesta Azure Batch program utför övervakning eller andra åtgärder som kör frågor mot Batch-tjänsten. Sådana listfrågor inträffar ofta med jämna mellanrum. Innan du till exempel kan söka efter köade aktiviteter i ett jobb måste du hämta data om varje aktivitet i jobbet. Om du minskar mängden data som Batch-tjänsten returnerar för frågor förbättras programmets prestanda. Den här artikeln beskriver hur du skapar och kör sådana frågor på ett effektivt sätt. Du kan skapa filtrerade frågor för Batch-jobb, uppgifter, beräkningsnoder och andra resurser med Batch .NET-biblioteket .

Anteckning

Batch-tjänsten ger API-stöd för vanliga scenarier för att räkna uppgifter i ett jobb och räkna beräkningsnoder i Batch-pool. Du kan anropa åtgärderna Get Task Counts och List Pool Node Counts i stället för att använda en listfråga. Dessa mer effektiva åtgärder returnerar dock mer begränsad information som kanske inte är uppdaterad. Mer information finns i Räkna uppgifter och beräkningsnoder efter tillstånd.

Ange en detaljnivå

Det kan finnas tusentals entiteter som jobb, uppgifter och beräkningsnoder i ett Batch-produktionsprogram. För varje fråga du gör om resurserna går en potentiellt stor mängd data från Batch-tjänsten till ditt program. Begränsa hur många objekt och vilken information frågan returnerar för att förbättra prestandan.

Det här Batch .NET API-kodfragmentet visar varje uppgift som är associerad med ett jobb, tillsammans med alla egenskaper för varje aktivitet.

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

Tillämpa en detaljnivå på din fråga för att visa information mer effektivt. Ange ett ODATADetailLevel-objekt till metoden JobOperations.ListTasks . Det här kodfragmentet returnerar endast informationsegenskaperna ID, kommandorad och beräkningsnod för slutförda aktiviteter.

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

Om det finns tusentals uppgifter i jobbet i det här exempelscenariot returneras vanligtvis resultatet från den andra frågan snabbare än från den första frågan. Mer information om hur du använder ODATADetailLevel när du listar objekt med Batch .NET API finns i avsnittet Effektiv frågekörning i Batch .NET.

Viktigt

Vi rekommenderar starkt att du alltid anger ett ODATADetailLevel objekt i din .NET API-lista som kräver maximal effektivitet och prestanda för ditt program. Genom att ange en detaljnivå kan du minska svarstiderna för Batch-tjänsten, förbättra nätverksanvändningen och minimera minnesanvändningen för klientprogram.

Använda frågesträngar

Du kan använda Rest-API:erna för Batch .NET och Batch för att minska hur många objekt som en fråga returnerar och hur mycket information frågan returnerar för varje objekt. Det finns tre typer av frågesträngar som du kan använda för att begränsa frågan: $filter, $select och $expand.

Information om Batch .NET API finns i ODATADetailLevel Class-egenskaperna. Läs även avsnittet Effektiv frågekörning i Batch .NET.

För Rest-API:et för Batch läser du rest-API-referensen för Batch. Leta upp listreferensen för den resurs som du vill köra frågor mot. Granska sedan avsnittet URI-parametrar för mer information om $filter, $selectoch $expand. Se till exempel URI-parametrarna för Pool – lista. Se även hur du gör effektiva Batch-frågor med Azure CLI.

Anteckning

När du skapar någon av de tre frågesträngstyperna måste du se till att egenskapsnamnen och skiftläget matchar deras REST API-elementmotsvarigheter. När du till exempel arbetar med klassen .NET CloudTask måste du ange tillstånd i stället för Delstat, även om .NET-egenskapen är CloudTask.State. Mer information finns i egenskapsmappningarna mellan .NET- och REST-API:erna.

Filtrera

Uttryckssträngen $filter minskar antalet objekt som returneras. Du kan till exempel bara visa en lista över aktiviteter som körs för ett jobb eller bara visa en lista över beräkningsnoder som är redo att köra aktiviteter.

Den här strängen består av ett eller flera uttryck, med ett uttryck som består av ett egenskapsnamn, en operator och ett värde. De egenskaper som kan anges är specifika för varje entitetstyp som du frågar efter, liksom de operatorer som stöds för varje egenskap. Flera uttryck kan kombineras med hjälp av de logiska operatorerna and och or.

I det här exemplet visas endast de renderingsuppgifter som körs: (state eq 'running') and startswith(id, 'renderTask').

Välj

Uttryckssträngen $select begränsar de egenskapsvärden som returneras för varje objekt. Du anger en lista med kommaavgränsade egenskapsnamn och endast dessa egenskapsvärden returneras för objekten i frågeresultatet. Du kan ange någon av egenskaperna för den entitetstyp som du frågar efter.

Det här exemplet anger att endast tre egenskapsvärden ska returneras för varje aktivitet: id, state, stateTransitionTime.

Visa

Uttryckssträngen $expand minskar antalet API-anrop som krävs för att hämta viss information. Du kan använda den här strängen för att få mer information om varje objekt med ett enda API-anrop. Den här metoden hjälper till att förbättra prestanda genom att minska API-anrop. Använd en $expand sträng i stället för att hämta listan över entiteter och begära information om varje listobjekt.

På liknande $select$expand sätt styr om vissa data ingår i listfrågeresultat. När alla egenskaper krävs och ingen select-sträng har angetts $expandmåste användas för att hämta statistikinformation. Om en select-sträng används för att hämta en delmängd av egenskaperna kan du stats ange den i den valda strängen och $expand behöver inte anges.

Användning av den här strängen som stöds är bland annat listning av jobb, jobbscheman, uppgifter och pooler. För närvarande stöder strängen endast statistikinformation.

Det här exemplet anger att statistikinformation ska returneras för varje objekt i listan: stats.

Regler för att filtrera, välja och expandera strängar

  • Kontrollera att egenskapernas namn i filtret, väljer och expanderar strängar visas som de gör i Batch REST API . Den här regeln gäller även när du använder Batch .NET eller någon av de andra Batch-SDK:erna.
  • Alla egenskapsnamn är skiftlägeskänsliga, men egenskapsvärden är skiftlägeskänsliga.
  • Datum-/tidssträngar kan vara ett av två format och måste föregås av DateTime.
    • W3C-DTF-formatexempel: creationTime gt DateTime'2011-05-08T08:49:37Z'
    • RFC 1123-formatexempel: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
  • Booleska strängar är antingen true eller false.
  • Om en ogiltig egenskap eller operator har angetts resulterar ett 400 (Bad Request) fel.

Effektiv frågekörning i Batch .NET

I Batch .NET-API :et innehåller klassen ODATADetailLevelfilter, select och expandering av strängar för liståtgärder. Klassen ODataDetailLevel har tre egenskaper för offentliga strängar. Du kan ange dessa egenskaper i konstruktorn eller ange egenskaperna direkt på objektet. Skicka sedan objektet ODataDetailLevel som en parameter till de olika liståtgärderna, till exempel ListPools, ListJobs och ListTasks.

Följande kodfragment använder Batch .NET API för att effektivt fråga Batch-tjänsten efter statistik för en specifik uppsättning pooler. Batch-användaren har både test- och produktionspooler. Testpoolens ID:t har prefixet "test" och produktionspoolens ID:t har prefixet "prod". myBatchClient är en korrekt initierad instans av klassen 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();

Tips

En instans av ODATADetailLevel som har konfigurerats med Select- och Expand-satser kan också skickas till lämpliga Get-metoder, till exempel PoolOperations.GetPool, för att begränsa mängden data som returneras.

Batch REST till .NET API-mappningar

Egenskapsnamn i filter, select och expanderingssträngar måste återspegla deras REST API-motsvarigheter, både i namn och skiftläge. Tabellerna nedan innehåller mappningar mellan .NET- och REST API-motsvarigheterna.

Mappningar för filtersträngar

  • .NET-listmetoder: Var och en av .NET API-metoderna i den här kolumnen accepterar ett ODATADetailLevel-objekt som en parameter.
  • REST-listbegäranden: Varje REST API-sida som anges i den här kolumnen innehåller en tabell med de egenskaper och åtgärder som tillåts i filtersträngar. Du kan använda dessa egenskapsnamn och åtgärder när du skapar en ODATADetailLevel.FilterClause-sträng .
.NET-listmetoder REST-listbegäranden
CertificateOperations.ListCertificates Visa en lista över certifikaten i ett konto
CloudTask.ListNodeFiles Visa en lista över de filer som är associerade med en aktivitet
JobOperations.ListJobPreparationAndReleaseTaskStatus Ange status för jobbförberedelse- och jobbpubliceringsuppgifterna för ett jobb
JobOperations.ListJobs Visa en lista över jobben i ett konto
JobOperations.ListNodeFiles Visa en lista över filerna på en nod
JobOperations.ListTasks Visa en lista över aktiviteter som är associerade med ett jobb
JobScheduleOperations.ListJobSchedules Visa en lista över jobbscheman i ett konto
JobScheduleOperations.ListJobs Visa en lista över jobb som är associerade med ett jobbschema
PoolOperations.ListComputeNodes Visa en lista över beräkningsnoderna i en pool
PoolOperations.ListPools Visa en lista över poolerna i ett konto

Mappningar för utvalda strängar

  • Batch .NET-typer: Batch .NET API-typer.
  • REST API-entiteter: Varje sida i den här kolumnen innehåller en eller flera tabeller som visar REST API-egenskapsnamnen för typen. Dessa egenskapsnamn används när du skapar utvalda strängar. Du använder samma egenskapsnamn när du skapar en ODATADetailLevel.SelectClause-sträng .
Batch .NET-typer REST API-entiteter
Certifikat Hämta information om ett certifikat
CloudJob Hämta information om ett jobb
CloudJobSchedule Hämta information om ett jobbschema
ComputeNode Hämta information om en nod
CloudPool Hämta information om en pool
CloudTask Hämta information om en uppgift

Exempel: skapa en filtersträng

Om du vill skapa en filtersträng för ODATADetailLevel.FilterClause letar du upp motsvarande REST API-sida. Valbara egenskaper och deras operatorer som stöds finns i den första tabellen med flera rader. Om du till exempel vill hämta alla aktiviteter vars slutkod inte var noll markerar du Lista aktiviteterna som är associerade med ett jobb för den tillämpliga egenskapssträngen och tillåtna operatorer:

Egenskap Tillåtna åtgärder Typ
executionInfo/exitCode eq, ge, gt, le , lt Int

Den relaterade filtersträngen är:

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

Exempel: skapa en select-sträng

Om du vill skapa ODATADetailLevel.SelectClause hittar du motsvarande REST API-sida för den entitet som du listar. Valbara egenskaper och deras operatorer som stöds finns i den första tabellen med flera rader. Om du till exempel bara vill hämta ID:t och kommandoraden för varje uppgift i en lista, markerar du Hämta information om en uppgift:

Egenskap Typ Kommentarer
id String The ID of the task.
commandLine String The command line of the task.

Den relaterade select-strängen är:

id, commandLine

Kodexempel

Effektiv lista: frågor

Exempelprojektet EfficientListQueries visar hur effektiva listfrågor påverkar programmets prestanda. Det här C#-konsolprogrammet skapar och lägger till ett stort antal uppgifter i ett jobb. Sedan gör programmet flera anrop till metoden JobOperations.ListTasks och skickar ODATADetailLevel-objekt . Dessa objekt konfigureras med olika egenskapsvärden för att variera mängden data som ska returneras. Det här exemplet genererar utdata som liknar:

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

Exemplet visar att du kan sänka svarstiderna för frågor avsevärt genom att begränsa egenskaperna och antalet objekt som returneras. Du hittar det här och andra exempelprojekt på lagringsplatsen azure-batch-samples på GitHub.

BatchMetrics-bibliotek

Följande BatchMetrics-exempelprojekt visar hur du effektivt övervakar Azure Batch jobbförloppet med batch-API:et.

Det här exemplet innehåller ett .NET-klassbiblioteksprojekt som du kan införliva i dina egna projekt. Det finns också ett enkelt kommandoradsprogram för att träna och demonstrera användningen av biblioteket.

Exempelprogrammet i projektet visar följande åtgärder:

  • Välja specifika attribut för att endast ladda ned de egenskaper som du behöver
  • Filtrering av tillståndsövergångstider för att endast ladda ned ändringar sedan den senaste frågan

Följande metod visas till exempel i BatchMetrics-biblioteket. Den returnerar en ODATADetailLevel som anger att endast id egenskaperna och state ska hämtas för de entiteter som efterfrågas. Det anger också att endast entiteter vars tillstånd har ändrats sedan den angivna DateTime parametern ska returneras.

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

Nästa steg