更新訊息

發行項
06/27/2023

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 儲存體的要求
 狀態和錯誤碼
 佇列儲存體錯誤碼