放置訊息

發行項
08/05/2023

Put Message 作業可將新訊息加入到訊息佇列的後端。您也可以指定可見度逾時，讓訊息隱藏，直到可見度逾時到期為止。訊息必須使用 UTF-8 編碼格式，才可包含在 XML 要求中。針對 2011-08-18 版和更新版本，編碼的訊息大小可高達 64 kibibytes (KiB) ，或舊版的 8 KiB。

要求

您可以建構 Put Message 要求，如下所示。建議您使用 HTTPS。將 myaccount 取代為您的儲存體帳戶名稱，並以 myqueue 您的佇列名稱取代：

方法	要求 URI	HTTP 版本
`POST`	`https://myaccount.queue.core.windows.net/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1

模擬儲存體服務要求

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

方法	要求 URI	HTTP 版本
`POST`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1

如需詳細資訊，請參閱使用 Azure 模擬器進行本機 Azure 儲存體開發。

URI 參數

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

參數	描述
`visibilitytimeout=<int=seconds>`	選擇性。指定相對於伺服器時間的新可見度逾時值，以秒為單位。如果已指定，則必須使用 `x-ms-version` 2011-08-18 或更新版本的來提出要求。如果未指定，預設值為 0。新值必須大於或等於 0，而且不能大於 7 天。郵件的可見度逾時無法設定為晚于到期日的值。設定 `visibilitytimeout` 為小於存留時間值的值。
`messagettl=<int-seconds>`	選擇性。指定訊息之存留時間的間隔 (以秒為單位)。在 2017-07-29 之前的版本中，允許的存留時間上限為 7 天。針對 2017-07-29 版和更新版本，存留時間上限可以是任何正數，表示 `-1` 訊息不會過期。如果省略此參數，預設存留時間為 7 天。
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定佇列服務作業的逾時。

要求標頭

下表說明必要的和選擇性要求標頭：

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

要求本文

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

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

範例要求

Request:  
POST https://myaccount.queue.core.windows.net/messages?visibilitytimeout=30&timeout=30 HTTP/1.1  
  
Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Tue, 30 Aug 2011 01:03:21 GMT  
Authorization: SharedKey myaccount:sr8rIheJmCd6npMSx7DfAY3L//V3uWvSXOzUBCV9wnk=  
Content-Length: 100  
  
Body:  
<QueueMessage>  
<MessageText>PHNhbXBsZT5zYW1wbGUgbWVzc2FnZTwvc2FtcGxlPg==</MessageText>  
</QueueMessage>

回應

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

狀態碼

成功的作業會傳回狀態碼「201 (已建立)」。

如需狀態碼的詳細資訊，請參閱狀態和錯誤碼。

回應標頭

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

要求標頭	描述
`x-ms-request-id`	可唯一識別提出的要求，而且您可以使用它對要求進行疑難排解。如需詳細資訊，請參閱針對 API 作業進行疑難排解。
`x-ms-version`	指出用來執行要求的佇列服務版本。針對針對 2009-09-19 版和更新版本提出的要求，會傳回此標頭。
`Date`	服務所產生的 UTC 日期/時間值，表示起始回應的時間。
`x-ms-client-request-id`	此標頭可用來針對要求和對應的回應進行疑難排解。如果此標頭存在於要求中，且值包含不超過 1，024 個可見的 ASCII 字元，則此標頭的值等於標頭的值 `x-ms-client-request-id` 。 `x-ms-client-request-id`如果要求中沒有標頭，它就不會出現在回應中。

回應本文

自 2016-05-31 版起，作業的 Put Message 回應會包含回應本文中的訊息資訊。此處說明傳回本文的 XML 格式。

MessageID 項目是用來識別在佇列中之訊息的 GUID 值。此值會依佇列儲存體指派給訊息，而且不透明地指派給用戶端。這個值可以與 PopReceipt 元素的值搭配使用，以刪除或更新佇列中的訊息。 PopReceipt 的值也對用戶端不透明，而且當您使用刪除訊息或更新訊息 API 時，這是必要的值。

InsertionTime、ExpirationTime 和 TimeNextVisible 項目會以 UTC 值表示，格式如 RFC 1123 所述。

<QueueMessagesList>
    <QueueMessage>
      <MessageId>string-message-id</MessageId>
      <InsertionTime>insertion-time</InsertionTime>
      <ExpirationTime>expiration-time</ExpirationTime>
      <PopReceipt>opaque-string-receipt-data</PopReceipt>
      <TimeNextVisible>time-next-visible</TimeNextVisible>
    </QueueMessage>
</QueueMessagesList>

範例回應

Response Status:
HTTP/1.1 200 OK
Response headers:
Transfer-Encoding: chunked
Content-Type: application/xml
x-ms-version: 2016-05-31
Date: Fri, 09 Oct 2016 21:04:30 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0

Response Body:

<?xml version="1.0" encoding="utf-8"?>
<QueueMessagesList>
  <QueueMessage>
    <MessageId>5974b586-0df3-4e2d-ad0c-18e3892bfca2</MessageId>
    <InsertionTime>Fri, 09 Oct 2016 21:04:30 GMT</InsertionTime>
    <ExpirationTime>Fri, 16 Oct 2016 21:04:30 GMT</ExpirationTime>
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>
    <TimeNextVisible>Fri, 09 Oct 2016 23:29:20 GMT</TimeNextVisible>
   </QueueMessage>
</QueueMessagesList>

授權

此作業可由帳戶擁有者以及具有共用存取簽章且有權執行這項作業的任何人執行。

備註

選擇性的可見度逾時會指定訊息不可見的時間。逾時到期之後，訊息就會變成可見。如果您未指定可見度逾時，則會使用預設值 0。

選擇性的訊息存留時間會指定訊息保留在佇列中的時間長度。當存留時間到期時，就會從佇列中刪除訊息。

訊息必須使用 UTF-8 編碼格式，才可包含在 XML 要求中。若要在訊息中加入標記，訊息內容必須是 XML 逸出格式或 Base64 編碼格式。訊息中未逸出或編碼的任何 XML 標記都會在訊息新增至佇列之前移除。

如果訊息太大，服務會傳回狀態碼 400 (不正確的要求)。

另請參閱

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