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 spesso si verificano a intervalli regolari. Ad esempio, prima di poter controllare le attività in coda in un processo, è necessario ottenere dati su ogni attività del processo. Ridurre la 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 Batch, attività, nodi di calcolo e altre risorse con la libreria Batch .NET .

Specificare un livello di dettaglio

Esistono migliaia di entità come processi, attività e nodi di calcolo in un'applicazione Batch di produzione. Per ogni query eseguita sulle risorse, una quantità potenzialmente elevata di dati 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 .NET di Batch elenca ogni attività associata 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 nel processo sono presenti migliaia di attività, 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 gli elementi con l'API .NET batch, vedere la sezione Esecuzione di query efficienti in Batch .NET.

Usare stringhe di query

È possibile usare le API RESTbatch .NET e Batch per ridurre il numero di elementi restituiti da una query e la quantità di informazioni restituite dalla query per ogni elemento. Sono disponibili tre tipi di stringa di query che è possibile usare per restringere la query: $filter, $select e $expand.

Per l'API .NET batch, vedere le proprietà della classe ODATADetailLevel. Esaminare anche la sezione Esecuzione di query efficienti in Batch .NET.

Per l'API REST batch, vedere informazioni di riferimento sull'API REST batch. Trovare il riferimento elenco per la risorsa che si desidera eseguire una 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 rendere efficienti le query batch con l'interfaccia della riga di comando di Azure.

Filtra

La $filter stringa di 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').

Select

La $select stringa di espressione limita i valori delle proprietà restituiti per ogni elemento. Si specifica un elenco di nomi di proprietà separati da virgole e vengono restituiti solo i valori delle proprietà nei risultati della query. È possibile specificare una delle proprietà per il tipo di entità che 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.

Espandere

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 anziché ottenere l'elenco di entità e richiedere informazioni su ogni elemento di elenco.

Analogamente a $select, $expand controlla se alcuni dati sono inclusi nei risultati della query di elenco. Quando tutte le proprietà sono necessarie e non viene specificata alcuna stringa selezionata, $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 processi di elenco, pianificazioni di 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 e espandere le stringhe vengano visualizzate come fanno nell'API REST batch . Questa regola si applica anche quando si usa Batch .NET o uno degli altri SDK 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'
• Le stringhe booleane sono true o false.
• 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 .NET batch , la classe ODATADetailLevel fornisce filtri, selezionare ed espandere stringhe per elencare le operazioni. 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: limitare il numero di elementi restituiti.
• ODATADetailLevel.SelectClause: specificare i valori delle proprietà restituiti con ogni elemento.
• ODATADetailLevel.ExpandClause: recuperare 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 batch ha sia 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 corretta 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();

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 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 costruisce 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 costruisce 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:

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à che si sta elencando. 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à:

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 Azure Batch avanzamento del processo 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
• Applicazione di filtri 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 Azure Batch l'utilizzo delle risorse di calcolo con le attività simultanee dei nodi. 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 attività e nodi in base allo stato