Share via

QueueClient 類別

  • 參考

要與特定佇列互動的用戶端。

如需更多選擇性設定，請按一下 這裡。

繼承
azure.storage.queue._shared.base_client.StorageAccountHostsMixin
QueueClient
azure.storage.queue._encryption.StorageEncryptionMixin
QueueClient

建構函式

QueueClient(account_url: str, queue_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

參數

account_url
str
必要

儲存體帳戶的 URL。 若要為佇列提供完整 URI 來建立用戶端，請使用 from_queue_url classmethod。

queue_name
str
必要

佇列的名稱。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 的實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以取得明確的認證

  • 除了 AzureSasCredential 的情況之外，衝突的 SAS 權杖將會引發 ValueError。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。
api_version
str

要用於要求的儲存體 API 版本。 預設值是與目前 SDK 相容的最新服務版本。 將 設定為較舊版本可能會導致功能相容性降低。

secondary_hostname
str

次要端點的主機名稱。

message_encode_policy

要用於傳出訊息的編碼原則。 預設值不是編碼訊息。 其他選項包括 TextBase64EncodePolicy 、 BinaryBase64EncodePolicy 或 None。

message_decode_policy

要用於傳入訊息的解碼原則。 預設值不是解碼訊息。 其他選項包括 TextBase64DecodePolicy 、 BinaryBase64DecodePolicy 或 None。

audience
str

要求 Azure Active Directory 驗證權杖時要使用的物件。 只有在認證類型為 TokenCredential 時才會生效。 此值可以是 https://storage.azure.com/ 預設 () 或 HTTPs：//.queue.core.windows.net。

範例

使用 URL 和認證建立佇列用戶端。


   token_auth_queue = QueueClient.from_queue_url(
       queue_url=queue.url,
       credential=sas_token
   )

方法

clear_messages

從指定的佇列中刪除所有訊息。
close

這個方法是關閉用戶端所開啟的通訊端。 搭配內容管理員使用時，不需要使用它。
create_queue

在儲存體帳戶中建立新的佇列。

如果具有相同名稱的佇列已經存在，作業就會失敗， 並出現 ResourceExistsError。
delete_message

刪除指定的訊息。

一般而言，在用戶端擷取具有接收訊息作業的訊息之後，用戶端預期會處理並刪除訊息。 若要刪除訊息，您必須擁有訊息物件本身，或兩個專案的資料：id 和 pop_receipt。 識別碼會從先前的receive_messages作業傳回。 pop_receipt是從最近 receive_messages 或 update_message 作業傳回。 為了讓delete_message作業成功，要求上指定的pop_receipt必須符合 或 update_message 作業傳 receive_messages 回的pop_receipt。
delete_queue

刪除指定的佇列及其包含的任何訊息。

成功刪除佇列時，它會立即標示為要刪除，而且用戶端無法再存取。 稍後記憶體回收時，將會從佇列服務中移除此佇列。

請注意，刪除佇列可能需要至少 40 秒的時間才能完成。 如果在刪除佇列時嘗試對佇列執行作業， <xref:azure.storage.queue.HttpResponseError> 將會擲回 。
from_connection_string

從連接字串建立 QueueClient。
from_queue_url

要與特定佇列互動的用戶端。
get_queue_access_policy

傳回可用於共用存取簽章之佇列上指定之任何預存存取原則的詳細資料。
get_queue_properties

傳回指定佇列的所有使用者定義中繼資料。

傳回的資料不包含佇列的訊息清單。
peek_messages

從佇列前端擷取一或多個訊息，但不會改變訊息的可見度。

只能擷取可見的訊息。 第一次使用 呼叫 receive_messages 擷取訊息時，其dequeue_count屬性會設定為 1。 如果未刪除，且後續會再次擷取，則會遞增dequeue_count屬性。 用戶端可以使用這個值判斷訊息被擷取的次數。 請注意，對 peek_messages 的呼叫不會遞增dequeue_count的值，但會傳回此值供用戶端讀取。

如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。
receive_message

從佇列前端移除一則訊息。

從佇列擷取訊息時，回應會包含訊息內容和pop_receipt值，這是刪除訊息所需的值。 訊息不會從佇列自動刪除，但在擷取訊息之後，其他用戶端不會看到visibility_timeout參數所指定的時間間隔。

如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。
receive_messages

從佇列前端移除一或多個訊息。

從佇列擷取訊息時，回應會包含訊息內容和pop_receipt值，這是刪除訊息所需的值。 訊息不會從佇列自動刪除，但在擷取訊息之後，其他用戶端不會看到visibility_timeout參數所指定的時間間隔。 反覆運算器會持續擷取訊息，直到已設定max_messages) 時，佇列是空的或max_messages達到 (。

如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。
send_message

將新的訊息新增至訊息佇列的後端。

可見度逾時會指定訊息不可見的時間。 逾時終止之後，會顯示訊息。 如果未指定可見度逾時，則會使用預設值 0。

訊息存留時間會指定訊息會保留在佇列中的時間長度。 存留時間期限到期時，將會從佇列中刪除訊息。

如果本機服務物件上已設定 key-encryption-key 欄位，這個方法會在上傳之前先加密內容。
set_queue_access_policy

為佇列設定可搭配共用存取簽章使用之儲存的存取原則。

當您設定佇列的權限時，會取代現有的權限。 若要更新佇列的許可權，請呼叫 get_queue_access_policy 以擷取與佇列相關聯的所有存取原則、修改您想要變更的存取原則，然後使用完整的資料集呼叫此函式來執行更新。

當您在佇列上建立儲存的存取原則時，可能需要 30 秒的時間才會生效。 在此間隔期間，與預存存取原則相關聯的共用存取簽章將會擲回 ， <xref:azure.storage.queue.HttpResponseError> 直到存取原則變成作用中為止。
set_queue_metadata

在指定的佇列上設定使用者定義的中繼資料。

中繼資料與佇列產生關聯的結果為名稱/值組。
update_message

匯報訊息的可見度逾時。 您也可以使用這項作業，以更新訊息的內容。

此作業可用來持續擴充佇列訊息的不可見度。 如果您想要背景工作角色「租用」佇列訊息，這項功能會很有用。 例如，如果背景工作角色呼叫 receive_messages 並辨識它需要更多時間來處理訊息，它可以持續擴充訊息的不可見度，直到處理它為止。 如果背景工作角色在處理期間失敗，訊息最後會再次顯示，以供其他背景工作角色處理。

如果本機服務物件上已設定 key-encryption-key 欄位，這個方法會在上傳之前先加密內容。

clear_messages

從指定的佇列中刪除所有訊息。

clear_messages(**kwargs: Any) -> None

參數

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

範例

清除所有訊息。


   queue.clear_messages()

close

這個方法是關閉用戶端所開啟的通訊端。 搭配內容管理員使用時，不需要使用它。

close()

create_queue

在儲存體帳戶中建立新的佇列。

如果具有相同名稱的佇列已經存在，作業就會失敗， 並出現 ResourceExistsError。

create_queue(*, metadata: Dict[str, str] | None = None, **kwargs: Any) -> None

參數

metadata
Dict[str,str]

包含要與佇列建立關聯做為中繼資料之名稱/值組的聽寫。 請注意，中繼資料名稱會保留其建立時的大小寫，但在設定或讀取時並不區分大小寫。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

無或 cls (回應的結果)

傳回類型

None

例外狀況

StorageErrorException

範例

建立佇列。


   queue.create_queue()

delete_message

刪除指定的訊息。

一般而言，在用戶端擷取具有接收訊息作業的訊息之後，用戶端預期會處理並刪除訊息。 若要刪除訊息，您必須擁有訊息物件本身，或兩個專案的資料：id 和 pop_receipt。 識別碼會從先前的receive_messages作業傳回。 pop_receipt是從最近 receive_messages 或 update_message 作業傳回。 為了讓delete_message作業成功，要求上指定的pop_receipt必須符合 或 update_message 作業傳 receive_messages 回的pop_receipt。

delete_message(message: str | QueueMessage, pop_receipt: str | None = None, **kwargs: Any) -> None

參數

message
str 或 QueueMessage
必要

識別要刪除之訊息的訊息物件或識別碼。

pop_receipt
str
必要

從 或 的先前呼叫 receive_messagesupdate_message 傳回的有效快顯收據值。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

範例

刪除訊息。


   # Get the message at the front of the queue
   msg = next(queue.receive_messages())

   # Delete the specified message
   queue.delete_message(msg)

delete_queue

刪除指定的佇列及其包含的任何訊息。

成功刪除佇列時，它會立即標示為要刪除，而且用戶端無法再存取。 稍後記憶體回收時，將會從佇列服務中移除此佇列。

請注意，刪除佇列可能需要至少 40 秒的時間才能完成。 如果在刪除佇列時嘗試對佇列執行作業， <xref:azure.storage.queue.HttpResponseError> 將會擲回 。

delete_queue(**kwargs: Any) -> None

參數

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

None

範例

刪除佇列。


   queue.delete_queue()

from_connection_string

從連接字串建立 QueueClient。

from_connection_string(conn_str: str, queue_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

參數

conn_str
str
必要

Azure 儲存體帳戶連接字串。

queue_name
str
必要

佇列名稱。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，或連接字串已經有共用存取金鑰值，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 的實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 此處提供的認證優先于連接字串中的認證。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。

audience
str

要求 Azure Active Directory 驗證權杖時要使用的物件。 只有在認證類型為 TokenCredential 時才會生效。 此值可以是 https://storage.azure.com/ 預設 () 或 HTTPs：//.queue.core.windows.net。

傳回

佇列用戶端。

傳回類型

QueueClient

範例

從 連接字串 建立佇列用戶端。


   from azure.storage.queue import QueueClient
   queue = QueueClient.from_connection_string(self.connection_string, "myqueue1")

from_queue_url

要與特定佇列互動的用戶端。

from_queue_url(queue_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

參數

queue_url
str
必要

佇列的完整 URI，包括使用 SAS 權杖。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 的實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以取得明確的認證

  • 除了 AzureSasCredential 的情況之外，衝突的 SAS 權杖將會引發 ValueError。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。
audience
str

要求 Azure Active Directory 驗證權杖時要使用的物件。 只有在認證類型為 TokenCredential 時才會生效。 此值可以是 https://storage.azure.com/ 預設 () 或 HTTPs：//.queue.core.windows.net。

傳回

佇列用戶端。

傳回類型

QueueClient

get_queue_access_policy

傳回可用於共用存取簽章之佇列上指定之任何預存存取原則的詳細資料。

get_queue_access_policy(**kwargs: Any) -> Dict[str, AccessPolicy]

參數

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

與佇列相關聯的存取原則字典。

傳回類型

Dict[str, AccessPolicy]

get_queue_properties

傳回指定佇列的所有使用者定義中繼資料。

傳回的資料不包含佇列的訊息清單。

get_queue_properties(**kwargs: Any) -> QueueProperties

參數

timeout
int

timeout 參數以秒為單位。

傳回

佇列的使用者定義中繼資料。

傳回類型

QueueProperties

範例

取得佇列上的屬性。


   properties = queue.get_queue_properties().metadata

peek_messages

從佇列前端擷取一或多個訊息，但不會改變訊息的可見度。

只能擷取可見的訊息。 第一次使用 呼叫 receive_messages 擷取訊息時，其dequeue_count屬性會設定為 1。 如果未刪除，且後續會再次擷取，則會遞增dequeue_count屬性。 用戶端可以使用這個值判斷訊息被擷取的次數。 請注意，對 peek_messages 的呼叫不會遞增dequeue_count的值，但會傳回此值供用戶端讀取。

如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。

peek_messages(max_messages: int | None = None, **kwargs: Any) -> List[QueueMessage]

參數

max_messages
int
必要

這是非零整數值，可指定從佇列查看的訊息數目 (32 則為上限)。 根據預設，使用此作業會從佇列查看單一訊息。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

QueueMessage 物件的清單。 請注意，next_visible_on和pop_receipt不會填入，因為預覽不會快顯訊息，而且只能擷取已經可見的訊息。

傳回類型

list(QueueMessage)

範例

預覽訊息。


   # Peek at one message at the front of the queue
   msg = queue.peek_messages()

   # Peek at the last 5 messages
   messages = queue.peek_messages(max_messages=5)

   # Print the last 5 messages
   for message in messages:
       print(message.content)

receive_message

從佇列前端移除一則訊息。

從佇列擷取訊息時，回應會包含訊息內容和pop_receipt值，這是刪除訊息所需的值。 訊息不會從佇列自動刪除，但在擷取訊息之後，其他用戶端不會看到visibility_timeout參數所指定的時間間隔。

如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。

receive_message(*, visibility_timeout: int | None = None, **kwargs: Any) -> QueueMessage | None

參數

visibility_timeout
int

如果未指定，預設值為 30。 指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 此值必須大於或等於 1，且不能大於 7 天。 訊息的可見度逾時不可以設為晚於到期時間的值。 visibility_timeout應該設定為小於存留時間值的值。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

如果佇列是空的，則傳回來自佇列或 None 的訊息。

傳回類型

QueueMessage,
None

範例

從佇列接收一則訊息。


   # Pop two messages from the front of the queue
   message1 = queue.receive_message()
   message2 = queue.receive_message()
   # We should see message 3 if we peek
   message3 = queue.peek_messages()[0]

   if not message1 or not message2 or not message3:
       raise ValueError("One of the messages are None.")

   print(message1.content)
   print(message2.content)
   print(message3.content)

receive_messages

從佇列前端移除一或多個訊息。

從佇列擷取訊息時，回應會包含訊息內容和pop_receipt值，這是刪除訊息所需的值。 訊息不會從佇列自動刪除，但在擷取訊息之後，其他用戶端不會看到visibility_timeout參數所指定的時間間隔。 反覆運算器會持續擷取訊息，直到已設定max_messages) 時，佇列是空的或max_messages達到 (。

如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。

receive_messages(*, messages_per_page: int | None = None, visibility_timeout: int | None = None, max_messages: int | None = None, **kwargs: Any) -> ItemPaged[QueueMessage]

參數

visibility_timeout
int

如果未指定，預設值為 30。 指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 此值必須大於或等於 1，且不能大於 7 天。 訊息的可見度逾時不可以設為晚於到期時間的值。 visibility_timeout應該設定為小於存留時間值的值。

max_messages
int

整數，指定要從佇列擷取的訊息數目上限。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

傳回類似聽寫之 Message 物件的訊息反覆運算器。

傳回類型

ItemPaged[QueueMessage]

範例

從佇列接收訊息。


   # Receive messages one-by-one
   messages = queue.receive_messages()
   for msg in messages:
       print(msg.content)

   # Receive messages by batch
   messages = queue.receive_messages(messages_per_page=5)
   for msg_batch in messages.by_page():
       for msg in msg_batch:
           print(msg.content)
           queue.delete_message(msg)

send_message

將新的訊息新增至訊息佇列的後端。

可見度逾時會指定訊息不可見的時間。 逾時終止之後，會顯示訊息。 如果未指定可見度逾時，則會使用預設值 0。

訊息存留時間會指定訊息會保留在佇列中的時間長度。 存留時間期限到期時，將會從佇列中刪除訊息。

如果本機服務物件上已設定 key-encryption-key 欄位，這個方法會在上傳之前先加密內容。

send_message(content: object | None, *, visibility_timeout: int | None = None, time_to_live: int | None = None, **kwargs: Any) -> QueueMessage

參數

content
Optional[object]
必要

訊息內容。 允許的類型是由服務上設定的encode_function所決定。 預設值為 str。 編碼訊息的大小上限為 64 KB。

visibility_timeout
int

若未指定，預設值是 0。 指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 此值必須大於或等於 0，且不能大於 7 天。 訊息的可見度逾時不可以設為晚於到期時間的值。 visibility_timeout應該設定為小於存留時間值的值。

time_to_live
int

指定訊息之存留時間的間隔 (以秒為單位)。 存留時間可以是任何正數或 -1 表示無限大。 如果省略此參數，預設存留時間為 7 天。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

QueueMessage 物件。 雖然此物件並未從服務傳回，但也會填入內容。

傳回類型

QueueMessage

範例

傳送訊息。


   queue.send_message("message1")
   queue.send_message("message2", visibility_timeout=30)  # wait 30s before becoming visible
   queue.send_message("message3")
   queue.send_message("message4")
   queue.send_message("message5")

set_queue_access_policy

為佇列設定可搭配共用存取簽章使用之儲存的存取原則。

當您設定佇列的權限時，會取代現有的權限。 若要更新佇列的許可權，請呼叫 get_queue_access_policy 以擷取與佇列相關聯的所有存取原則、修改您想要變更的存取原則，然後使用完整的資料集呼叫此函式來執行更新。

當您在佇列上建立儲存的存取原則時，可能需要 30 秒的時間才會生效。 在此間隔期間，與預存存取原則相關聯的共用存取簽章將會擲回 ， <xref:azure.storage.queue.HttpResponseError> 直到存取原則變成作用中為止。

set_queue_access_policy(signed_identifiers: Dict[str, AccessPolicy], **kwargs: Any) -> None

參數

signed_identifiers
Dict[str, AccessPolicy]
必要

要與佇列建立關聯的 SignedIdentifier 存取原則。 這最多可以包含 5 個元素。 空的聽寫會清除服務上設定的存取原則。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

範例

在佇列上設定存取原則。


   # Create an access policy
   from azure.storage.queue import AccessPolicy, QueueSasPermissions
   access_policy = AccessPolicy()
   access_policy.start = datetime.utcnow() - timedelta(hours=1)
   access_policy.expiry = datetime.utcnow() + timedelta(hours=1)
   access_policy.permission = QueueSasPermissions(read=True)
   identifiers = {'my-access-policy-id': access_policy}

   # Set the access policy
   queue.set_queue_access_policy(identifiers)

set_queue_metadata

在指定的佇列上設定使用者定義的中繼資料。

中繼資料與佇列產生關聯的結果為名稱/值組。

set_queue_metadata(metadata: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, Any]

參數

metadata
Optional[Dict[str, str]]
必要

包含要與佇列建立關聯做為中繼資料之名稱/值組的聽寫。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

回應標頭的字典。

傳回類型

Dict[str, Any]

範例

在佇列上設定中繼資料。


   metadata = {'foo': 'val1', 'bar': 'val2', 'baz': 'val3'}
   queue.set_queue_metadata(metadata=metadata)

update_message

匯報訊息的可見度逾時。 您也可以使用這項作業，以更新訊息的內容。

此作業可用來持續擴充佇列訊息的不可見度。 如果您想要背景工作角色「租用」佇列訊息，這項功能會很有用。 例如，如果背景工作角色呼叫 receive_messages 並辨識它需要更多時間來處理訊息，它可以持續擴充訊息的不可見度，直到處理它為止。 如果背景工作角色在處理期間失敗，訊息最後會再次顯示，以供其他背景工作角色處理。

如果本機服務物件上已設定 key-encryption-key 欄位，這個方法會在上傳之前先加密內容。

update_message(message: str | QueueMessage, pop_receipt: str | None = None, content: object | None = None, *, visibility_timeout: int | None = None, **kwargs: Any) -> QueueMessage

參數

message
str 或 QueueMessage
必要

識別要更新之訊息的訊息物件或識別碼。

pop_receipt
str
必要

從之前呼叫 receive_messages 或 update_message 作業所傳回的有效 pop receipt 值。

content
Optional[object]
必要

訊息內容。 允許的類型是由服務上設定的encode_function所決定。 預設值為 str。

visibility_timeout
int

指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 此新值必須大於或等於 0，而且不得超過 7 天。 訊息的可見度逾時不可以設為晚於到期時間的值。 在刪除訊息或訊息過期之前，都可更新訊息。 用來識別要更新之訊息的訊息物件或訊息識別碼。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

QueueMessage 物件。 為了方便起見，雖然服務不會傳回此物件，但也會填入內容。

傳回類型

QueueMessage

範例

更新訊息。


   # Send a message
   queue.send_message("update me")

   # Receive the message
   messages = queue.receive_messages()

   # Update the message
   list_result = next(messages)
   message = queue.update_message(
       list_result.id,
       pop_receipt=list_result.pop_receipt,
       visibility_timeout=0,
       content="updated")

屬性

api_version

用於要求的儲存體 API 版本。

傳回類型

str

location_mode

用戶端目前使用的位置模式。

根據預設，這會是「主要」。 選項包括 「primary」 和 「secondary」。

傳回類型

str

primary_endpoint

完整的主要端點 URL。

傳回類型

str

primary_hostname

主要端點的主機名稱。

傳回類型

str

secondary_endpoint

如果已設定，則為完整的次要端點 URL。

如果無法使用，將會引發 ValueError。 若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

傳回類型

str

例外狀況

ValueError

secondary_hostname

次要端點的主機名稱。

如果無法使用，則為 None。 若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

傳回類型

Optional[str]

url

此實體的完整端點 URL，包括使用 SAS 權杖。

這可能是主要端點或次要端點，視目前的 location_mode 而定。 ：returns：使用此實體的完整端點 URL，包括使用 SAS 權杖。 ：rtype： str