Creare query per elencare le risorse di Batch in modo efficiente
La maggior parte delle applicazioni Azure Batch esegue il monitoraggio o altre operazioni che eseguono query sul servizio Batch. Tali query di elenco vengono spesso eseguite a intervalli regolari. Ad esempio, prima di poter verificare la presenza di attività in coda in un processo, è necessario ottenere dati su ogni attività in tale processo. La riduzione della quantità di dati restituiti dal servizio Batch per le query migliora le prestazioni dell'applicazione. Questo articolo illustra come creare ed eseguire tali query in modo efficiente. È possibile creare query filtrate per processi, attività, nodi di calcolo e altre risorse di Batch con la libreria Batch .NET .
Nota
Il servizio Batch fornisce il supporto api per gli scenari comuni di conteggio delle attività in un processo e il conteggio dei nodi di calcolo nel pool di Batch. È possibile chiamare le operazioni Get Task Counts e List Pool Node Counts invece di usare una query di elenco. Tuttavia, queste operazioni più efficienti restituiscono informazioni più limitate che potrebbero non essere aggiornate. Per altre informazioni, vedere Contare le attività e i nodi di calcolo in base allo stato.
Specificare un livello di dettaglio
In un'applicazione Batch di produzione possono essere presenti migliaia di entità, ad esempio processi, attività e nodi di calcolo. Per ogni query eseguita sulle risorse, una quantità di dati potenzialmente elevata passa dal servizio Batch all'applicazione. Limitare il numero di elementi e le informazioni restituite dalla query per migliorare le prestazioni.
Questo frammento di codice dell'API Batch .NET elenca tutte le attività associate a un processo, insieme a tutte le proprietà di ogni attività.
// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
batchClient.JobOperations.ListTasks("job-001");
Applicare un livello di dettaglio alla query per elencare le informazioni in modo più efficiente. Fornire un oggetto ODATADetailLevel al metodo JobOperations.ListTasks . Questo frammento restituisce solo le proprietà ID, riga di comando e nodo di calcolo delle attività completate.
// 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);
In questo scenario di esempio, se sono presenti migliaia di attività nel processo, i risultati della seconda query vengono in genere restituiti più rapidamente rispetto alla prima query. Per altre informazioni sull'uso ODATADetailLevel di quando si elencano elementi con l'API Batch .NET, vedere la sezione Esecuzione efficiente di query in Batch .NET.
Importante
È consigliabile fornire sempre un oggetto all'elenco ODATADetailLevel di API .NET per ottenere la massima efficienza e prestazioni dell'applicazione. Specificando un livello di dettaglio è possibile ridurre i tempi di risposta del servizio Batch, migliorare l'utilizzo della rete e ridurre l'utilizzo di memoria da parte delle applicazioni client.
Usare stringhe di query
È possibile usare le API REST batch .NET e Batch per ridurre il numero di elementi restituiti da una query e la quantità di informazioni restituite dalla query per ogni elemento. Esistono tre tipi di stringa di query che è possibile usare per restringere la query: $filter, $select e $expand.
Per l'API Batch .NET, vedere le proprietà della classe ODATADetailLevel. Vedere anche la sezione Esecuzione efficiente di query in Batch .NET.
Per l'API REST di Batch, vedere le informazioni di riferimento sull'API REST di Batch. Trovare il riferimento elenco per la risorsa su cui eseguire la query. Esaminare quindi la sezione Parametri URI per informazioni dettagliate su $filter, $selecte $expand. Ad esempio, vedere i parametri URI per Pool - List. Vedere anche come eseguire query Batch efficienti con l'interfaccia della riga di comando di Azure.
Nota
Quando si costruisce uno dei tre tipi di stringa di query, è necessario assicurarsi che i nomi delle proprietà e le maiuscole/minuscole corrispondano a quelli delle controparti dell'elemento DELL'API REST. Ad esempio, quando si usa la classe CloudTask .NET, è necessario specificare state invece di State, anche se la proprietà .NET è CloudTask.State. Per altre informazioni, vedere mapping delle proprietà tra le API REST e .NET.
Filtro
La $filter stringa dell'espressione riduce il numero di elementi restituiti. Ad esempio, è possibile elencare solo le attività in esecuzione per un processo o elencare solo i nodi di calcolo pronti per l'esecuzione delle attività.
Questa stringa è costituita da una o più espressioni, con un'espressione costituita da un nome di proprietà, un operatore e un valore. Le proprietà che è possibile immettere sono specifiche di ogni tipo di entità su cui viene eseguita la query, come lo sono gli operatori supportati per ogni proprietà. È possibile combinare più espressioni usando gli operatori logici and e or.
In questo esempio vengono elencate solo le attività di rendering in esecuzione: (state eq 'running') and startswith(id, 'renderTask').
Seleziona
La stringa dell'espressione $select limita i valori delle proprietà restituiti per ogni elemento. Si specifica un elenco di nomi di proprietà delimitati da virgole e vengono restituiti solo i valori delle proprietà per gli elementi nei risultati della query. È possibile specificare una delle proprietà per il tipo di entità su cui si sta eseguendo una query.
In questo esempio viene specificato che per ogni attività devono essere restituiti solo tre valori di proprietà: id, state, stateTransitionTime.
Espandi
La $expand stringa di espressione riduce il numero di chiamate API necessarie per ottenere determinate informazioni. È possibile usare questa stringa per ottenere altre informazioni su ogni elemento con una singola chiamata API. Questo metodo consente di migliorare le prestazioni riducendo le chiamate API. Usare una $expand stringa invece di ottenere l'elenco di entità e richiedere informazioni su ogni elemento di elenco.
Analogamente a $select, $expand controlla se determinati dati sono inclusi nei risultati della query di elenco. Quando tutte le proprietà sono obbligatorie e non viene specificata alcuna stringa di selezione, $expand è necessario usare per ottenere informazioni sulle statistiche. Se viene usata una stringa di selezione per ottenere un subset di proprietà, stats è possibile specificare nella stringa di selezione e $expand non è necessario specificare.
Gli usi supportati di questa stringa includono l'elenco di processi, pianificazioni dei processi, attività e pool. Attualmente, la stringa supporta solo le informazioni sulle statistiche.
Questo esempio specifica che le informazioni sulle statistiche devono essere restituite per ogni elemento dell'elenco: stats.
Regole per le stringhe di filtro, selezione ed espansione
- Assicurarsi che i nomi delle proprietà nel filtro, selezionare ed espandere le stringhe vengano visualizzate come fanno nell'API REST di Batch. Questa regola si applica anche quando si usa Batch .NET o uno degli altri SDK di Batch.
- Per tutti i nomi di proprietà viene fatta distinzione tra maiuscole e minuscole, al contrario di quanto avviene per i valori delle proprietà.
- Le stringhe relative a data/ora possono essere indicate in uno dei due formati seguenti e devono essere precedute da
DateTime.- Esempio di formato W3C-DTF:
creationTime gt DateTime'2011-05-08T08:49:37Z' - Esempio di formato RFC 1123:
creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
- Esempio di formato W3C-DTF:
- Le stringhe booleane sono
trueofalse. - Se si specifica una proprietà o un operatore non valido, viene generato un errore
400 (Bad Request).
Esecuzione efficiente di query in Batch .NET
Nell'API Batch .NET la classe ODATADetailLevel fornisce filtri, selezione ed espansione di stringhe per le operazioni di elenco. La ODataDetailLevel classe ha tre proprietà di stringa pubblica. È possibile specificare queste proprietà nel costruttore o impostare le proprietà direttamente sull'oggetto . Passare quindi l'oggetto ODataDetailLevel come parametro alle varie operazioni di elenco, ad esempio ListPools, ListJobs e ListTasks.
- ODATADetailLevel.FilterClause: limita il numero di elementi restituiti.
- ODATADetailLevel.SelectClause: specificare i valori delle proprietà restituiti con ogni elemento.
- ODATADetailLevel.ExpandClause: recupera i dati per tutti gli elementi in una singola chiamata API anziché chiamate separate per ogni elemento.
Il frammento di codice seguente usa l'API Batch .NET per eseguire query sul servizio Batch in modo efficiente per le statistiche di un set specifico di pool. L'utente di Batch dispone sia di pool di test che di produzione. Gli ID del pool di test sono preceduti da "test", mentre quelli del pool di produzione sono preceduti da "prod". myBatchClient è un'istanza inizializzata correttamente della classe 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();
Suggerimento
È anche possibile passare un'istanza di ODATADetailLevel configurata con le clausole Select ed Expand ai metodi Get appropriati, ad esempio PoolOperations.GetPool, per limitare la quantità di dati restituiti.
Mapping di API Batch REST a API .NET
I nomi delle proprietà nelle stringhe di filtro, selezione ed espansione devono riflettere le rispettive controparti dell'API REST, sia a livello di nome che di lettere maiuscole/minuscole. Le tabelle seguenti forniscono i mapping tra l'API .NET e le relative controparti dell'API REST.
Mapping per le stringhe di filtro
- Metodi list .NET: ogni metodo dell'API .NET in questa colonna accetta un oggetto ODATADetailLevel come parametro.
- Richieste di elenco REST: ogni pagina dell'API REST elencata in questa colonna contiene una tabella con le proprietà e le operazioni consentite nelle stringhe di filtro. È possibile usare questi nomi di proprietà e operazioni quando si crea una stringa ODATADetailLevel.FilterClause .
Mapping per le stringhe di selezione
- Tipi di Batch .NET: tipi di API Batch .NET.
- Entità di API REST: ogni pagina di questa colonna contiene una o più tabelle che indicano i nomi delle proprietà dell'API REST per il tipo. Questi nomi di proprietà vengono usati per la costruzione di stringhe di selezione . Questi stessi nomi di proprietà vengono usati quando si crea una stringa ODATADetailLevel.SelectClause .
Esempio: costruire una stringa di filtro
Per costruire una stringa di filtro per ODATADetailLevel.FilterClause, trovare la pagina dell'API REST corrispondente. Le proprietà selezionabili e i relativi operatori supportati si trovano nella prima tabella a più righe. Ad esempio, per recuperare tutte le attività il cui codice di uscita era diverso da zero, selezionare Elencare le attività associate a un processo per la stringa di proprietà applicabile e gli operatori consentiti:
| Proprietà | Operazioni consentite | Type |
|---|---|---|
executionInfo/exitCode |
eq, ge, gt, le , lt |
Int |
La stringa di filtro correlata è:
(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)
Esempio: costruire una stringa di selezione
Per costruire ODATADetailLevel.SelectClause, trovare la pagina dell'API REST corrispondente per l'entità elencata. Le proprietà selezionabili e i relativi operatori supportati si trovano nella prima tabella a più righe. Ad esempio, per recuperare solo l'ID e la riga di comando per ogni attività in un elenco, vedere Ottenere informazioni su un'attività:
| Proprietà | Type | Note |
|---|---|---|
id |
String |
The ID of the task. |
commandLine |
String |
The command line of the task. |
La stringa di selezione correlata è:
id, commandLine
Esempi di codice
Query di elenco efficienti
Il progetto di esempio EfficientListQueries mostra in che modo l'esecuzione efficiente delle query sugli elenchi influisce sulle prestazioni dell'applicazione. Questa applicazione console C# crea e aggiunge un numero elevato di attività a un processo. L'applicazione effettua quindi più chiamate al metodo JobOperations.ListTasks e passa gli oggetti ODATADetailLevel . Questi oggetti sono configurati con valori di proprietà diversi per variare la quantità di dati da restituire. Questo esempio produce un output simile al seguente:
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...
L'esempio mostra che è possibile ridurre notevolmente i tempi di risposta delle query limitando le proprietà e il numero di elementi restituiti. Questo e altri progetti di esempio sono disponibili nel repository azure-batch-samples in GitHub.
Libreria BatchMetrics
Il progetto di esempio BatchMetrics seguente illustra come monitorare in modo efficiente lo stato dei processi di Azure Batch usando l'API Batch.
Questo esempio include un progetto di libreria di classi .NET, che è possibile incorporare nei propri progetti. È disponibile anche un semplice programma da riga di comando per eseguire l'esercizio e dimostrare l'uso della libreria.
L'applicazione di esempio all'interno del progetto illustra queste operazioni:
- Selezione di attributi specifici per scaricare solo le proprietà necessarie
- Filtro in base ai tempi di transizione dello stato per scaricare solo le modifiche dall'ultima query
Ad esempio, il metodo seguente è presente nella libreria BatchMetrics. Restituisce un elemento ODATADetailLevel che specifica che dovranno essere ottenute solo le proprietà id e state per le entità sulle quali viene eseguita una query. Specifica anche che dovranno essere restituite solo le entità il cui stato è stato modificato dopo il parametro DateTime specificato.
internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
return new ODATADetailLevel(
selectClause: "id, state",
filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
);
}
Passaggi successivi
- Ottimizzare l'utilizzo delle risorse di calcolo di Azure Batch con attività del nodo simultanee. Alcuni tipi di carichi di lavoro possono trarre vantaggio dall'esecuzione di attività parallele in nodi di calcolo più grandi (ma meno). Vedere lo scenario di esempio nell'articolo per informazioni dettagliate su questo scenario.
- Monitorare le soluzioni Batch conteggiando le attività e i nodi in base allo stato