Esecuzione di query su tabelle ed entità

L'esecuzione di query su tabelle ed entità nel servizio tabelle richiede un'attenta creazione dell'URI della richiesta. Nelle sezioni seguenti vengono descritte le opzioni di query e vengono illustrati alcuni scenari comuni.

Sintassi delle query di base

Per restituire tutte le tabelle in un determinato account di archiviazione, eseguire un'operazione GET sulla risorsa Tabelle, come descritto nell'operazione Tabelle di query . L'URI di base per l'indirizzamento della risorsa Tabelle è il seguente:

https://myaccount.table.core.windows.net/Tables  

Per restituire una singola tabella denominata, specificare la tabella nel modo seguente:

https://myaccount.table.core.windows.net/Tables('MyTable')  

Per restituire tutte le entità in una tabella, specificare il nome della tabella nell'URI, senza la risorsa Tabelle:

https://myaccount.table.core.windows.net/MyTable()  

I risultati delle query vengono ordinati per PartitionKey, quindi per RowKey. Altri tipi di ordinamento dei risultati non sono supportati.

È possibile specificare opzioni aggiuntive per limitare il set di tabelle o entità restituite, come descritto nella sezione Opzioni di query supportate seguente.

Nota

È possibile limitare il numero di entità restituite per una singola richiesta, se la query supera il numero massimo di entità, supera l'intervallo di timeout o supera il limite della partizione. Per altre informazioni, vedere Timeout delle query e Paginazione.

Opzioni di query supportate

Il servizio tabelle supporta le opzioni di query seguenti, conformi alla specifica del protocollo OData. È possibile utilizzare queste opzioni per limitare il set di tabelle, entità o proprietà di entità restituite da una query.

Opzione query di sistema Descrizione
$filter Restituisce solo le tabelle o le entità che soddisfano il filtro specificato.

Si noti che non sono consentiti più di 15 confronti discreti in una stringa $filter.
$top Restituisce solo le prime n tabelle o entità del set.
$select Restituisce le proprietà desiderate di un'entità dal set. Questa opzione di query è supportata solo per le richieste che utilizzano la versione 2011-08-18 o successive. Per altre informazioni, vedere Scrittura di query LINQ sul servizio tabelle.

Nota

Una richiesta che restituisce più del numero massimo predefinito o massimo di risultati specificato restituisce un token di continuazione per l'esecuzione della paginazione. Quando si effettuano richieste successive che includono token di continuazione, assicurarsi di passare l'URI originale nella richiesta. Ad esempio, se è stata specificata un'opzione $filterdi query , $selecto $top come parte della richiesta originale, è necessario includere tale opzione nelle richieste successive. In caso contrario, le richieste successive potrebbero restituire risultati imprevisti. Per altre informazioni, vedere Timeout delle query e Paginazione .

Si noti che l'opzione $top query nel caso in cui i risultati vengano impaginati specifica il numero massimo di risultati per pagina, non il numero massimo di risultati nell'intero set di risposte.

Le opzioni di query aggiuntive definite da OData non sono supportate dal servizio tabelle.

Operatori di confronto supportati

In una clausola $filter è possibile utilizzare gli operatori di confronto per specificare i criteri in base ai quali filtrare i risultati di query.

Per tutti i tipi di proprietà, sono supportati gli operatori di confronto seguenti:

Operatore Espressione dell'URI
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

Per le proprietà booleane sono supportati gli operatori seguenti:

Operatore Espressione dell'URI
And and
Not not
Or or

Per altre informazioni sulla sintassi del filtro, vedere la specifica del protocollo OData.

Codifica delle stringhe di query

Per poter usare i caratteri seguenti in una stringa di query, è necessario codificarli:

  • Barra (/)
  • Punto interrogativo (?)
  • Due punti (:)
  • Simbolo @
  • E commerciale (&)
  • Segno di uguale (=)
  • Segno più (+)
  • Virgola (,)
  • Segno del dollaro ($)

Virgolette singole (')

Le virgolette singole nelle stringhe di query devono essere rappresentate come due virgolette singole consecutive (''). Ad esempio, "o'clock" sarà:

o''clock

Espressioni di query di esempio

Negli esempi seguenti viene illustrato come creare l'URI della richiesta per alcune query di entità tipiche utilizzando la sintassi REST. Le stesse query possono essere scritte utilizzando la sintassi LINQ. Per altre informazioni, vedere Scrittura di query LINQ sul servizio tabelle.

Si noti che le opzioni $top e $filter possono essere entrambe utilizzate per filtrare i nomi delle tabelle, utilizzando la sintassi illustrata per applicare filtri sulle proprietà di tipo String.

Restituzione delle prime n entità

Per restituire le prime n entità per una query qualsiasi, specificare l'opzione di query $top. Nell'esempio seguente vengono restituite le prime n entità da una tabella denominata Customers:

https://myaccount.table.core.windows.net/Customers()?$top=10  

Applicazioni di filtri sulle proprietà PartitionKey e RowKey

Poiché le proprietà PartitionKey e RowKey costituiscono la chiave primaria di un'entità, è possibile utilizzare una sintassi speciale per identificare l'entità, come illustrato di seguito:

https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')  

In alternativa, è possibile specificare queste proprietà come parte dell'opzione $filter, come illustrato nella sezione seguente.

Si noti che i nomi delle proprietà chiave e i valori costanti distinguono tra maiuscole e minuscole. Le proprietà PartitionKey e RowKey sono entrambe di tipo String.

Creazione di stringhe di filtro

Quando si crea una stringa di filtro, tenere presente queste regole:

  • Usare gli operatori logici definiti dalla specifica del protocollo OData per confrontare una proprietà con un valore. Si noti che non è possibile confrontare una proprietà con un valore dinamico. Un elemento dell'espressione deve essere una costante.

  • Il nome della proprietà, l'operatore e il valore costante devono essere separati da spazi con codifica URL. Uno spazio con codifica URL è come %20.

  • Viene effettuata la distinzione tra maiuscole e minuscole per tutte le parti della stringa di filtro.

  • Il valore costante deve essere dello stesso tipo di dati della proprietà affinché il filtro restituisca risultati validi. Per altre informazioni sui tipi di proprietà supportati, vedere Informazioni sul modello di dati del servizio tabelle.

Nota

Assicurarsi che una proprietà sia stata tipizzata in modo esplicito prima di considerarla di un tipo diverso dalla stringa. Se una proprietà è stata tipizzata in modo esplicito, il tipo viene indicato nella risposta quando viene restituita l'entità. Se la proprietà non è stata tipizzata in modo esplicito, è di tipo String e il tipo non è indicato nella risposta quando viene restituita l'entità.

Applicazione di filtri alle proprietà della stringa

Quando si applicano filtri alle proprietà della stringa, includere la costante della stringa tra virgolette singole.

Nell'esempio seguente vengono applicati filtri alle proprietà PartitionKey e RowKey. Alla stringa della query è anche possibile aggiungere ulteriori proprietà non chiave.

https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'  

Nell'esempio seguente vengono applicati filtri alle proprietà FirstName e LastName:

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'  

Si noti che il servizio tabelle non supporta le query con caratteri jolly. Tuttavia, è possibile eseguire la corrispondenza di prefissi usando gli operatori di confronto sul prefisso desiderato. Nell'esempio seguente vengono restituite le entità con una proprietà LastName che inizia con la lettera 'A':

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'  

Applicazione di filtri alle proprietà numeriche

Per applicare filtri a un numero intero o a virgola mobile, specificare il valore della costante nell'URI senza virgolette.

In questo esempio vengono restituite tutte le entità con una proprietà Age il cui valore è maggiore di 30:

https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030  

In questo esempio vengono restituite tutte le entità con una proprietà AmountDue il cui valore è minore o uguale a 100,25:

https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20  

Applicazione di filtri alle proprietà booleane

Per applicare filtri a un valore booleano, specificare true o false senza virgolette.

Nell'esempio seguente vengono restituite tutte le entità per le quali la proprietà IsActive è impostata su true:

https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true  

Applicazione di filtri alle proprietà DateTime

Per applicare filtri a un valore DateTime, specificare la parola chiave datetime nell'URI, seguita dalla costante date/time tra virgolette singole. La costante di data/ora deve essere in formato UTC combinato, come descritto in Formattazione dei valori DateTime.

Nell'esempio seguente vengono restituite le entità per le quali la proprietà CustomerSince è uguale a 10 luglio 2008:

https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'  

Applicazione di filtri alle proprietà GUID

Per applicare filtri a un valore GUIID, specificare la parola chiave guid nell'URI, seguita dalla costante GUID tra virgolette singole.

Nell'esempio seguente vengono restituite le entità per le quali la proprietà GuidValue è uguale a:

https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'  

Vedere anche

Concetti del servizio tabelle
Informazioni sul modello di dati del servizio tabelle
Indirizzamento delle risorse del servizio tabelle
Timeout query e paginazione
Scrittura di query LINQ nel servizio tabelle