Query's maken om Batch-resources efficiënt weer te geven
De meeste Azure Batch toepassingen voeren bewakingsbewerkingen of andere bewerkingen uit die een query uitvoeren op de Batch-service. Dergelijke lijstquery's worden vaak met regelmatige tussenpozen uitgevoerd. Voordat u bijvoorbeeld kunt controleren op taken in de wachtrij in een taak, moet u gegevens over elke taak in die taak ophalen. Door de hoeveelheid gegevens te verminderen die de Batch-service retourneert voor query's, worden de prestaties van uw toepassing verbeterd. In dit artikel wordt uitgelegd hoe u dergelijke query's op een efficiënte manier maakt en uitvoert. U kunt gefilterde query's maken voor Batch-taken, -taken, -rekenknooppunten en andere resources met de Batch .NET-bibliotheek .
Notitie
De Batch-service biedt API-ondersteuning voor de algemene scenario's voor het tellen van taken in een taak en het tellen van rekenknooppunten in Batch-pool. U kunt de bewerkingen Get Task Counts en List Pool NodeS aanroepen in plaats van een lijstquery te gebruiken. Deze efficiëntere bewerkingen retourneren echter beperktere informatie die mogelijk niet up-to-date is. Zie Taken en rekenknooppunten tellen op status voor meer informatie.
Een detailniveau opgeven
Een Batch-productietoepassing kan duizenden entiteiten, zoals taken, taken en rekenknooppunten, bevatten. Voor elke query die u over de resources maakt, gaat er een potentieel grote hoeveelheid gegevens van de Batch-service naar uw toepassing. Beperk het aantal items en de informatie die uw query retourneert om de prestaties te verbeteren.
Dit Codefragment batch .NET API bevat elke taak die is gekoppeld aan een taak, samen met alle eigenschappen van elke taak.
// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
batchClient.JobOperations.ListTasks("job-001");
Pas een detailniveau toe op uw query om informatie efficiënter weer te geven. Geef een ODATADetailLevel-object op voor de methode JobOperations.ListTasks . Dit codefragment retourneert alleen de eigenschappen id, opdrachtregel en rekenknooppuntgegevens van voltooide taken.
// 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);
Als de taak in dit voorbeeldscenario duizenden taken bevat, worden de resultaten van de tweede query doorgaans sneller geretourneerd dan uit de eerste query. Zie de sectie Efficiënte query's uitvoeren in Batch .NET voor meer informatie over het gebruik ODATADetailLevel wanneer u items weergeeft met de Batch .NET-API.
Belangrijk
We raden u ten zeerste aan om altijd een ODATADetailLevel object op te geven in uw .NET API-lijst voor maximale efficiëntie en prestaties van uw toepassing. Door een detailniveau op te geven, kunt u de reactietijden van de Batch-service verlagen, het netwerkgebruik verbeteren en het geheugengebruik door clienttoepassingen minimaliseren.
Queryreeksen gebruiken
U kunt de Api's Batch .NET en Batch REST gebruiken om het aantal items dat een query retourneert te verminderen en hoeveel informatie de query voor elk item retourneert. Er zijn drie querytekenreekstypen die u kunt gebruiken om uw query te verfijnen: $filter, $select en $expand.
Zie de eigenschappen van ODATADetailLevel Class voor de Batch .NET-API. Bekijk ook de sectie Efficiënte query's uitvoeren in Batch .NET.
Zie de Batch REST API-naslaginformatie voor de Batch REST API. Zoek de lijstreferentie voor de resource waarop u een query wilt uitvoeren. Bekijk vervolgens de sectie URI-parameters voor meer informatie over $filter, $selecten $expand. Zie bijvoorbeeld de URI-parameters voor Pool - List. Zie ook hoe u efficiënte Batch-query's maakt met de Azure CLI.
Notitie
Wanneer u een van de drie querytekenreekstypen maakt, moet u ervoor zorgen dat de eigenschapsnamen en hoofdletters overeenkomen met die van de tegenhangers van de REST API-elementen. Als u bijvoorbeeld werkt met de klasse .NET CloudTask , moet u de status opgeven in plaats van State, ook al is de eigenschap .NET CloudTask.State. Zie de eigenschapstoewijzingen tussen de .NET- en REST-API's voor meer informatie.
Filter
De $filter expressietekenreeks vermindert het aantal items dat wordt geretourneerd. U kunt bijvoorbeeld alleen de actieve taken voor een taak weergeven of alleen rekenknooppunten weergeven die klaar zijn om taken uit te voeren.
Deze tekenreeks bestaat uit een of meer expressies, met een expressie die bestaat uit een eigenschapsnaam, operator en waarde. De eigenschappen die kunnen worden opgegeven, zijn specifiek voor elk entiteitstype dat u opvraagt, evenals de operators die voor elke eigenschap worden ondersteund. Meerdere expressies kunnen worden gecombineerd met behulp van de logische operators and en or.
In dit voorbeeld worden alleen de actieve rendertaken vermeld: (state eq 'running') and startswith(id, 'renderTask').
Selecteer
De $select expressietekenreeks beperkt de eigenschapswaarden die voor elk item worden geretourneerd. U geeft een lijst met door komma's gescheiden eigenschapsnamen op en alleen deze eigenschapswaarden worden geretourneerd voor de items in de queryresultaten. U kunt een van de eigenschappen opgeven voor het entiteitstype waarop u een query uitvoert.
In dit voorbeeld wordt aangegeven dat er slechts drie eigenschapswaarden moeten worden geretourneerd voor elke taak: id, state, stateTransitionTime.
Uitvouwen
De $expand expressietekenreeks vermindert het aantal API-aanroepen dat nodig is om bepaalde informatie te verkrijgen. U kunt deze tekenreeks gebruiken om meer informatie over elk item te verkrijgen met één API-aanroep. Deze methode helpt de prestaties te verbeteren door API-aanroepen te verminderen. Gebruik een $expand tekenreeks in plaats van de lijst met entiteiten op te halen en informatie op te vragen over elk lijstitem.
$selectNet als bij bepaalt $expand u of bepaalde gegevens worden opgenomen in de resultaten van de lijstquery. Wanneer alle eigenschappen vereist zijn en er geen selectietekenreeks is opgegeven, $expandmoet worden gebruikt om statistische informatie op te halen. Als een select-tekenreeks wordt gebruikt om een subset van eigenschappen op te halen, stats kan worden opgegeven in de selectietekenreeks en $expand hoeft deze niet te worden opgegeven.
Ondersteunde toepassingen van deze tekenreeks zijn onder andere het weergeven van taken, taakplanningen, taken en pools. Op dit moment ondersteunt de tekenreeks alleen statistische gegevens.
In dit voorbeeld wordt aangegeven dat statistische gegevens moeten worden geretourneerd voor elk item in de lijst: stats.
Regels voor het filteren, selecteren en uitvouwen van tekenreeksen
- Zorg ervoor dat de namen van eigenschappen in het filter, selecteren en uitvouwen van tekenreeksen worden weergegeven zoals in de Batch REST API. Deze regel is zelfs van toepassing wanneer u Batch .NET of een van de andere Batch-SDK's gebruikt.
- Alle eigenschapsnamen zijn hoofdlettergevoelig, maar eigenschapswaarden zijn niet hoofdlettergevoelig.
- Datum-/tijdtekenreeksen kunnen een van de twee notaties zijn en moeten worden voorafgegaan door
DateTime.- Voorbeeld van W3C-DTF-indeling:
creationTime gt DateTime'2011-05-08T08:49:37Z' - Voorbeeld van RFC 1123-indeling:
creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
- Voorbeeld van W3C-DTF-indeling:
- Booleaanse tekenreeksen zijn of
truefalse. - Als er een ongeldige eigenschap of operator is opgegeven, treedt er een
400 (Bad Request)fout op.
Efficiënte query's uitvoeren in Batch .NET
In de Batch .NET-API biedt de klasse ODATADetailLevelfilter, selectie en uitvouwen van tekenreeksen voor lijstbewerkingen. De ODataDetailLevel klasse heeft drie openbare tekenreekseigenschappen. U kunt deze eigenschappen opgeven in de constructor of de eigenschappen rechtstreeks op het object instellen. Geef het ODataDetailLevel object vervolgens door als parameter aan de verschillende lijstbewerkingen, zoals ListPools, ListJobs en ListTasks.
- ODATADetailLevel.FilterClause: beperk het aantal items dat wordt geretourneerd.
- ODATADetailLevel.SelectClause: geef op welke eigenschapswaarden voor elk item worden geretourneerd.
- ODATADetailLevel.ExpandClause: gegevens ophalen voor alle items in één API-aanroep in plaats van afzonderlijke aanroepen voor elk item.
In het volgende codefragment wordt de Batch .NET-API gebruikt om efficiënt een query uit te voeren op de Batch-service voor de statistieken van een specifieke set pools. De Batch-gebruiker heeft zowel test- als productiepools. De testgroep-id's worden voorafgegaan door 'test' en de productiegroep-id's worden voorafgegaan door 'prod'. myBatchClient is een correct geïnitialiseerd exemplaar van de klasse 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
Een exemplaar van ODATADetailLevel dat is geconfigureerd met select- en expand-componenten kan ook worden doorgegeven aan de juiste Get-methoden, zoals PoolOperations.GetPool, om de hoeveelheid gegevens te beperken die wordt geretourneerd.
Batch REST naar .NET API-toewijzingen
Eigenschapsnamen in tekenreeksen voor filteren, selecteren en uitvouwen moeten overeenkomen met hun REST API-tegenhangers, zowel in naam als in hoofdletters. De onderstaande tabellen bevatten toewijzingen tussen de .NET- en REST API-tegenhangers.
Toewijzingen voor filtertekenreeksen
- .NET-lijstmethoden: elk van de .NET API-methoden in deze kolom accepteert een ODATADetailLevel-object als parameter.
- REST-lijstaanvragen: Elke REST API-pagina die in deze kolom wordt vermeld, bevat een tabel met de eigenschappen en bewerkingen die zijn toegestaan in filtertekenreeksen. U kunt deze eigenschapsnamen en bewerkingen gebruiken wanneer u een ODATADetailLevel.FilterClause-tekenreeks maakt.
Toewijzingen voor geselecteerde tekenreeksen
- Batch .NET-typen: Batch .NET API-typen.
- REST API-entiteiten: elke pagina in deze kolom bevat een of meer tabellen met de namen van de REST API-eigenschappen voor het type. Deze eigenschapsnamen worden gebruikt bij het maken van selectietekenreeksen. U gebruikt dezelfde eigenschapsnamen wanneer u een ODATADetailLevel.SelectClause-tekenreeks maakt.
Voorbeeld: een filtertekenreeks maken
Als u een filterreeks wilt maken voor ODATADetailLevel.FilterClause, zoekt u de bijbehorende REST API-pagina. Selecteerbare eigenschappen en de ondersteunde operators bevinden zich in de eerste tabel met meerdere rijen. Als u bijvoorbeeld alle taken wilt ophalen waarvan de afsluitcode niet nul is, schakelt u De taken weergeven die zijn gekoppeld aan een taak in voor de toepasselijke eigenschapstekenreeks en toegestane operators:
| Eigenschap | Bewerkingen toegestaan | Type |
|---|---|---|
executionInfo/exitCode |
eq, ge, gt, le , lt |
Int |
De gerelateerde filtertekenreeks is:
(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)
Voorbeeld: een selectietekenreeks maken
Als u ODATADetailLevel.SelectClause wilt maken, zoekt u de bijbehorende REST API-pagina voor de entiteit die u weer geeft. Selecteerbare eigenschappen en de ondersteunde operators bevinden zich in de eerste tabel met meerdere rijen. Als u bijvoorbeeld alleen de id en opdrachtregel voor elke taak in een lijst wilt ophalen, raadpleegt u Informatie over een taak ophalen:
| Eigenschap | Type | Opmerkingen |
|---|---|---|
id |
String |
The ID of the task. |
commandLine |
String |
The command line of the task. |
De gerelateerde selectietekenreeks is:
id, commandLine
Codevoorbeelden
Efficiënte lijstquery's
Het voorbeeldproject EfficientListQueries laat zien hoe efficiënte lijstquery's van invloed zijn op de prestaties van toepassingen. Deze C#-consoletoepassing maakt een groot aantal taken en voegt deze toe aan een taak. Vervolgens voert de toepassing meerdere aanroepen uit naar de methode JobOperations.ListTasks en worden ODATADetailLevel-objecten doorgegeven. Deze objecten worden geconfigureerd met verschillende eigenschapswaarden om de hoeveelheid gegevens te variëren die moet worden geretourneerd. Dit voorbeeld produceert uitvoer die vergelijkbaar is met:
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...
In het voorbeeld ziet u dat u de reactietijden van query's aanzienlijk kunt verlagen door de eigenschappen en het aantal geretourneerde items te beperken. U vindt deze en andere voorbeeldprojecten in de opslagplaats azure-batch-samples op GitHub.
BatchMetrics-bibliotheek
Het volgende BatchMetrics-voorbeeldproject laat zien hoe u de voortgang van Azure Batch taak efficiënt kunt bewaken met behulp van de Batch-API.
Dit voorbeeld bevat een .NET-klassebibliotheekproject, dat u kunt opnemen in uw eigen projecten. Er is ook een eenvoudig opdrachtregelprogramma om het gebruik van de bibliotheek te oefenen en te demonstreren.
De voorbeeldtoepassing in het project laat deze bewerkingen zien:
- Specifieke kenmerken selecteren om alleen de eigenschappen te downloaden die u nodig hebt
- Filteren op statusovergangstijden om alleen wijzigingen sinds de laatste query te downloaden
De volgende methode wordt bijvoorbeeld weergegeven in de bibliotheek BatchMetrics. Het retourneert een ODATADetailLevel dat aangeeft dat alleen de id eigenschappen en state moeten worden verkregen voor de entiteiten die worden opgevraagd. Het geeft ook aan dat alleen entiteiten waarvan de status is gewijzigd sinds de opgegeven DateTime parameter moeten worden geretourneerd.
internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
return new ODATADetailLevel(
selectClause: "id, state",
filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
);
}
Volgende stappen
- Maximaliseer Azure Batch gebruik van rekenresources met gelijktijdige knooppunttaken. Sommige typen workloads kunnen profiteren van het uitvoeren van parallelle taken op grotere (maar minder) rekenknooppunten. Bekijk het voorbeeldscenario in het artikel voor meer informatie over een dergelijk scenario.
- Batch-oplossingen bewaken door taken en knooppunten te tellen op status