Lekérdezések létrehozása a Batch-erőforrások hatékony listázásához

  • Cikk

A legtöbb Azure Batch alkalmazás figyeli vagy más műveleteket végez, amelyek lekérdezik a Batch szolgáltatást. Az ilyen lista lekérdezések gyakran rendszeres időközönként történnek. Ha például egy feladat várólistára helyezett tevékenységeit szeretné ellenőrizni, a feladat minden tevékenységéről adatokat kell lekérnie. A Batch szolgáltatás által a lekérdezésekhez visszaadott adatok mennyiségének csökkentése javítja az alkalmazás teljesítményét. Ez a cikk bemutatja, hogyan hozhat létre és hajthat végre ilyen lekérdezéseket hatékonyan. A Batch .NET-kódtár segítségével szűrt lekérdezéseket hozhat létre Batch-feladatokhoz, feladatokhoz, számítási csomópontokhoz és más erőforrásokhoz.

Megjegyzés

A Batch szolgáltatás API-támogatást nyújt a feladatok tevékenységeinek megszámlálására és a Számítási csomópontok Megszámlálására a Batch-készletben. A Feladatszám és a Listakészlet csomópontszámánaklekérése művelet meghívható lista lekérdezés helyett. Ezek a hatékonyabb műveletek azonban korlátozottabb információkat adnak vissza, amelyek esetleg nem naprakészek. További információ: Tevékenységek és számítási csomópontok számlálása állapot szerint.

Részletességi szint megadása

Egy éles Batch-alkalmazásban több ezer entitás, például feladatok, tevékenységek és számítási csomópontok lehetnek. Az erőforrásokkal kapcsolatos minden lekérdezés esetében potenciálisan nagy mennyiségű adat kerül a Batch szolgáltatásból az alkalmazásba. Korlátozza, hogy a lekérdezés hány elemet és milyen információt ad vissza a teljesítmény javítása érdekében.

Ez a Batch .NET API-kódrészlet felsorolja a feladathoz társított összes feladatot, valamint az egyes tevékenységek összes tulajdonságát.

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

Részletességi szint alkalmazása a lekérdezésre az információk hatékonyabb listázásához. Adjon meg egy ODATADetailLevel objektumot a JobOperations.ListTasks metódusnak . Ez a kódrészlet csak a befejezett tevékenységek azonosító- és parancssori és számítási csomópontinformációs tulajdonságait adja vissza.

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

Ebben a példában, ha több ezer feladat van a feladatban, a második lekérdezés eredményei általában gyorsabban lesznek visszaadva, mint az első lekérdezésből. Az elemek Batch .NET API-val való listázásakor történő használatáról ODATADetailLevel a Hatékony lekérdezés a Batch .NET-ben című szakaszban talál további információt.

Fontos

Határozottan javasoljuk, hogy mindig adjon meg egy ODATADetailLevel objektumot a .NET API-listahívásokhoz az alkalmazás maximális hatékonysága és teljesítménye érdekében. A részletességi szint megadásával csökkentheti a Batch szolgáltatás válaszideét, javíthatja a hálózat kihasználtságát, és minimalizálhatja az ügyfélalkalmazások memóriahasználatát.

Lekérdezési sztringek használata

A Batch .NET és a Batch REST API-k használatával csökkentheti a lekérdezés által visszaadott elemek számát, valamint azt, hogy a lekérdezés mennyi adatot ad vissza az egyes elemekhez. A lekérdezés szűkítéséhez három lekérdezési sztringtípus használható: $filter, $select és $expand.

A Batch .NET API-hoz lásd az ODATADetailLevel Osztály tulajdonságait. Tekintse át a Hatékony lekérdezés a Batch .NET-ben című szakaszt is.

A Batch REST API-val kapcsolatban tekintse meg a Batch REST API referenciáját. Keresse meg a lekérdezni kívánt erőforrás listareferenciáját . Ezután tekintse át az URI-paraméterek szakaszt a , $selectés $expandrészleteiért$filter. Lásd például a Készlet – Lista URI-paramétereit. Azt is megtudhatja , hogyan végezhet hatékony Batch-lekérdezéseket az Azure CLI-vel.

Megjegyzés

A három lekérdezési sztringtípus bármelyikének létrehozásakor meg kell győződnie arról, hogy a tulajdonságnevek és a kis- és nagybetűk megegyeznek a REST API-elem megfelelőivel. Ha például a .NET CloudTask osztályt használja, az Állapot helyett az állapotot kell megadnia, annak ellenére, hogy a .NET tulajdonsága CloudTask.State. További információ: A .NET és a REST API-k közötti tulajdonságleképezések.

Szűrő

A $filter kifejezési sztring csökkenti a visszaadott elemek számát. Listázhatja például egy feladat futó tevékenységeit, vagy csak a tevékenységek futtatására kész számítási csomópontokat.

Ez a sztring egy vagy több kifejezésből áll, egy tulajdonságnévből, operátorból és értékből álló kifejezéssel. A megadható tulajdonságok a lekérdezett entitástípusokra vonatkoznak, valamint az egyes tulajdonságokhoz támogatott operátorokra. Több kifejezés kombinálható a logikai operátorok and és ora használatával.

Ez a példa csak a futó renderelési feladatokat sorolja fel: (state eq 'running') and startswith(id, 'renderTask').

Válassza ezt:

A $select kifejezési sztring korlátozza az egyes elemekhez visszaadott tulajdonságértékeket. Meg kell adnia a vesszővel tagolt tulajdonságnevek listáját, és a rendszer csak ezeket a tulajdonságértékeket adja vissza a lekérdezés eredményeiben szereplő elemekhez. A lekérdezni kívánt entitástípus bármelyik tulajdonságát megadhatja.

Ez a példa azt határozza meg, hogy minden tevékenységhez csak három tulajdonságértéket kell visszaadni: id, state, stateTransitionTime.

Kibontás

A $expand kifejezési sztring csökkenti a bizonyos információk beszerzéséhez szükséges API-hívások számát. Ezzel a sztringgel több információt kaphat az egyes elemekről egyetlen API-hívással. Ez a módszer az API-hívások csökkentésével segít a teljesítmény javításában. Használjon sztringet $expand az entitások listájának lekérése és az egyes listaelemek adatainak lekérése helyett.

A -hez hasonlóan azt is szabályozza, $select$expand hogy bizonyos adatok szerepeljenek-e a lista lekérdezési eredményeiben. Ha minden tulajdonság megadása kötelező, és nincs megadva választó sztring, $expand statisztikai adatok lekéréséhez kell használni. Ha egy kijelölési sztringet használ a tulajdonságok egy részhalmazának lekéréséhez, akkor stats meg lehet adni a kijelölési sztringben, és $expand nem kell megadni.

A sztring támogatott felhasználási területei közé tartoznak a feladatok, a feladatütemezések, a tevékenységek és a készletek listázása. A sztring jelenleg csak a statisztikai adatokat támogatja.

Ez a példa azt határozza meg, hogy a lista minden eleméhez statisztikai adatokat kell visszaadni: stats.

A sztringek szűrésére, kijelölésére és kibontára vonatkozó szabályok

  • Győződjön meg arról, hogy a tulajdonságok nevei a szűrőben, a kijelölésben és a sztringek kibontásakor ugyanúgy jelennek meg, mint a Batch REST API-ban. Ez a szabály akkor is érvényes, ha a Batch .NET-et vagy a többi Batch SDK-t használja.
  • Minden tulajdonságnév megkülönbözteti a kis- és nagybetűket, de a tulajdonságértékek nem különböztetik meg a kis- és nagybetűket.
  • A dátum/idő sztringek két formátum egyikét tartalmazhatják, és meg kell előznie a formátumot.DateTime
    • Példa W3C-DTF formátumra: creationTime gt DateTime'2011-05-08T08:49:37Z'
    • Példa RFC 1123 formátumra: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
  • A logikai sztringek vagy true .false
  • Ha érvénytelen tulajdonság vagy operátor van megadva, 400 (Bad Request) hiba történik.

Hatékony lekérdezés a Batch .NET-ben

A Batch .NET API-ban az ODATADetailLevel osztály szűrőt biztosít, kiválaszt és kibont sztringeket a műveletek listázásához. Az ODataDetailLevel osztály három nyilvános karakterlánc-tulajdonsággal rendelkezik. Ezeket a tulajdonságokat megadhatja a konstruktorban, vagy beállíthatja közvetlenül az objektumon. Ezután adja át az ODataDetailLevel objektumot paraméterként a különböző listaműveleteknek, például a ListPools, a ListJobs és a ListTasks műveletnek.

Az alábbi kódrészlet a Batch .NET API-val kérdezi le hatékonyan a Batch szolgáltatást egy adott készlet statisztikái alapján. A Batch-felhasználó teszt- és éles készletekkel is rendelkezik. A tesztkészlet azonosítói "teszt" előtaggal, az éles készlet azonosítói pedig "prod" előtaggal vannak ellátva. A myBatchClient a BatchClient osztály megfelelően inicializált példánya.

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

Tipp

A Select és a Expand záradékokkal konfigurált ODATADetailLevel példánya a megfelelő Get metódusoknak is átadható, például a PoolOperations.GetPool metódusnak a visszaadott adatok mennyiségének korlátozásához.

Batch REST –.NET API-leképezések

A szűrési, kiválasztási és kibontó sztringek tulajdonságneveinek a REST API-megfelelőiknek kell tükrözniük mind a név, mind a kis- és nagybetűk esetében. Az alábbi táblázatok a .NET és a REST API megfelelői közötti leképezéseket tartalmazzák.

Szűrési sztringek leképezése

  • .NET-listametódusok: Az oszlopban található .NET API-metódusok mindegyike elfogad egy ODATADetailLevel objektumot paraméterként.
  • REST-listakérések: Az oszlopban felsorolt MINDEN REST API-lap tartalmaz egy táblázatot, amely a szűrősztringekben engedélyezett tulajdonságokat és műveleteket tartalmazza. Ezeket a tulajdonságneveket és műveleteket használhatja ODATADetailLevel.FilterClause sztring létrehozásakor.
.NET-lista metódusai REST-listakérések
CertificateOperations.ListCertificates A fiókokban lévő tanúsítványok listázása
CloudTask.ListNodeFiles A tevékenységhez társított fájlok listázása
JobOperations.ListJobPreparationAndReleaseTaskStatus Egy feladat feladat-előkészítési és feladatkiadási feladatainak állapotának listázása
JobOperations.ListJobs A fiókban lévő feladatok listázása
JobOperations.ListNodeFiles Csomópont fájljainak listázása
JobOperations.ListTasks A feladathoz társított tevékenységek listázása
JobScheduleOperations.ListJobSchedules Feladatütemezések listázása egy fiókban
JobScheduleOperations.ListJobs A feladatütemezéshez társított feladatok listázása
PoolOperations.ListComputeNodes A készletben lévő számítási csomópontok listázása
PoolOperations.ListPools A fiókok készleteinek listázása

A kijelölt sztringek leképezései

  • Batch .NET-típusok: Batch .NET API-típusok.
  • REST API-entitások: Az oszlop minden oldala tartalmaz egy vagy több táblát, amelyek a típus REST API-tulajdonságneveit tartalmazzák. Ezek a tulajdonságnevek a kijelölt sztringek létrehozásakor használatosak. Ugyanezeket a tulajdonságneveket használja odataDetailLevel.SelectClause sztring létrehozásakor.
Batch .NET-típusok REST API-entitások
Tanúsítvány Tanúsítvány adatainak lekérése
CloudJob Feladatokkal kapcsolatos információk lekérése
CloudJobSchedule A feladatütemezéssel kapcsolatos információk lekérése
ComputeNode Csomópont adatainak lekérése
CloudPool Készletre vonatkozó információk lekérése
CloudTask Tevékenység adatainak lekérése

Példa: szűrősztring létrehozása

Az ODATADetailLevel.FilterClause szűrősztringjének létrehozásához keresse meg a megfelelő REST API-oldalt. A választható tulajdonságok és a támogatott operátorok az első többsoros táblázatban találhatók. Ha például le szeretné kérni az összes olyan tevékenységet, amelynek a kilépési kódja nem volt érvényes, jelölje be a Feladathoz társított tevékenységek listázása az alkalmazható tulajdonságsztringhez és az engedélyezett operátorokhoz című szakaszt:

Tulajdonság Engedélyezett műveletek Típus
executionInfo/exitCode eq, ge, gt, le , lt Int

A kapcsolódó szűrősztring a következő:

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

Példa: válasszon sztringet

AZ ODATADetailLevel.SelectClause létrehozásához keresse meg a listázandó entitáshoz tartozó REST API-oldalt. A választható tulajdonságok és a támogatott operátorok az első többsoros táblázatban találhatók. Ha például csak az azonosítót és a parancssort szeretné lekérni a listában szereplő egyes tevékenységekhez, ellenőrizze a Tevékenység adatainak lekérése című témakört:

Tulajdonság Típus Jegyzetek
id String The ID of the task.
commandLine String The command line of the task.

A kapcsolódó kijelölési sztring a következő:

id, commandLine

Kódminták

Hatékony listázó lekérdezések

Az EfficientListQueries mintaprojekt bemutatja, hogy a listalekérdezés mennyire befolyásolja az alkalmazás teljesítményét. Ez a C#-konzolalkalmazás sok feladatot hoz létre és ad hozzá egy feladathoz. Ezután az alkalmazás több hívást kezdeményez a JobOperations.ListTasks metódushoz, és átadja az ODATADetailLevel objektumokat. Ezek az objektumok különböző tulajdonságértékekkel vannak konfigurálva, hogy eltérjenek a visszaadandó adatok mennyisége. Ez a minta a következőhöz hasonló kimenetet hoz létre:

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

A példa azt mutatja, hogy a visszaadott tulajdonságok és elemek számának korlátozásával jelentősen csökkentheti a lekérdezési válaszidőt. Ezt és más mintaprojekteket a GitHub azure-batch-samples adattárában találja.

BatchMetrics-kódtár

Az alábbi BatchMetrics-mintaprojekt bemutatja, hogyan figyelheti hatékonyan Azure Batch feladat előrehaladását a Batch API használatával.

Ez a minta egy .NET-osztálytárprojektet tartalmaz, amelyet beépíthet a saját projektjeibe. A kódtár használatát egy egyszerű parancssori program is bemutatja.

A projekten belüli mintaalkalmazás a következő műveleteket mutatja be:

  • Adott attribútumok kiválasztása csak a szükséges tulajdonságok letöltéséhez
  • Szűrés az állapotáttúllépési időkre, hogy csak a legutóbbi lekérdezés óta történt módosításokat töltse le

Az alábbi metódus például megjelenik a BatchMetrics kódtárban. Egy ODATADetailLevel értéket ad vissza, amely azt határozza meg, hogy csak a id lekérdezett entitások és state tulajdonságok legyenek lekérve. Azt is meghatározza, hogy csak azokat az entitásokat kell visszaadni, amelyeknek az állapota megváltozott a megadott DateTime paraméter óta.

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

Következő lépések