你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
QueueService 类
这是管理队列资源的main类。
队列服务存储消息。 队列可以包含无限数量的消息，每个消息的大小最大为 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 () – 返回此密钥的字符串密钥 ID。 必须为需要解密的 API 实现以下方法：unwrap_key (密钥、算法) –使用字符串指定的算法返回指定对称密钥的未包装形式。 get_kid () – 返回此密钥的字符串密钥 ID。
- 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。 ID 是从上一个get_messages操作返回的。 pop_receipt是从最近的 get_messages 或 update_message 操作返回的。 为了使delete_message操作成功，在请求中指定的pop_receipt必须与从 get_messages 或 update_message 操作返回的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 隧道的代理服务器主机和端口。 |
| 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 个字符，并且只能包含小写字母、数字和短划线 ( ) 字符。 队列中的第一个和最后一个字母必须是字母数字。 短划线 (-) 字符不能是第一个或最后一个字符。 队列名称中不允许有连续的短划线字符。
包含要作为元数据与队列关联的名称/值对的 dict。 请注意，元数据名称保留在创建时具有的大小写形式，但在设置或读取时不区分大小写。
返回
指示是否已创建队列的布尔值。 如果fail_on_exist设置为 True，则会引发，而不是返回 false。
返回类型
delete_message
删除指定的消息。
通常，在客户端使用 get_messages 操作检索消息后，客户端应处理并删除该消息。 若要删除消息，必须具有两个数据项：id 和pop_receipt。 ID 是从上一个get_messages操作返回的。 pop_receipt是从最近的 get_messages 或 update_message 操作返回的。 为了使delete_message操作成功，在请求中指定的pop_receipt必须与从 get_messages 或 update_message 操作返回的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>
与共享访问签名关联的权限。 用户只能执行权限允许的操作。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。
共享访问签名变为无效的时间。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 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
与共享访问签名关联的权限。 用户只能执行权限允许的操作。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。
共享访问签名变为无效的时间。 必需，除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定，则必须省略此字段。 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。 编码的消息大小最多可为 64KB。
- visibility_timeout
- int
如果未指定，则默认值为 0。 指定新的可见性超时值（秒），它相对于服务器时间。 该值必须大于或等于 0，并且不能大于 7 天。 消息的可见性超时不能设置为晚于到期时间的值。 visibility_timeout应设置为小于生存时间值的值。
返回
QueueMessage 对象。 此对象也用内容填充，尽管它不是从服务返回的。
返回类型
set_proxy
设置 HTTP CONNECT 隧道的代理服务器主机和端口。
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。
提交和查看相关反馈