QueueService 類別
這是管理佇列資源的主要類別。
佇列服務會儲存訊息。 佇列可以包含無限數目的訊息，每個訊息的大小最多可達 64KB。 訊息通常會加入到佇列的後端，並從佇列前端開始擷取，但不保證先進先出 (FIFO) 行為。
：type ~azure.storage.common.TokenCredential
- 繼承
-
QueueService
建構函式
QueueService(account_name=None, account_key=None, sas_token=None, is_emulated=False, protocol='https', endpoint_suffix='core.windows.net', request_session=None, connection_string=None, socket_timeout=None, token_credential=None)參數
- endpoint_suffix
- str
URL 的主機基底元件，減去帳戶名稱。 預設為 Azure (core.windows.net) 。 覆寫此選項以使用中國雲端 (core.chinacloudapi.cn) 。
- request_session
- <xref:requests.Session>
要用於 HTTP 要求的會話物件。
- connection_string
- str
如果指定，這會覆寫要求會話以外的所有其他參數。 如需連接字串格式，請參閱 http://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/ 。
- socket_timeout
- int
如果指定，這會覆寫預設通訊端逾時。 指定的逾時是以秒為單位。 如需預設值，請參閱 _constants.py 中的DEFAULT_SOCKET_TIMEOUT。
- token_credential
用來驗證 HTTPS 要求的權杖認證。 權杖值應該在到期前更新。
變數
- encode_function
- <xref:function>(<xref:data>)
用來編碼佇列訊息的函式。 接受作為傳遞至 put_message API 的資料參數，並傳回編碼的訊息。 預設為接受文字和 xml 編碼，但可以使用位元組和其他編碼。 例如，base64 可能比較適合在不同的語言中跨多個 Azure 儲存體程式庫進行開發。 QueueMessageFormat請參閱 xml、base64 和沒有編碼方法以及二進位對等專案的 。
- decode_function
- <xref:function>(<xref:data>)
用來編碼解碼訊息的函式。 接受作為get_messages和peek_messages API 所傳回之資料的參數，並傳回解碼的訊息。 預設會傳回文字和 xml 解碼，但可以使用位元組和其他解碼。 例如，base64 可能比較適合在不同的語言中跨多個 Azure 儲存體程式庫進行開發。 QueueMessageFormat請參閱 xml、base64 和沒有解碼方法以及二進位對等專案的 。
- key_encryption_key
- object
使用者選擇性地提供 key-encryption-key。 如果提供，將會用來加密/解密支援的方法。 對於需要解密的方法，必須提供key_encryption_key或解析程式。 如果同時提供這兩者，解析程式會優先使用。 必須針對需要加密的 API 實作下列方法：wrap_key (金鑰) 包裝指定的金鑰 (位元組) 使用使用者選擇的演算法。 以位元組形式傳回加密金鑰。 get_key_wrap_algorithm () –傳回用來包裝指定對稱金鑰的演算法。 get_kid () –傳回此金鑰加密金鑰的字串金鑰識別碼。 必須針對需要解密的 API 實作下列方法：unwrap_key (金鑰、演算法) –使用字串指定的演算法傳回指定對稱金鑰的未包裝形式。 get_kid () –傳回此金鑰加密金鑰的字串金鑰識別碼。
- key_resolver_function
- kid) (<xref:function>
函式，可選擇性地解析使用者所提供的金鑰。 如果提供，將會用來解密支援的方法。 對於需要解密的方法，必須提供key_encryption_key或解析程式。 如果同時提供這兩者，解析程式會優先使用。 它會使用兒童字串傳回實作上述介面的金鑰加密金鑰。
- require_encryption
- bool
可以設定的旗標，以確保所有訊息都已成功上傳至佇列，而且所有從佇列下載且成功讀取的訊息在伺服器上都會加密/已加密。 如果設定此旗標，則必須提供加密/解密的所有必要參數。 請參閱上述key_encryption_key和解析程式的批註。
方法
| clear_messages |
從指定的佇列中刪除所有訊息。 |
| create_queue |
在指定的帳號下建立佇列。 |
| delete_message |
刪除指定的訊息。 一般而言，在用戶端擷取具有get_messages作業的訊息之後，用戶端應該會處理並刪除訊息。 若要刪除訊息，您必須有兩個專案：id 和 pop_receipt。 識別碼會從上一個get_messages作業傳回。 pop_receipt是從最近 get_messages 或 update_message 作業傳回。 為了讓delete_message作業成功，要求上指定的pop_receipt必須符合 或 update_message 作業傳 get_messages 回的pop_receipt。 |
| delete_queue |
刪除指定的佇列及其包含的任何訊息。 成功刪除佇列時，它會立即標示為要刪除，而且用戶端無法再存取。 稍後記憶體回收時，將會從佇列服務中移除此佇列。 請注意，刪除佇列可能需要至少 40 秒的時間才能完成。 如果在刪除佇列時嘗試對佇列執行作業， <xref:azure.storage.queue.queueservice.AzureConflictHttpError> 將會擲回 。 |
| exists |
傳回布林值，指出佇列是否存在。 |
| extract_date_and_request_id | |
| generate_account_shared_access_signature |
產生佇列服務的共用存取簽章。 使用傳回的簽章搭配 QueueService 的 sas_token 參數。 |
| generate_queue_shared_access_signature |
產生佇列的共用存取簽章。 使用傳回的簽章搭配 QueueService 的 sas_token 參數。 |
| get_messages |
從佇列前端擷取一或多個訊息。 從佇列擷取訊息時，回應會包含訊息內容和pop_receipt值，這是刪除訊息所需的值。 訊息不會從佇列自動刪除，但在擷取訊息之後，其他用戶端不會看到visibility_timeout參數所指定的時間間隔。 如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。 |
| get_queue_acl |
傳回可用於共用存取簽章之佇列上指定之任何預存存取原則的詳細資料。 |
| get_queue_metadata |
擷取指定佇列上使用者定義的中繼資料和佇列屬性。 中繼資料與佇列產生關聯的結果為名稱/值組。 |
| get_queue_service_properties |
取得儲存體帳戶佇列服務的屬性，包括記錄、分析和 CORS 規則。 |
| get_queue_service_stats |
擷取與佇列服務的複寫相關的統計資料。 只有在儲存體帳戶啟用讀取權限異地備援複寫時，才能使用。 有了地理備援複寫，Azure 儲存體會以持久的方式在兩個位置維護您的資料。 在這兩個位置中，Azure 儲存體會持續維護狀況良好的多個資料複本。 您讀取、建立、更新或刪除資料的位置是「主要」儲存體帳戶的位置。 主要位置存在於您在透過 Azure 管理 Azure 傳統入口網站建立帳戶時所選擇的區域，例如美國中北部。 資料複寫的目標位置是「次要」位置。 次要位置是根據主要的位置自動判斷而來，它是與主要位置位於相同地區的第二個資料中心。 當儲存體帳戶啟用「讀取權限的地理備援複寫」時，可從次要位置使用唯讀權限。 |
| list_queues |
傳回產生器以列出佇列。 產生器會延遲遵循服務傳回的接續權杖，並在到達所有佇列或num_results時停止。 如果指定了num_results，且帳戶的佇列數目超過該數目，則產生器會在完成之後填入next_marker欄位。 如果需要更多結果，可以使用此標記來建立新的產生器。 |
| peek_messages |
從佇列前端擷取一或多個訊息，但不會改變訊息的可見度。 只能擷取可見的訊息。 第一次使用呼叫get_messages擷取訊息時，其dequeue_count屬性會設定為 1。 如果未刪除，且後續會再次擷取，則會遞增dequeue_count屬性。 用戶端可以使用這個值判斷訊息被擷取的次數。 請注意，對 peek_messages 的呼叫不會遞增 DequeueCount 的值，但會傳回此值供用戶端讀取。 如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。 |
| put_message |
將新訊息新增至訊息佇列的背面。 可見度逾時會指定訊息將隱藏的時間。 逾時終止之後，會顯示訊息。 如果未指定可見度逾時，則會使用預設值 0。 訊息存留時間會指定訊息會保留在佇列中的時間長度。 存留時間期限到期時，將會從佇列中刪除訊息。 如果在本機服務物件上設定了 key-encryption-key 欄位，此方法會在上傳之前先加密內容。 |
| set_proxy |
設定 HTTP CONNECT Tunnelling 的 Proxy 伺服器主機和埠。 |
| set_queue_acl |
為佇列設定可搭配共用存取簽章使用之儲存的存取原則。 當您設定佇列的權限時，會取代現有的權限。 若要更新佇列的許可權，請呼叫 get_queue_acl 以擷取與佇列相關聯的所有存取原則、修改您想要變更的存取原則，然後使用完整的資料集呼叫此函式來執行更新。 當您在佇列上建立儲存的存取原則時，可能需要 30 秒的時間才會生效。 在此間隔期間，與預存存取原則相關聯的共用存取簽章會擲回 ， <xref:azure.storage.queue.queueservice.AzureHttpError> 直到存取原則變成作用中為止。 |
| set_queue_metadata |
在指定的佇列上設定使用者定義的中繼資料。 中繼資料與佇列產生關聯的結果為名稱/值組。 |
| set_queue_service_properties |
設定儲存體帳戶佇列服務的屬性，包括 Azure 儲存體分析。 如果專案 (例如 Logging) 保留為 None，則會保留該服務上的現有設定。 如需 Azure 儲存體分析的詳細資訊，請參閱 https://msdn.microsoft.com/en-us/library/azure/hh343270.aspx 。 |
| update_message |
匯報訊息的可見度逾時。 您也可以使用這項作業，以更新訊息的內容。 此作業可用來持續擴充佇列訊息的不可見度。 如果您想要讓背景工作角色「租用」佇列訊息，這項功能會很有用。 例如，如果背景工作角色呼叫 get_messages，並辨識它需要更多時間來處理訊息，它可以持續擴充訊息的不可見度，直到處理為止。 如果背景工作角色在處理期間失敗，訊息最後會再次顯示，以供其他背景工作角色處理。 如果在本機服務物件上設定了 key-encryption-key 欄位，此方法會在上傳之前先加密內容。 |
clear_messages
從指定的佇列中刪除所有訊息。
clear_messages(queue_name, timeout=None)參數
create_queue
在指定的帳號下建立佇列。
create_queue(queue_name, metadata=None, fail_on_exist=False, timeout=None)參數
- queue_name
- str
要建立的佇列名稱。 佇列名稱長度必須為 3 到 63 個字元，且只能包含小寫字母、數位和虛線 ( ) 字元。 佇列中的第一個和最後一個字母必須是英數位元。 虛線 (-) 字元不可做為第一個或最後一個字元。 佇列名稱中不可使用連續的虛線字元。
傳回
布林值，指出是否已建立佇列。 如果fail_on_exist設定為 True，這會擲回而不是傳回 false。
傳回類型
delete_message
刪除指定的訊息。
一般而言，在用戶端擷取具有get_messages作業的訊息之後，用戶端應該會處理並刪除訊息。 若要刪除訊息，您必須有兩個專案：id 和 pop_receipt。 識別碼會從上一個get_messages作業傳回。 pop_receipt是從最近 get_messages 或 update_message 作業傳回。 為了讓delete_message作業成功，要求上指定的pop_receipt必須符合 或 update_message 作業傳 get_messages 回的pop_receipt。
delete_message(queue_name, message_id, pop_receipt, timeout=None)參數
delete_queue
刪除指定的佇列及其包含的任何訊息。
成功刪除佇列時，它會立即標示為要刪除，而且用戶端無法再存取。 稍後記憶體回收時，將會從佇列服務中移除此佇列。
請注意，刪除佇列可能需要至少 40 秒的時間才能完成。 如果在刪除佇列時嘗試對佇列執行作業， <xref:azure.storage.queue.queueservice.AzureConflictHttpError> 將會擲回 。
delete_queue(queue_name, fail_not_exist=False, timeout=None)參數
傳回
布林值，指出佇列是否已刪除。 如果fail_not_exist設定為 True，這會擲回而不是傳回 false。
傳回類型
exists
傳回布林值，指出佇列是否存在。
exists(queue_name, timeout=None)參數
傳回
布林值，指出佇列是否存在。
傳回類型
extract_date_and_request_id
static extract_date_and_request_id(retry_context)參數
- retry_context
generate_account_shared_access_signature
產生佇列服務的共用存取簽章。 使用傳回的簽章搭配 QueueService 的 sas_token 參數。
generate_account_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)參數
- resource_types
- <xref:ResourceTypes>
指定帳戶 SAS 可存取的資源類型。
- permission
- <xref:AccountPermissions>
這些權限與共用存取簽章相關聯。 使用者只能執行這些權限允許的作業。 除非指定參考包含此欄位之預存存取原則的識別碼，否則為必要專案。 如果已在相關聯的預存存取原則中指定，則必須省略此欄位。
共用存取簽章變成不正確時間。 除非指定參考包含此欄位之預存存取原則的識別碼，否則為必要專案。 如果已在相關聯的預存存取原則中指定，則必須省略此欄位。 Azure 一律會將值轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。
共用存取簽章生效的時間。 如果省略，此呼叫的開始時間會假設為儲存體服務收到要求的時間。 Azure 一律會將值轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。
- ip
- str
指定要接受要求的 IP 位址或 IP 位址範圍。 如果要求的來源 IP 位址不符合 SAS 權杖上指定的 IP 位址或位址範圍，則不會驗證要求。 例如，在 SAS 上指定 sip=168.1.5.65 或 sip=168.1.5.60-168.1.5.70 會限制這些 IP 位址的要求。
傳回
共用存取簽章 (sas) 權杖。
傳回類型
generate_queue_shared_access_signature
產生佇列的共用存取簽章。 使用傳回的簽章搭配 QueueService 的 sas_token 參數。
generate_queue_shared_access_signature(queue_name, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None)參數
- permission
- QueuePermissions
這些權限與共用存取簽章相關聯。 使用者只能執行這些權限允許的作業。 除非指定參考包含此欄位之預存存取原則的識別碼，否則為必要專案。 如果已在相關聯的預存存取原則中指定，則必須省略此欄位。
共用存取簽章變成不正確時間。 除非指定參考包含此欄位之預存存取原則的識別碼，否則為必要專案。 如果已在相關聯的預存存取原則中指定，則必須省略此欄位。 Azure 一律會將值轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。
共用存取簽章生效的時間。 如果省略，此呼叫的開始時間會假設為儲存體服務收到要求的時間。 Azure 一律會將值轉換成 UTC。 如果在沒有時區資訊的情況下傳入日期，則會假設為 UTC。
- ip
- str
指定要接受要求的 IP 位址或 IP 位址範圍。 如果要求的來源 IP 位址不符合 SAS 權杖上指定的 IP 位址或位址範圍，則不會驗證要求。 例如，在 SAS 上指定 sip='168.1.5.65' 或 sip='168.1.5.60-168.1.5.70' 會限制這些 IP 位址的要求。
傳回
共用存取簽章 (sas) 權杖。
傳回類型
get_messages
從佇列前端擷取一或多個訊息。
從佇列擷取訊息時，回應會包含訊息內容和pop_receipt值，這是刪除訊息所需的值。 訊息不會從佇列自動刪除，但在擷取訊息之後，其他用戶端不會看到visibility_timeout參數所指定的時間間隔。
如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。
get_messages(queue_name, num_messages=None, visibility_timeout=None, timeout=None)參數
- num_messages
- int
這是非零整數值，可指定從佇列擷取的訊息數目 (32 則為上限)。 如果可見的訊息較少，則會傳回可見的訊息。 根據預設，使用此作業會從佇列擷取單一訊息。
- visibility_timeout
- int
指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 新值必須大於或等於 1 秒，且不能大於 7 天。 訊息的可見度逾時可以設為晚於到期時間的值。
傳回
QueueMessage物件，表示傳遞的資訊。
傳回類型
get_queue_acl
傳回可用於共用存取簽章之佇列上指定之任何預存存取原則的詳細資料。
get_queue_acl(queue_name, timeout=None)參數
傳回
與佇列相關聯的存取原則字典。
傳回類型
get_queue_metadata
擷取指定佇列上使用者定義的中繼資料和佇列屬性。 中繼資料與佇列產生關聯的結果為名稱/值組。
get_queue_metadata(queue_name, timeout=None)參數
傳回
字典，代表在估計佇列中訊息數目的聽寫上具有 approximate_message_count int 屬性的佇列中繼資料。
傳回類型
get_queue_service_properties
取得儲存體帳戶佇列服務的屬性，包括記錄、分析和 CORS 規則。
get_queue_service_properties(timeout=None)參數
傳回
佇列服務屬性。
傳回類型
get_queue_service_stats
擷取與佇列服務的複寫相關的統計資料。 只有在儲存體帳戶啟用讀取權限異地備援複寫時，才能使用。
有了地理備援複寫，Azure 儲存體會以持久的方式在兩個位置維護您的資料。 在這兩個位置中，Azure 儲存體會持續維護狀況良好的多個資料複本。 您讀取、建立、更新或刪除資料的位置是「主要」儲存體帳戶的位置。 主要位置存在於您在透過 Azure 管理 Azure 傳統入口網站建立帳戶時所選擇的區域，例如美國中北部。 資料複寫的目標位置是「次要」位置。 次要位置是根據主要的位置自動判斷而來，它是與主要位置位於相同地區的第二個資料中心。 當儲存體帳戶啟用「讀取權限的地理備援複寫」時，可從次要位置使用唯讀權限。
get_queue_service_stats(timeout=None)參數
傳回
佇列服務統計資料。
傳回類型
list_queues
傳回產生器以列出佇列。 產生器會延遲遵循服務傳回的接續權杖，並在到達所有佇列或num_results時停止。
如果指定了num_results，且帳戶的佇列數目超過該數目，則產生器會在完成之後填入next_marker欄位。 如果需要更多結果，可以使用此標記來建立新的產生器。
list_queues(prefix=None, num_results=None, include_metadata=False, marker=None, timeout=None)參數
- marker
- str
不透明接續權杖。 如果指定了num_results且產生器已完成列舉結果，則可以從先前產生器物件的next_marker欄位擷取此值。 如果指定，這個產生器會從先前產生器停止的點開始傳回結果。
peek_messages
從佇列前端擷取一或多個訊息，但不會改變訊息的可見度。
只能擷取可見的訊息。 第一次使用呼叫get_messages擷取訊息時，其dequeue_count屬性會設定為 1。 如果未刪除，且後續會再次擷取，則會遞增dequeue_count屬性。 用戶端可以使用這個值判斷訊息被擷取的次數。 請注意，對 peek_messages 的呼叫不會遞增 DequeueCount 的值，但會傳回此值供用戶端讀取。
如果在本機服務物件上設定了 key-encryption-key 或 resolver 欄位，則會在傳回之前解密訊息。
peek_messages(queue_name, num_messages=None, timeout=None)參數
傳回
QueueMessage 物件的清單。 請注意，time_next_visible和pop_receipt不會填入，因為預覽不會快顯訊息，而且只能擷取已經可見的訊息。
傳回類型
put_message
將新訊息新增至訊息佇列的背面。
可見度逾時會指定訊息將隱藏的時間。 逾時終止之後，會顯示訊息。 如果未指定可見度逾時，則會使用預設值 0。
訊息存留時間會指定訊息會保留在佇列中的時間長度。 存留時間期限到期時，將會從佇列中刪除訊息。
如果在本機服務物件上設定了 key-encryption-key 欄位，此方法會在上傳之前先加密內容。
put_message(queue_name, content, visibility_timeout=None, time_to_live=None, timeout=None)參數
- content
- <xref:obj>
訊息內容。 允許的類型是由服務上設定的encode_function所決定。 預設值為 str。 編碼訊息的大小上限為 64 KB。
- visibility_timeout
- int
若未指定，預設值是 0。 指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 此值必須大於或等於 0，且不能大於 7 天。 訊息的可見度逾時不可以設為晚於到期時間的值。 visibility_timeout應該設定為小於存留時間值的值。
傳回
QueueMessage 物件。 雖然此物件並未從服務傳回，但也會填入內容。
傳回類型
set_proxy
設定 HTTP CONNECT Tunnelling 的 Proxy 伺服器主機和埠。
set_proxy(host, port, user=None, password=None)參數
set_queue_acl
為佇列設定可搭配共用存取簽章使用之儲存的存取原則。
當您設定佇列的權限時，會取代現有的權限。 若要更新佇列的許可權，請呼叫 get_queue_acl 以擷取與佇列相關聯的所有存取原則、修改您想要變更的存取原則，然後使用完整的資料集呼叫此函式來執行更新。
當您在佇列上建立儲存的存取原則時，可能需要 30 秒的時間才會生效。 在此間隔期間，與預存存取原則相關聯的共用存取簽章會擲回 ， <xref:azure.storage.queue.queueservice.AzureHttpError> 直到存取原則變成作用中為止。
set_queue_acl(queue_name, signed_identifiers=None, timeout=None)參數
- signed_identifiers
- dict(str, AccessPolicy)
要與佇列產生關聯的存取原則字典。 字典最多可以包含 5 個元素。 空的字典會清除服務上設定的存取原則。
set_queue_metadata
在指定的佇列上設定使用者定義的中繼資料。 中繼資料與佇列產生關聯的結果為名稱/值組。
set_queue_metadata(queue_name, metadata=None, timeout=None)參數
set_queue_service_properties
設定儲存體帳戶佇列服務的屬性，包括 Azure 儲存體分析。 如果專案 (例如 Logging) 保留為 None，則會保留該服務上的現有設定。 如需 Azure 儲存體分析的詳細資訊，請參閱 https://msdn.microsoft.com/en-us/library/azure/hh343270.aspx 。
set_queue_service_properties(logging=None, hour_metrics=None, minute_metrics=None, cors=None, timeout=None)參數
- logging
- <xref:Logging>
記錄設定會提供要求記錄。
- hour_metrics
- <xref:Metrics>
小時計量設定會提供依 API 分組的要求統計資料摘要，以佇列的每小時匯總方式分組。
- minute_metrics
- <xref:Metrics>
分鐘計量設定會針對佇列的每個分鐘提供要求統計資料。
- cors
- list(CorsRule)
您可以在清單中包含最多五個 CorsRule 元素。 如果指定了空白清單，則會刪除所有 CORS 規則，而且會停用服務的 CORS。 如需有關 CORS 規則和評估邏輯的詳細資訊，請參閱https://msdn.microsoft.com/en-us/library/azure/dn535601.aspx。
update_message
匯報訊息的可見度逾時。 您也可以使用這項作業，以更新訊息的內容。
此作業可用來持續擴充佇列訊息的不可見度。 如果您想要讓背景工作角色「租用」佇列訊息，這項功能會很有用。 例如，如果背景工作角色呼叫 get_messages，並辨識它需要更多時間來處理訊息，它可以持續擴充訊息的不可見度，直到處理為止。 如果背景工作角色在處理期間失敗，訊息最後會再次顯示，以供其他背景工作角色處理。
如果在本機服務物件上設定了 key-encryption-key 欄位，此方法會在上傳之前先加密內容。
update_message(queue_name, message_id, pop_receipt, visibility_timeout, content=None, timeout=None)參數
- visibility_timeout
- int
指定相對於伺服器時間的新可見度逾時值 (以秒為單位)。 此新值必須大於或等於 0，而且不得超過 7 天。 訊息的可見度逾時不可以設為晚於到期時間的值。 在刪除訊息或訊息過期之前，都可更新訊息。
- content
- <xref:obj>
訊息內容。 允許的類型是由服務上設定的encode_function所決定。 預設值為 str。
傳回
QueueMessage 物件的清單。 為了方便起見，此物件也會填入內容，雖然服務不會傳回它。
傳回類型
屬性
protocol
request_session
socket_timeout
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應