查詢實體

發行項
02/07/2024

Query Entities 作業會查詢資料表中的實體，並包含 $filter 和 $select 選項。

要求

對於使用 $select 查詢選項的要求，您必須使用 2011-08-18 版或更新版本。此外，DataServiceVersion 和 MaxDataServiceVersion 標頭必須設為 2.0。

若要使用投影，您必須使用 2013-08-15 版或更新版本提出要求。 DataServiceVersion標 MaxDataServiceVersion 頭必須設定為 3.0。如需詳細資訊，請參閱設定 OData 數據服務版本標頭。

您可以依照下列方式建構 Query Entities 要求。我們建議使用 HTTPS。以記憶體帳戶的名稱取代 myaccount ，並以數據表的名稱取代 mytable 。

方法	要求 URI	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

要查詢之實體集的位址可能會在要求URI上採用各種形式。如需詳細資訊，請參閱查詢數據表和實體。

模擬記憶體服務 URI

當您對模擬器服務提出要求時，請將模擬器的主機名稱和資料表服務的埠指定為 127.0.0.1:10002。請遵循該資訊，其中包含模擬記憶體帳戶的名稱。

方法	要求 URI	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

記憶體模擬器中的數據表服務與 Azure 資料表記憶體有數種方式不同。如需詳細資訊，請參閱記憶體模擬器與 Azure 記憶體服務之間的差異。

URI 參數

此 Query Entities 作業支援 OData 通訊協定規格所定義的查詢選項。

要求標頭

下表描述必要和選擇性的要求標頭：

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	選擇性。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`Accept`	選擇性。指定接受的回應裝載內容類型。可能的值包括： - `application/atom+xml` 僅) 2015-12-11 之前的 (版本 - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 如需詳細資訊，請參閱數據表記憶體作業的承載格式。
`x-ms-client-request-id`	選擇性。提供客戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。

要求本文

無。

範例要求

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

回應

回應包括 HTTP 狀態碼、一組回應標頭和回應主體。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。

如需狀態代碼的相關信息，請參閱狀態和錯誤碼和數據表記憶體錯誤碼。

回應標頭

這項作業的回應包括下列標頭。回應也可能包含其他標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協議規格。

回應標頭	描述
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	表示： - 要傳回的實體數目超過 1,000。 - 超過伺服器逾時間隔。 - 如果查詢傳回分散到多部伺服器的數據，就會達到伺服器界限。如需使用接續令牌的詳細資訊，請參閱查詢逾時和分頁。
`x-ms-request-id`	可唯一識別所提出的要求。您可以使用它對要求進行疑難解答。如需詳細資訊，請參閱針對 API 作業進行疑難解答。
`x-ms-version`	指出用來執行要求的數據表記憶體版本。對 2009-09-19 及更新版本提出要求會傳回此標頭。
`Date`	UTC 日期/時間值，指出服務傳送響應的時間。
`Content-Type`	指出裝載的內容類型。此標頭的值會取決於 `Accept` 要求標頭的值。可能的值包括： - `application/atom+xml` 僅) 2015-12-11 之前的 (版本 - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 如需有效內容類型的詳細資訊，請參閱數據表記憶體作業的承載格式。
`x-ms-client-request-id`	可用來針對要求和對應的回應進行疑難解答。如果此標頭存在於要求中，此標頭的值等於標頭的值 `x-ms-client-request-id` ，且此值最多為 1,024 個可見的 ASCII 字元。 `x-ms-client-request-id`如果要求中沒有標頭，則回應中不會顯示此標頭。

範例回應

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

回應本文

作業 Query Entities 會將數據表中的實體清單傳回為 OData 實體集。實體清單是 JSON 格式或 Atom 摘要，視 Accept 要求的標頭而定。

注意

我們建議 JSON 作為承載格式。這是 2015-12-11 版和更新版本唯一支援的格式。

JSON (2013-08-15 版和更新版本)

以下是客戶資料表上作業的範例要求 URI Query Entities ：

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

以下是 JSON 中沒有元數據的響應承載：

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

以下是 JSON 中具有最少元數據的響應承載：

{  
   "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"  
      }  
   ]  
}

以下是 JSON 中具有完整元數據的響應承載：

{  
   "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"  
      }  
   ]  
}

Atom 摘要 (2015-12-11 之前的版本)

以下是客戶資料表上作業的範例要求 URI Query Entities ：

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

以下是作業的 Query Entities Atom 回應範例：

<?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>

授權

帳戶擁有者及使用共用存取簽章並有權執行這項作業的任何人，都可以執行這項作業。

備註

數據表記憶體的查詢一次最多可以傳回 1,000 個實體，最多可以執行五秒。回應包含自定義標頭，其中包含下列任一案例中的一組接續令牌：

結果集包含超過 1000 個實體。
查詢未在五秒內完成。
查詢跨越分割區界限。

您可以使用接續令牌來建構下一頁數據的後續要求。如需接續令牌的詳細資訊，請參閱查詢逾時和分頁。

注意

當您提出包含接續令牌的後續要求時，請務必在要求上傳遞原始 URI。例如，如果您已將、 $select或 $top 查詢選項指定為原始要求的一$filter部分，請在後續要求中包含該選項。否則，後續的要求可能會傳回非預期的結果。

在此情況下，查詢 $top 選項會指定每個頁面的結果數目上限。它不會指定整個回應集中的結果數目上限。

如需詳細資訊，請參閱查詢數據表和實體。

對於使用查詢選項的 $select 投影要求，版本必須是 2011-08-18 或更新版本。傳回的屬性數目上限為 255。回應本文包含所有投影屬性，即使屬性不屬於傳回實體的一部分也一樣。

例如，如果要求包含投射實體未包含的屬性 (property)，則會以 null 屬性 (attribute) 標記遺漏的屬性 (property)。上述範例回應本文包含 Address 屬性，不屬於投影實體的一部分。因此，屬性值為 null： <d:Address m:null="true" />。

配置給排程和處理查詢要求的總時間是30秒。該總計包含查詢執行的五秒。

請注意，查詢表達式的右側必須是常數。您無法參考表示式右側的屬性。如需建構查詢表達式的詳細資訊，請參閱查詢數據表和實體。

查詢表達式不能包含 null 值。如果您在查詢字串中使用下列字元，則必須進行編碼：

斜線 (/)
問號 (?)
冒號 (:)
@ 符號
連字號 (&)
等號 (=)
加號 (+)
逗號 (,)
貨幣符號 ($)

任何可以授權和傳送 HTTP GET 要求的應用程式都可以查詢數據表中的實體。

如需透過 LINQ 針對資料表記憶體支援的查詢作業詳細資訊，請參閱資料表記憶體支援的查詢運算元，以及針對資料表記憶體寫入 LINQ 查詢。

另請參閱

數據表記憶體錯誤碼
 授權對 Azure 記憶體的要求
 狀態和錯誤碼
 尋址數據表記憶體資源
 查詢數據表和實體
 設定 OData 資料服務版本標頭
 插入實體
 更新實體
 刪除實體

共用方式為