Delen via

Query's maken om Batch-resources efficiënt weer te geven

  • Artikel

De meeste Azure Batch-toepassingen voeren bewaking uit of andere bewerkingen die query's uitvoeren op de Batch-service. Dergelijke lijstquery's worden vaak regelmatig uitgevoerd. Voordat u bijvoorbeeld kunt controleren op taken in de wachtrij in een taak, moet u gegevens over elke taak in die taak ophalen. Het verminderen van de hoeveelheid gegevens die de Batch-service retourneert voor query's verbetert de prestaties van uw toepassing. In dit artikel wordt uitgelegd hoe u dergelijke query's op een efficiënte manier kunt maken en uitvoeren. 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 Node Counts aanroepen in plaats van een lijstquery te gebruiken. Deze efficiëntere bewerkingen retourneren echter beperktere informatie die mogelijk niet up-to-date is. Zie Aantal taken en rekenknooppunten per status voor meer informatie.

Een detailniveau opgeven

Er kunnen duizenden entiteiten zijn, zoals taken, taken en rekenknooppunten in een Batch-productietoepassing. Voor elke query die u maakt over de resources, gaat een mogelijk grote hoeveelheid gegevens van de Batch-service naar uw toepassing. Beperk hoeveel items en welke gegevens uw query retourneert om de prestaties te verbeteren.

Dit Codefragment voor de 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 gegevens efficiënter weer te geven. Geef een ODATADetailLevel-object op voor de methode JobOperations.ListTasks . Dit codefragment retourneert alleen de id-, opdrachtregel- en rekenknooppuntinformatie-eigenschappen 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 er in dit voorbeeldscenario duizenden taken in de taak staan, worden de resultaten van de tweede query doorgaans sneller geretourneerd dan uit de eerste query. Zie de sectie Efficiënt query's uitvoeren in Batch .NET voor meer informatie over het gebruik ODATADetailLevel van items met de Batch .NET-API.

Belangrijk

We raden u ten zeerste aan om altijd een ODATADetailLevel object op te geven voor uw .NET API-lijstaanroepen voor maximale efficiëntie en prestaties van uw toepassing. Door een detailniveau op te geven, kunt u helpen de reactietijden van de Batch-service te verlagen, het netwerkgebruik te verbeteren en het geheugengebruik door clienttoepassingen te minimaliseren.

Queryreeksen gebruiken

U kunt de Batch .NET - en Batch REST API's gebruiken om te beperken hoeveel items een query retourneert en hoeveel informatie de query voor elk item retourneert. Er zijn drie queryreekstypen die u kunt gebruiken om uw query te verfijnen: $filter, $select en $expand.

Zie de eigenschappen van de ODATADetailLevel-klasse voor de Batch .NET-API. Bekijk ook de sectie Efficiënt query's uitvoeren in Batch .NET.

Zie de Batch REST API-naslaginformatie voor de Batch REST API. Zoek de lijstreferentie voor de resource die u wilt opvragen. Controleer vervolgens de sectie URI-parameters voor meer informatie over $filter, $selecten $expand. Zie bijvoorbeeld de URI-parameters voor Pool - List. Bekijk ook hoe u efficiënte Batch-query's kunt maken met de Azure CLI.

Notitie

Bij het maken van een van de drie queryreekstypen moet u ervoor zorgen dat de eigenschapsnamen en hoofdletters overeenkomen met die van de rest API-elementen. Wanneer u bijvoorbeeld met de klasse .NET CloudTask werkt, 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, net als de operators die worden ondersteund voor elke eigenschap. Meerdere expressies kunnen worden gecombineerd met behulp van de logische operatoren and en or.

In dit voorbeeld worden alleen de actieve rendertaken weergegeven: (state eq 'running') and startswith(id, 'renderTask').

Select

De $select expressiereeks beperkt de eigenschapswaarden die worden geretourneerd voor elk item. U geeft een lijst met door komma's gescheiden eigenschapsnamen op en alleen die eigenschapswaarden worden geretourneerd voor de items in de queryresultaten. U kunt een van de eigenschappen opgeven voor het entiteitstype dat u wilt opvragen.

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.

$select$expand Hiermee bepaalt u of bepaalde gegevens zijn opgenomen in de lijstqueryresultaten. Wanneer alle eigenschappen vereist zijn en er geen tekenreeks is opgegeven, $expand moet u worden gebruikt om statistiekengegevens op te halen. Als een selectietekenreeks wordt gebruikt om een subset eigenschappen te verkrijgen, stats kunt u deze opgeven in de selectietekenreeks en $expand hoeft u deze niet op te geven.

Ondersteunde toepassingen van deze tekenreeks zijn het weergeven van taken, taakplanningen, taken en pools. Op dit moment ondersteunt de tekenreeks alleen statistische informatie.

In dit voorbeeld wordt aangegeven dat statistiekengegevens moeten worden geretourneerd voor elk item in de lijst: stats.

Regels voor filteren, selecteren en uitvouwen van tekenreeksen

  • Zorg ervoor dat de namen van eigenschappen in het filter, de selectie en het uitvouwen van tekenreeksen worden weergegeven zoals in de Batch REST API. Deze regel is ook 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'
  • Booleaanse tekenreeksen zijn true of false.
  • 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 ODATADetailLevel-klasse tekenreeksen filteren, selecteren en uitvouwen om bewerkingen weer te geven. De ODataDetailLevel klasse heeft drie eigenschappen voor openbare tekenreeksen. U kunt deze eigenschappen in de constructor opgeven of de eigenschappen rechtstreeks op het object instellen. Geef vervolgens het ODataDetailLevel object als parameter door aan de verschillende lijstbewerkingen, zoals ListPools, ListJobs en ListTasks.

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 productiegroepen. 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 BatchClient-klasse .

// 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 het filter, de selectie en het uitvouwen van tekenreeksen moeten overeenkomen met hun REST API-tegenhangers, zowel in naam als hoofdletters. De onderstaande tabellen bevatten toewijzingen tussen de tegenhangers van .NET en REST API.

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 filterreeksen. U kunt deze eigenschapsnamen en bewerkingen gebruiken wanneer u een ODATADetailLevel.FilterClause-tekenreeks maakt.
.NET-lijstmethoden REST-lijstaanvragen
CertificateOperations.ListCertificates De certificaten in een account weergeven
CloudTask.ListNodeFiles De bestanden weergeven die zijn gekoppeld aan een taak
JobOperations.ListJobPreparationAndReleaseTaskStatus De status van de jobvoorbereidings- en jobreleasetaken voor een taak weergeven
JobOperations.ListJobs De taken in een account weergeven
JobOperations.ListNodeFiles De bestanden op een knooppunt weergeven
JobOperations.ListTasks De taken weergeven die zijn gekoppeld aan een taak
JobScheduleOperations.ListJobSchedules De taakplanningen weergeven in een account
JobScheduleOperations.ListJobs De taken weergeven die zijn gekoppeld aan een taakplanning
PoolOperations.ListComputeNodes De rekenknooppunten in een pool weergeven
PoolOperations.ListPools De pools in een account weergeven

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 wanneer u tekenreeksen maakt. U gebruikt dezelfde eigenschapsnamen wanneer u een ODATADetailLevel.SelectClause-tekenreeks maakt.
Batch .NET-typen REST API-entiteiten
Certificaat Informatie over een certificaat ophalen
CloudJob Informatie over een taak ophalen
CloudJobSchedule Informatie over een taakplanning ophalen
ComputeNode Informatie over een knooppunt ophalen
CloudPool Informatie over een pool ophalen
CloudTask Informatie over een taak ophalen

Voorbeeld: een filtertekenreeks maken

Als u een filtertekenreeks 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 voor de toepasselijke eigenschapstekenreeks en toegestane operators:

Eigenschappen Toegestane bewerkingen Type
executionInfo/exitCode eq, ge, gt, le , lt Int

De gerelateerde filtertekenreeks is:

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

Voorbeeld: een select-tekenreeks maken

Als u ODATADetailLevel.SelectClause wilt maken, zoekt u de bijbehorende REST API-pagina voor de entiteit die u opgeeft. 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, schakelt u Informatie over een taak ophalen in:

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

In het voorbeeldproject EfficientListQueries ziet u hoe efficiënte lijstquery's van invloed zijn op de prestaties van toepassingen. Deze C#-consoletoepassing maakt en voegt een groot aantal taken toe aan een taak. Vervolgens voert de toepassing meerdere aanroepen uit naar de methode JobOperations.ListTasks en geeft de ODATADetailLevel-objecten door. Deze objecten worden geconfigureerd met verschillende eigenschapswaarden om de hoeveelheid gegevens te variëren die moet worden geretourneerd. In dit voorbeeld wordt uitvoer geproduceerd 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

In het volgende BatchMetrics-voorbeeldproject ziet u hoe u de voortgang van azure Batch-taken efficiënt kunt bewaken met behulp van de Batch-API.

Dit voorbeeld bevat een .NET-klassebibliotheekproject dat u in uw eigen projecten kunt opnemen. Er is ook een eenvoudig opdrachtregelprogramma om te oefenen en het gebruik van de bibliotheek 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 te downloaden sinds de laatste query

De volgende methode wordt bijvoorbeeld weergegeven in de BatchMetrics-bibliotheek. Het retourneert een ODATADetailLevel die aangeeft dat alleen de id en state eigenschappen moeten worden verkregen voor de entiteiten waarop een query wordt uitgevoerd. Het geeft ook aan dat alleen entiteiten waarvan de status is gewijzigd sinds de opgegeven DateTime parameter moet 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