更新訊息

此作業會 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 上指定下列參數。

參數	Description
`popreceipt`	必須的。指定從先前呼叫 [取得訊息] 或 [更新訊息 ] 作業傳回的有效彈出收據值。必須 `popreceipt` 以 URL 編碼。
`visibilitytimeout`	必須的。指定相對於伺服器時間的新可見度逾時值（以秒為單位）。新值必須大於或等於 0，且不能大於 7 天。訊息的可見度逾時無法設定為晚於到期時間的值。您可以更新訊息，直到訊息被刪除或過期為止。
`timeout`	選擇性。參數以 `timeout` 秒為單位。如需相關資訊，請參閱設定佇列儲存體作業的逾時。

請求標頭

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

請求標頭	Description
`Authorization`	必須的。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體的要求。
`Date` `or x-ms-date`	必須的。指定要求的協調世界時間（UTC）。如需詳細資訊，請參閱授權對 Azure 儲存體的要求。
`x-ms-version`	需要 2011-08-18 或更新版本。指定要用於此請求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`x-ms-client-request-id`	選擇性。提供用戶端產生的不透明值，其字元限制為 1 KB （KiB），該字元限制會在設定記錄時記錄在記錄中。強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求建立關聯。如需詳細資訊，請參閱監視 Azure 佇列儲存體。

請求主體

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

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

回應

回應包含 HTTP 狀態代碼和一組響應標頭。

狀態碼

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

回應標頭

此作業的回應包含下列標頭。回應也可以包含其他標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協定規範。

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

回應主體

沒有。

Authorization

帳戶擁有者可以執行此作業。此外，任何具有共享存取簽章且有權執行此作業的人都可以這樣做。

範例要求和回應

下列要求會將佇列訊息的可見度延長 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如果佇列中不存在指定的訊息，或指定的彈出式收據與訊息不符，則作業會失敗。

作業或Update Message作業會傳Get Messages回彈出收據。彈出收據在發生下列其中一個事件之前保持有效：

訊息已過期。
訊息已使用收到的最後一個彈出式收據（來自 Get Messages 或 Update Message）刪除。
不可見時間已過，且訊息已由要求移 Get Messages 出佇列。當不可見時間過去時，訊息會再次可見。如果由另一個 Get Messages 要求擷取，則傳回的彈出式回條可用來刪除或更新訊息。
訊息已更新為新的可見度逾時。更新訊息後，將傳回新的彈出式收據。

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

訊息的格式必須可以包含在具有 UTF-8 編碼的 XML 要求中。若要在訊息中包含標記，訊息的內容必須以 Base64 編碼。訊息中任何未編碼的 XML 標記都會導致訊息無效。如果訊息中包含無效字元（例如 0x1F），即使它是 XML 逸出，訊息的後續讀取也不會成功。

如果訊息太大，服務會傳回狀態碼 400 （錯誤的要求）。

另請參閱

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

Last updated on 2025-10-22

共用方式為