Query Entities

Articolo
06/27/2023

Tramite l'operazione Query Entities vengono eseguite query sulle entità di una tabella. Sono incluse le opzioni $filter e $select.

Richiesta

Per le richieste che usano l'opzione di query, è necessario usare la $select versione 2011-08-18 o successiva. Inoltre, le intestazioni DataServiceVersion e MaxDataServiceVersion devono essere impostate su 2.0.

Per usare la proiezione, è necessario effettuare la richiesta usando la versione 2013-08-15 o successiva. Le DataServiceVersion intestazioni e MaxDataServiceVersion devono essere impostate su 3.0. Per altre informazioni, vedere Impostare le intestazioni della versione del servizio dati OData.

È possibile costruire la Query Entities richiesta come indicato di seguito. È consigliabile HTTPS. Sostituire myaccount con il nome dell'account di archiviazione e sostituire mytable con il nome della tabella.

Metodo	URI richiesta	Versione HTTP
`GET`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>`	HTTP/1.1

L'indirizzo del set di entità da eseguire una query potrebbe accettare varie forme nell'URI della richiesta. Per altre informazioni, vedere Eseguire query su tabelle ed entità.

URI del servizio di archiviazione emulato

Quando si effettua una richiesta con il servizio di archiviazione emulato, specificare il nome host dell'emulatore e la porta del servizio tabelle come 127.0.0.1:10002. Seguire queste informazioni con il nome dell'account di archiviazione emulato.

Metodo	URI richiesta	Versione HTTP
`GET`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>`	HTTP/1.1

Il servizio Tabelle nell'emulatore di archiviazione differisce da Archiviazione tabelle di Azure in diversi modi. Per altre informazioni, vedere Differenze tra l'emulatore di archiviazione e i servizi di archiviazione di Azure.

Parametri URI

L'operazione Query Entities supporta le opzioni di query definite dalla specifica del protocollo OData .

Intestazioni della richiesta

Nella tabella seguente vengono descritte le intestazioni richieste e facoltative:

Intestazione della richiesta	Descrizione
`Authorization`	Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`Date` o `x-ms-date`	Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`x-ms-version`	facoltativo. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`Accept`	facoltativo. Specifica il tipo di contenuto accettato del payload di risposta. I valori possibili sono: - `application/atom+xml` (versioni precedenti al 2015-12-11) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Per altre informazioni, vedere Formato payload per le operazioni di archiviazione tabelle.
`x-ms-client-request-id`	facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando la registrazione è configurata. È consigliabile usare questa intestazione per correlare le attività lato client con le richieste ricevute dal server.

Testo della richiesta

Nessuno.

Richiesta di esempio

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Risposta

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni per la risposta e il corpo di una risposta.

Codice stato

Un'operazione completata correttamente restituisce 200 (OK).

Per informazioni sui codici di stato, vedere Codici di errore e codici di errore e codici di errore di archiviazione tabelle.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta potrebbe includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione risposta	Descrizione
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	Indica che: - Il numero di entità da restituire supera 1.000. - L'intervallo di timeout del server viene superato. - Viene raggiunto un limite del server, se la query restituisce i dati distribuiti in più server. Per altre informazioni sull'uso dei token di continuazione, vedere Timeout query e paginazione.
`x-ms-request-id`	Identifica in modo univoco la richiesta effettuata. È possibile usarlo per risolvere la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api.
`x-ms-version`	Indica la versione di Archiviazione tabelle usata per eseguire la richiesta. Questa intestazione viene restituita per le richieste effettuate nella versione 2009-09-19 e successive.
`Date`	Valore di data/ora UTC che indica l'ora in cui il servizio ha inviato la risposta.
`Content-Type`	Indica il tipo di contenuto del payload. Il valore di questa intestazione dipende dal valore dell'intestazione della richiesta `Accept`. I valori possibili sono: - `application/atom+xml` (versioni precedenti al 2015-12-11) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Per altre informazioni sui tipi di contenuto validi, vedere Formato payload per le operazioni di archiviazione tabelle.
`x-ms-client-request-id`	Può essere usato per risolvere le richieste e le risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione `x-ms-client-request-id` , se presente nella richiesta e il valore è al massimo 1.024 caratteri ASCII visibili. Se l'intestazione `x-ms-client-request-id` non è presente nella richiesta, questa intestazione non sarà presente nella risposta.

Risposta di esempio

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

Corpo della risposta

L'operazione Query Entities restituisce l'elenco di entità in una tabella come set di entità OData. L'elenco delle entità è in un formato JSON o in un feed Atom, a seconda dell'intestazione Accept della richiesta.

Nota

È consigliabile json come formato payload. È l'unico formato supportato per la versione 2015-12-11 e versioni successive.

JSON (versione 2013-08-15 e versioni successive)

Ecco un URI di richiesta di esempio per un'operazione in una Query Entities tabella di clienti:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Ecco il payload della risposta in JSON senza metadati:

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Ecco il payload della risposta in JSON con metadati minimi:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Ecco il payload della risposta in JSON con metadati completi:

{  
   "odata.metadata":" https://myaccount.table.core.windows.net/metadata#Customers",  
   "value":[  
      {  
         "odata.type":"myaccount.Customers",  
         "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Feed Atom (versioni precedenti al 2015-12-11)

Ecco un URI di richiesta di esempio per un'operazione in una Query Entities tabella di clienti:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Ecco una risposta Atom di esempio per l'operazione Query Entities :

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

Autorizzazione

Questa operazione può essere eseguita dal proprietario dell'account e da qualsiasi altro utente che usa una firma di accesso condiviso con l'autorizzazione di esecuzione di questa operazione.

Commenti

Una query su Archiviazione tabelle può restituire un massimo di 1.000 entità contemporaneamente e può essere eseguita per un massimo di cinque secondi. La risposta include intestazioni personalizzate che contengono un set di token di continuazione in uno dei casi seguenti:

Il set di risultati contiene più di 1.000 entità.
La query non è stata completata entro cinque secondi.
La query supera il limite della partizione.

È possibile usare i token di continuazione per costruire una richiesta successiva per la pagina successiva di dati. Per altre informazioni sui token di continuazione, vedere Timeout delle query e paginazione.

Nota

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, includere tale opzione nelle richieste successive. In caso contrario, le richieste successive potrebbero restituire risultati imprevisti.

L'opzione $top query in questo caso specifica il numero massimo di risultati per pagina. Non specifica il numero massimo di risultati nell'intero set di risposte.

Per altre informazioni, vedere Eseguire query su tabelle ed entità.

Per le richieste di proiezione che usano l'opzione $select di query, la versione deve essere 2011-08-18 o successiva. Il numero massimo di proprietà restituite è 255. Il corpo della risposta include tutte le proprietà proiettate, anche se le proprietà non fanno parte dell'entità restituita.

Ad esempio, se la richiesta include una proprietà che l'entità proiettata non contiene, la proprietà mancante è contrassegnata con un attributo Null. Il corpo della risposta di esempio precedente include la Address proprietà , che non fa parte dell'entità proiettata. Il valore della proprietà è quindi null: <d:Address m:null="true" />.

Il tempo totale assegnato alla richiesta di pianificazione ed elaborazione della query è di 30 secondi. Il totale include i cinque secondi per l'esecuzione della query.

Si noti che il lato destro di un'espressione di query deve essere una costante. Non è possibile fare riferimento a una proprietà sul lato destro dell'espressione. Per informazioni dettagliate sulla creazione di espressioni di query, vedere Eseguire query su tabelle ed entità.

Un'espressione di query non può contenere null valori. Se vengono usati in una stringa di query, è necessario codificare i caratteri seguenti:

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

Qualsiasi applicazione in grado di autorizzare e inviare una richiesta HTTP GET può eseguire query sulle entità in una tabella.

Per altre informazioni sulle operazioni di query supportate sull'archiviazione tabelle tramite LINQ, vedere Operatori di query supportati per l'archiviazione tabelle e Scrivere query LINQ su Archiviazione tabelle.

Vedi anche

Codici di errore di archiviazione tabelle
Autorizzare le richieste ad Archiviazione di Azure
Stato e codici errore
Indirizzamento delle risorse di archiviazione tabelle
Eseguire query su tabelle ed entità
Impostare le intestazioni della versione del servizio dati OData
Insert Entity
Aggiornare l'entità
Delete Entity

Condividi tramite