共用方式為

更新訊息

  • 發行項

Update Message 作業可更新訊息的可見度逾時。 您也可以使用這項作業，以更新訊息的內容。 訊息的格式必須包含于具有 UTF-8 編碼的 XML 要求中，且編碼訊息的大小上限為 64 KB。 此作業已引進 Azure 佇列儲存體 API 2011-08-18 版。

要求

您可以依照下列方式建構 Update Message 要求。 建議使用 HTTPS。 以儲存體帳戶的名稱取代 myaccount ，並將 myqueue 取代為佇列的名稱。

方法 要求 URI HTTP 版本
PUT https://myaccount.queue.core.windows.net/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds> HTTP/1.1

模擬的儲存體服務

SDK 1.6 和更新版本支援這項作業。

當您對模擬儲存體服務提出要求時，請將模擬器主機名稱和佇列儲存體埠指定為 127.0.0.1:10001 ，後面接著模擬的儲存體帳戶名稱。

方法 要求 URI HTTP 版本
PUT http://127.0.0.1:10001/devstoreaccount1/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds> HTTP/1.1

URI 參數

您可以在要求 URI 上指定下列參數。

參數 描述
popreceipt 必要。 指定從先前呼叫 取得訊息 或 更新訊息 作業傳回的有效快顯收據值。 popreceipt必須是 URL 編碼。
visibilitytimeout 必要。 指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 新值必須大於或等於 0，且不能大於 7 天。 訊息的可見度逾時不能設定為晚于到期時間的值。 您可以更新訊息，直到訊息已刪除或過期為止。
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊，請參閱 設定佇列儲存體作業的逾時。

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
Date or x-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
x-ms-version 需要 2011-08-18 或更新版本。 指定用於這個要求的作業版本。 如需詳細資訊，請參閱 Azure 儲存體服務的版本。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。 如需詳細資訊，請參閱 監視 Azure 佇列儲存體。

要求本文

要求主體包含下列 XML 格式中的訊息資料。 請注意，訊息內容的格式必須是可使用 UTF-8 編碼的格式。

<QueueMessage>  
    <MessageText>message-content</MessageText>  
</QueueMessage>

回應

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

狀態碼

成功的作業會傳回狀態碼 204 (沒有內容)。 如需狀態碼的相關資訊，請參閱 狀態和錯誤碼。

回應標頭

這項作業的回應包括下列標頭。 回應也可以包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格。

要求標頭 描述
x-ms-request-id 此標頭可唯一識別已提出的要求，並可用於對要求進行疑難排解。 如需詳細資訊，請參閱 針對 API 作業進行疑難排解。
x-ms-version 指出用來執行要求的佇列儲存體版本。 對 2009-09-19 及更新版本提出要求會傳回此標頭。
Date UTC 日期/時間值，指出起始回應的時間。 服務會產生此值。
x-ms-popreceipt 佇列訊息的 pop receipt。
x-ms-time-next-visible 在佇列中看到訊息時顯示的 UTC 日期/時間值。
x-ms-client-request-id 您可以使用此標頭來針對要求和對應的回應進行疑難排解。 如果此標頭存在於要求中，這個標頭的值會等於標頭的值 x-ms-client-request-id 。 此值最多為 1，024 個可見的 ASCII 字元。 x-ms-client-request-id如果要求中沒有標頭，則此標頭不會出現在回應中。

回應本文

無。

授權

帳戶擁有者可以執行這項作業。 此外，具有共用存取簽章的任何人都可以執行這項作業。

範例要求與回應

下列要求將佇列訊息的顯示時間延長 30 秒，並更新其內容。

PUT https://myaccount.queue.core.windows.net/myqueue/messages/663d89aa-d1d9-42a2-9a6a-fcf822a97d2c?popreceipt=AgAAAAEAAAApAAAAGIw6Q29bzAE%3d&visibilitytimeout=30&timeout=30 HTTP/1.1

所傳送的要求包含下列標頭：

x-ms-version: 2011-08-18  
x-ms-date: Mon, 29 Aug 2011 17:17:21 GMT  
Authorization: SharedKey myaccount:batcrWZ35InGCZeTUFWMdIQiOZPCW7UEyeGdDOg7WW4=  
Content-Length: 75

所傳送的要求包含下列 XML 主體：

<QueueMessage>  
    <MessageText>new-message-content</MessageText>  
</QueueMessage>

傳送要求之後，會傳回下列回應：

HTTP/1.1 204 No Content  
Content-Length: 0  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: df34a7dd-3cbe-4206-a586-d6de3cf225a7  
x-ms-version: 2011-08-18  
x-ms-popreceipt: AwAAAAIAAAApAAAAINtMQ29bzAEBAAAA  
x-ms-time-next-visible: Mon, 29 Aug 2011 17:17:51 GMT  
Date: Mon, 29 Aug 2011 17:17:21 GMT

備註

Update Message如果指定的訊息不存在於佇列中，或指定的快顯回條不符合訊息，作業就會失敗。

Pop receipt 是由 Get Messages 作業或 Update Message 作業所傳回。 Pop receipt 會持續有效到發生下列其中一個事件為止：

  • 訊息已過期。

  • 已使用從 或 Update Message 收到的最後一個快顯 Get Messages 收據刪除郵件。

  • 已過了隱藏時間，因此 Get Messages 要求已從佇列中清除訊息。 過了隱藏時間之後，將再次顯示訊息。 如果由另一個 Get Messages 要求擷取，則傳回的快顯收據可用來刪除或更新訊息。

  • 訊息已更新可見度逾時。 更新訊息時，會傳回新的 pop receipt。

您可以使用 Update Message 作業來持續擴充佇列訊息的不可見度。 如果您想要背景工作角色租用佇列訊息，這項功能會很有用。 例如，如果背景工作角色呼叫 取得訊息 ，並辨識它需要更多時間來處理訊息，它可以持續擴充訊息的不可見度，直到處理為止。 如果背景工作角色在處理期間失敗，最終訊息會再次顯示，而另一個背景工作角色可以處理它。

另請參閱

授權對 Azure 儲存體的要求
狀態和錯誤碼
佇列儲存體錯誤碼