Creare query per elencare le risorse di Batch in modo efficiente

La maggior parte delle applicazioni di Azure Batch effettua il monitoraggio o altre operazioni che interagiscono con il servizio Batch tramite query. 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 Batch, attività, nodi di calcolo e altre risorse con la libreria Azure.Compute.Batch.

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 Azure.Compute.Batch elenca tutte le attività associate a un processo batch, insieme a tutte le proprietà di ciascuna attività.

// Get a collection of all of the tasks and all of their properties for job-001
AsyncPageable<BatchTask> allTasks = batchClient.GetTasksAsync("job-001");

Applicare un livello di dettaglio alla query per elencare le informazioni in modo più efficiente. Passare le stringhe filter, select e expand al metodo BatchClient.GetTasks. Questo frammento restituisce solo le proprietà ID, riga di comando e nodo di calcolo delle attività completate.

// Specify filter and select strings to return only a subset of tasks and their properties.
AsyncPageable<BatchTask> completedTasks = batchClient.GetTasksAsync(
    jobId: "job-001",
    filter: "state eq 'completed'",
    select: new[] { "id", "commandLine", "nodeInfo" });

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 dei parametri /filter, select e expand con il Azure. API Compute.Batch, vedere la sezione Efficient querying in Azure. Compute.Batch.

Importante

Consigliamo vivamente di specificare sempre le stringhe filter, select e, se appropriato, expand nelle chiamate di elenco dell'API .NET per garantire la massima efficienza e le migliori 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 il Azure. Compute.Batch e Batch REST API 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 Azure.Compute.Batch, consulta il riferimento di BatchClient per il metodo list i cui parametri filter, select e expand vuoi usare. Esaminare anche la sezione Efficient querying in Azure. Compute.Batch.

Per l'API REST di Batch, vedere il riferimento dell'API REST di Batch. Trova il riferimento della Lista per la risorsa che vuoi interrogare. 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 lettere maiuscole/minuscole corrispondano a quelli degli elementi dell'API REST. Ad esempio, quando si usa la classe .NET BatchTask è necessario specificare state anziché State, anche se la proprietà .NET è BatchTask.State. Per ulteriori informazioni, vedere le mappature delle proprietà tra le API .NET e REST.

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 lavori, programmazioni dei lavori, 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à nelle stringhe di filtro, selezione ed espansione appaiano come nell'API Batch REST. Questa regola si applica anche quando si usa Azure. Compute.Batch 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'
  • 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 Azure.Compute.Batch

Nel Azure. Api Compute.Batch, i metodi di elenco in BatchClient accettano direttamente i parametri filter, select e expand:

  • filter: limita il numero di elementi restituiti.
  • select: specificare i valori delle proprietà restituiti con ogni elemento.
  • expand: recupera i dati per tutti gli elementi in una singola chiamata API anziché chiamate separate per ogni elemento.

Il frammento di codice seguente usa il Azure. API Compute.Batch 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 .

// Pull only the "test" pools, and limit the data crossing the wire by selecting only
// the Id and Statistics properties. Use expand="stats" so the .NET API pulls the
// statistics for the BatchPools 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 (BatchPool.Statistics).
List<BatchPool> testPools = new List<BatchPool>();
await foreach (BatchPool pool in myBatchClient.GetPoolsAsync(
    filter: "startswith(id, 'test')",
    select: new[] { "id", "stats" },
    expand: new[] { "stats" }))
{
    testPools.Add(pool);
}

Suggerimento

Gli stessi filterparametri , selecte expand possono anche essere passati ai metodi Get appropriati, ad esempio BatchClient.GetPool, per limitare la quantità di dati restituiti.

Mappature di API REST Batch a API .NET

I nomi delle proprietà nelle stringhe di filtro, selezione ed espansione devono rispecchiare le rispettive controparti dell'API REST, per nome e uso delle maiuscole. Le tabelle seguenti forniscono i mapping tra l'API .NET e le relative controparti dell'API REST.

Mapping per le stringhe di filtro

  • .NET list methods: ognuno dei metodi API .NET in questa colonna accetta filter, select e expand parametri stringa.
  • 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 filter stringa.
Metodi delle liste .NET Richieste REST elenco
BatchAccountResource.GetBatchAccountCertificates Elenca i certificati di un account
BatchClient.GetTaskFiles Elencare i file associati a un'attività
BatchClient.GetJobPreparationAndReleaseTaskStatuses Elencare lo stato della preparazione e le attività di rilascio per un processo
BatchClient.GetJobs Elenca i lavori in un account
BatchClient.GetNodeFiles Elencare i file in un nodo
BatchClient.GetTasks Elencare le attività associate a un processo
BatchClient.GetJobSchedules Elenca le pianificazioni dei lavori in un account
BatchClient.GetJobsFromSchedule Elenca le attività associate a una pianificazione attività
BatchClient.GetNodes Elencare i nodi di calcolo in un pool
BatchClient.GetPools Elencare i pool in un account

Mapping per le stringhe di selezione

  • Tipi di Azure.Compute.Batch: tipi dell'API Azure.Compute.Batch.
  • 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 select stringa.
Tipi di Azure.Compute.Batch Entità di API REST
BatchJob Ottenere informazioni su un lavoro
BatchJobSchedule Ottenere informazioni su una pianificazione di un lavoro
BatchNode Ottenere informazioni su un nodo
BatchPool Ottenere informazioni su un pool
BatchTask Ottenere informazioni su un'attività

Esempio: costruire una stringa di filtro

Per costruire una stringa di filtro per il parametro di un metodo list filter , 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 Tipo
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 una select stringa, 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à Tipo 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 grande numero di attività a un job. L'applicazione esegue quindi più chiamate al metodo BatchClient.GetTasks e passa valori diversi filterdi parametri , selecte expand 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 una tupla contenente le stringhe select e filter, che specificano che per le entità interrogate devono essere ottenute solo le proprietà id e state e che devono essere restituite solo le entità il cui stato è cambiato a partire dal parametro DateTime specificato.

return (
    Filter: string.Format("stateTransitionTime gt DateTime'{0:o}'", time),
    Select: new[] { "id", "state" });

Passaggi successivi

  • Last updated on