azure.storage.queue.QueueClient.yml

### YamlMime:PythonClass
uid: azure.storage.queue.QueueClient
name: QueueClient
fullName: azure.storage.queue.QueueClient
module: azure.storage.queue
summary: 'A client to interact with a specific Queue.


  For more optional configuration, please click

  [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#optional-configuration).'
constructor:
  syntax: 'QueueClient(account_url: str, queue_name: str, credential: str | Dict[str,
    str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None =
    None, *, api_version: str | None = None, secondary_hostname: str | None = None,
    message_encode_policy: BinaryBase64EncodePolicy | TextBase64EncodePolicy | None
    = None, message_decode_policy: BinaryBase64DecodePolicy | TextBase64DecodePolicy
    | None = None, audience: str | None = None, **kwargs: Any)'
  parameters:
  - name: account_url
    description: 'The URL to the storage account. In order to create a client given
      the full URI to the queue,

      use the <xref:azure.storage.queue.QueueClient.from_queue_url> classmethod.'
    isRequired: true
    types:
    - <xref:str>
  - name: queue_name
    description: The name of the queue.
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: 'The credentials with which to authenticate. This is optional if
      the

      account URL already has a SAS token. The value can be a SAS token string,

      an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials,

      an account shared access key, or an instance of a TokenCredentials class from
      azure.identity.

      If the resource URI already contains a SAS token, this will be ignored in favor
      of an explicit credential

      - except in the case of AzureSasCredential, where the conflicting SAS tokens
      will raise a ValueError.

      If using an instance of AzureNamedKeyCredential, "name" should be the storage
      account name, and "key"

      should be the storage account key.'
    defaultValue: None
    types:
    - <xref:azure.core.credentials.AzureNamedKeyCredential>
    - <xref:azure.core.credentials.AzureSasCredential>
    - <xref:azure.core.credentials.TokenCredential>
    - <xref:str>
    - <xref:dict>[<xref:str>, <xref:str>]
    - <xref:None>
  keywordOnlyParameters:
  - name: api_version
    description: 'The Storage API version to use for requests. Default value is the
      most recent service version that is

      compatible with the current SDK. Setting to an older version may result in reduced
      feature compatibility.'
    defaultValue: None
    types:
    - <xref:str>
  - name: secondary_hostname
    description: The hostname of the secondary endpoint.
    defaultValue: None
    types:
    - <xref:str>
  - name: message_encode_policy
    description: 'The encoding policy to use on outgoing messages.

      Default is not to encode messages. Other options include ~azure.storage.queue.TextBase64EncodePolicy,

      ~azure.storage.queue.BinaryBase64EncodePolicy or *None*.'
    defaultValue: None
    types:
    - <xref:azure.storage.queue.BinaryBase64EncodePolicy>
    - <xref:azure.storage.queue.TextBase64EncodePolicy>
    - <xref:None>
  - name: message_decode_policy
    description: 'The decoding policy to use on incoming messages.

      Default value is not to decode messages. Other options include ~azure.storage.queue.TextBase64DecodePolicy,

      ~azure.storage.queue.BinaryBase64DecodePolicy or *None*.'
    defaultValue: None
    types:
    - <xref:azure.storage.queue.BinaryBase64DecodePolicy>
    - <xref:azure.storage.queue.TextBase64DecodePolicy>
    - <xref:None>
  - name: audience
    description: 'The audience to use when requesting tokens for Azure Active Directory

      authentication. Only has an effect when credential is of type TokenCredential.
      The value could be

      [https://storage.azure.com/](https://storage.azure.com/) (default) or [https:/](https:/)/<account>.queue.core.windows.net.'
    defaultValue: None
    types:
    - <xref:str>
examples:
- "Create the queue client with url and credential.<!--[!code-python[Main](les\\queue_samples_message.py\
  \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
  : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\x64\\\
  \\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
  \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
  : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
  linenos\": false} -->\n\n````python\n\n   token_auth_queue = QueueClient.from_queue_url(queue_url=queue.url,\
  \ credential=sas_token)\n\n   ````\n"
methods:
- uid: azure.storage.queue.QueueClient.clear_messages
  name: clear_messages
  summary: Deletes all messages from the specified queue.
  signature: 'clear_messages(*, timeout: int | None = None, **kwargs: Any) -> None'
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  examples:
  - "Clears all messages.<!--[!code-python[Main](les\\queue_samples_message.py )]-->\n\
    \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   queue.clear_messages()\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.close
  name: close
  summary: 'This method is to close the sockets opened by the client.

    It need not be used when using with a context manager.'
  signature: close() -> None
  return:
    description: None
    types:
    - <xref:None>
- uid: azure.storage.queue.QueueClient.create_queue
  name: create_queue
  summary: 'Creates a new queue in the storage account.


    If a queue with the same name already exists, the operation fails with

    a *ResourceExistsError*.'
  signature: 'create_queue(*, metadata: Dict[str, str] | None = None, timeout: int
    | None = None, **kwargs: Any) -> None'
  keywordOnlyParameters:
  - name: metadata
    description: 'A dict containing name-value pairs to associate with the queue as

      metadata. Note that metadata names preserve the case with which they

      were created, but are case-insensitive when set or read.'
    defaultValue: None
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:str>]
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: None or the result of cls(response)
    types:
    - <xref:None>
  exceptions:
  - type: StorageErrorException
  examples:
  - "Create a queue.<!--[!code-python[Main](les\\queue_samples_hello_world.py )]-->\n\
    \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_hello_world.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   queue.create_queue()\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.delete_message
  name: delete_message
  summary: 'Deletes the specified message.


    Normally after a client retrieves a message with the receive messages operation,

    the client is expected to process and delete the message. To delete the

    message, you must have the message object itself, or two items of data: id and
    pop_receipt.

    The id is returned from the previous receive_messages operation. The

    pop_receipt is returned from the most recent <xref:azure.storage.queue.QueueClient.receive_messages>
    or

    <xref:azure.storage.queue.QueueClient.update_message> operation. In order for
    the delete_message operation

    to succeed, the pop_receipt specified on the request must match the

    pop_receipt returned from the <xref:azure.storage.queue.QueueClient.receive_messages>
    or <xref:azure.storage.queue.QueueClient.update_message>

    operation.'
  signature: 'delete_message(message: str | QueueMessage, pop_receipt: str | None
    = None, *, timeout: int | None = None, **kwargs: Any) -> None'
  parameters:
  - name: message
    description: The message object or id identifying the message to delete.
    isRequired: true
    types:
    - <xref:str>
    - <xref:azure.storage.queue.QueueMessage>
  - name: pop_receipt
    description: 'A valid pop receipt value returned from an earlier call

      to the <xref:azure.storage.queue.QueueClient.receive_messages> or <xref:azure.storage.queue.QueueClient.update_message>.'
    defaultValue: None
    types:
    - <xref:str>
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  examples:
  - "Delete a message.<!--[!code-python[Main](les\\queue_samples_message.py )]-->\n\
    \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   # Get the message at the front of the\
    \ queue\n   msg = next(queue.receive_messages())\n\n   # Delete the specified\
    \ message\n   queue.delete_message(msg)\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.delete_queue
  name: delete_queue
  summary: 'Deletes the specified queue and any messages it contains.


    When a queue is successfully deleted, it is immediately marked for deletion

    and is no longer accessible to clients. The queue is later removed from

    the Queue service during garbage collection.


    Note that deleting a queue is likely to take at least 40 seconds to complete.

    If an operation is attempted against the queue while it was being deleted,

    an ~azure.core.exceptions.HttpResponseError will be thrown.'
  signature: 'delete_queue(*, timeout: int | None = None, **kwargs: Any) -> None'
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    types:
    - <xref:None>
  examples:
  - "Delete a queue.<!--[!code-python[Main](les\\queue_samples_hello_world.py )]-->\n\
    \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_hello_world.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   queue.delete_queue()\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.from_connection_string
  name: from_connection_string
  summary: Create QueueClient from a Connection String.
  signature: 'from_connection_string(conn_str: str, queue_name: str, credential: str
    | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential
    | None = None, *, api_version: str | None = None, secondary_hostname: str | None
    = None, message_encode_policy: BinaryBase64EncodePolicy | TextBase64EncodePolicy
    | None = None, message_decode_policy: BinaryBase64DecodePolicy | TextBase64DecodePolicy
    | None = None, audience: str | None = None, **kwargs: Any) -> Self'
  parameters:
  - name: conn_str
    description: A connection string to an Azure Storage account.
    isRequired: true
    types:
    - <xref:str>
  - name: queue_name
    description: The queue name.
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: 'The credentials with which to authenticate. This is optional if
      the

      account URL already has a SAS token, or the connection string already has shared

      access key values. The value can be a SAS token string,

      an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials,

      an account shared access key, or an instance of a TokenCredentials class from
      azure.identity.

      Credentials provided here will take precedence over those in the connection
      string.

      If using an instance of AzureNamedKeyCredential, "name" should be the storage
      account name, and "key"

      should be the storage account key.'
    defaultValue: None
    types:
    - <xref:azure.core.credentials.AzureNamedKeyCredential>
    - <xref:azure.core.credentials.AzureSasCredential>
    - <xref:azure.core.credentials.TokenCredential>
    - <xref:str>
    - <xref:dict>[<xref:str>, <xref:str>]
    - <xref:None>
  keywordOnlyParameters:
  - name: api_version
    description: 'The Storage API version to use for requests. Default value is the
      most recent service version that is

      compatible with the current SDK. Setting to an older version may result in reduced
      feature compatibility.'
    defaultValue: None
    types:
    - <xref:str>
  - name: secondary_hostname
    description: The hostname of the secondary endpoint.
    defaultValue: None
    types:
    - <xref:str>
  - name: message_encode_policy
    description: 'The encoding policy to use on outgoing messages.

      Default is not to encode messages. Other options include ~azure.storage.queue.TextBase64EncodePolicy,

      ~azure.storage.queue.BinaryBase64EncodePolicy or *None*.'
    defaultValue: None
    types:
    - <xref:azure.storage.queue.BinaryBase64EncodePolicy>
    - <xref:azure.storage.queue.TextBase64EncodePolicy>
    - <xref:None>
  - name: message_decode_policy
    description: 'The decoding policy to use on incoming messages.

      Default value is not to decode messages. Other options include ~azure.storage.queue.TextBase64DecodePolicy,

      ~azure.storage.queue.BinaryBase64DecodePolicy or *None*.'
    defaultValue: None
    types:
    - <xref:azure.storage.queue.BinaryBase64DecodePolicy>
    - <xref:azure.storage.queue.TextBase64DecodePolicy>
    - <xref:None>
  - name: audience
    description: 'The audience to use when requesting tokens for Azure Active Directory

      authentication. Only has an effect when credential is of type TokenCredential.
      The value could be

      [https://storage.azure.com/](https://storage.azure.com/) (default) or [https:/](https:/)/<account>.queue.core.windows.net.'
    defaultValue: None
    types:
    - <xref:str>
  return:
    description: A queue client.
    types:
    - <xref:azure.storage.queue.QueueClient>
  examples:
  - "Create the queue client from connection string.<!--[!code-python[Main](les\\\
    queue_samples_message.py )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\"\
    : [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\\
    ToolCache\\\\Python\\\\3.12.10\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\\
    dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\\samples\\\\queue_samples_message.py\"\
    , \"xml:space\": \"preserve\", \"force\": false, \"language\": \"python\", \"\
    highlight_args\": {\"linenostart\": 1}, \"linenos\": false} -->\n\n````python\n\
    \n   from azure.storage.queue import QueueClient\n\n   queue = QueueClient.from_connection_string(self.connection_string,\
    \ \"myqueue1\")\n   if queue.account_name is None:\n       print(\"Connection\
    \ string did not provide an account name.\" + \"\\n\" + \"Test: set_access_policy\"\
    )\n       sys.exit(1)\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.from_queue_url
  name: from_queue_url
  summary: A client to interact with a specific Queue.
  signature: 'from_queue_url(queue_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential
    | AzureSasCredential | TokenCredential | None = None, *, api_version: str | None
    = None, secondary_hostname: str | None = None, message_encode_policy: BinaryBase64EncodePolicy
    | TextBase64EncodePolicy | None = None, message_decode_policy: BinaryBase64DecodePolicy
    | TextBase64DecodePolicy | None = None, audience: str | None = None, **kwargs:
    Any) -> Self'
  parameters:
  - name: queue_url
    description: The full URI to the queue, including SAS token if used.
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: 'The credentials with which to authenticate. This is optional if
      the

      account URL already has a SAS token. The value can be a SAS token string,

      an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials,

      an account shared access key, or an instance of a TokenCredentials class from
      azure.identity.

      If the resource URI already contains a SAS token, this will be ignored in favor
      of an explicit credential

      - except in the case of AzureSasCredential, where the conflicting SAS tokens
      will raise a ValueError.

      If using an instance of AzureNamedKeyCredential, "name" should be the storage
      account name, and "key"

      should be the storage account key.'
    defaultValue: None
    types:
    - <xref:azure.core.credentials.AzureNamedKeyCredential>
    - <xref:azure.core.credentials.AzureSasCredential>
    - <xref:azure.core.credentials.TokenCredential>
    - <xref:str>
    - <xref:dict>[<xref:str>, <xref:str>]
    - <xref:None>
  keywordOnlyParameters:
  - name: api_version
    description: 'The Storage API version to use for requests. Default value is the
      most recent service version that is

      compatible with the current SDK. Setting to an older version may result in reduced
      feature compatibility.'
    defaultValue: None
    types:
    - <xref:str>
  - name: secondary_hostname
    description: The hostname of the secondary endpoint.
    defaultValue: None
    types:
    - <xref:str>
  - name: message_encode_policy
    description: 'The encoding policy to use on outgoing messages.

      Default is not to encode messages. Other options include ~azure.storage.queue.TextBase64EncodePolicy,

      ~azure.storage.queue.BinaryBase64EncodePolicy or *None*.'
    defaultValue: None
    types:
    - <xref:azure.storage.queue.BinaryBase64EncodePolicy>
    - <xref:azure.storage.queue.TextBase64EncodePolicy>
    - <xref:None>
  - name: message_decode_policy
    description: 'The decoding policy to use on incoming messages.

      Default value is not to decode messages. Other options include ~azure.storage.queue.TextBase64DecodePolicy,

      ~azure.storage.queue.BinaryBase64DecodePolicy or *None*.'
    defaultValue: None
    types:
    - <xref:azure.storage.queue.BinaryBase64DecodePolicy>
    - <xref:azure.storage.queue.TextBase64DecodePolicy>
    - <xref:None>
  - name: audience
    description: 'The audience to use when requesting tokens for Azure Active Directory

      authentication. Only has an effect when credential is of type TokenCredential.
      The value could be

      [https://storage.azure.com/](https://storage.azure.com/) (default) or [https:/](https:/)/<account>.queue.core.windows.net.'
    defaultValue: None
    types:
    - <xref:str>
  return:
    description: A queue client.
    types:
    - <xref:azure.storage.queue.QueueClient>
- uid: azure.storage.queue.QueueClient.get_queue_access_policy
  name: get_queue_access_policy
  summary: 'Returns details about any stored access policies specified on the

    queue that may be used with Shared Access Signatures.'
  signature: 'get_queue_access_policy(*, timeout: int | None = None, **kwargs: Any)
    -> Dict[str, AccessPolicy]'
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: A dictionary of access policies associated with the queue.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:azure.storage.queue.AccessPolicy>]
- uid: azure.storage.queue.QueueClient.get_queue_properties
  name: get_queue_properties
  summary: 'Returns all user-defined metadata for the specified queue.


    The data returned does not include the queue''s list of messages.'
  signature: 'get_queue_properties(*, timeout: int | None = None, **kwargs: Any) ->
    QueueProperties'
  keywordOnlyParameters:
  - name: timeout
    description: The timeout parameter is expressed in seconds.
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: User-defined metadata for the queue.
    types:
    - <xref:azure.storage.queue.QueueProperties>
  examples:
  - "Get the properties on the queue.<!--[!code-python[Main](les\\queue_samples_message.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\\
    3.12.10\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   properties = queue.get_queue_properties().metadata\n\
    \n   ````\n"
- uid: azure.storage.queue.QueueClient.peek_messages
  name: peek_messages
  summary: 'Retrieves one or more messages from the front of the queue, but does

    not alter the visibility of the message.


    Only messages that are visible may be retrieved. When a message is retrieved

    for the first time with a call to <xref:azure.storage.queue.QueueClient.receive_messages>,
    its dequeue_count property

    is set to 1. If it is not deleted and is subsequently retrieved again, the

    dequeue_count property is incremented. The client may use this value to

    determine how many times a message has been retrieved. Note that a call

    to peek_messages does not increment the value of dequeue_count, but returns

    this value for the client to read.


    If the key-encryption-key or resolver field is set on the local service object,

    the messages will be decrypted before being returned.'
  signature: 'peek_messages(max_messages: int | None = None, *, timeout: int | None
    = None, **kwargs: Any) -> List[QueueMessage]'
  parameters:
  - name: max_messages
    description: 'A nonzero integer value that specifies the number of

      messages to peek from the queue, up to a maximum of 32. By default,

      a single message is peeked from the queue with this operation.'
    defaultValue: None
    types:
    - <xref:int>
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: 'A list of ~azure.storage.queue.QueueMessage objects. Note that

      next_visible_on and pop_receipt will not be populated as peek does

      not pop the message and can only retrieve already visible messages.'
    types:
    - <xref:typing.List>[<xref:azure.storage.queue.QueueMessage>]
  examples:
  - "Peek messages.<!--[!code-python[Main](les\\queue_samples_message.py )]-->\n\n\
    <!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   # Peek at one message at the front of\
    \ the queue\n   msg = queue.peek_messages()\n\n   # Peek at the last 5 messages\n\
    \   messages = queue.peek_messages(max_messages=5)\n\n   # Print the last 5 messages\n\
    \   for message in messages:\n       print(message.content)\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.receive_message
  name: receive_message
  summary: 'Removes one message from the front of the queue.


    When the message is retrieved from the queue, the response includes the message

    content and a pop_receipt value, which is required to delete the message.

    The message is not automatically deleted from the queue, but after it has

    been retrieved, it is not visible to other clients for the time interval

    specified by the visibility_timeout parameter.


    If the key-encryption-key or resolver field is set on the local service object,
    the message will be

    decrypted before being returned.'
  signature: 'receive_message(*, visibility_timeout: int | None = None, timeout: int
    | None = None, **kwargs: Any) -> QueueMessage | None'
  keywordOnlyParameters:
  - name: visibility_timeout
    description: 'If not specified, the default value is 30. Specifies the

      new visibility timeout value, in seconds, relative to server time.

      The value must be larger than or equal to 1, and cannot be

      larger than 7 days. The visibility timeout of a message cannot be

      set to a value later than the expiry time. visibility_timeout

      should be set to a value smaller than the time-to-live value.'
    defaultValue: None
    types:
    - <xref:int>
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: Returns a message from the Queue or None if the Queue is empty.
    types:
    - <xref:azure.storage.queue.QueueMessage>
    - <xref:None>
  examples:
  - "Receive one message from the queue.<!--[!code-python[Main](les\\queue_samples_message.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\\
    3.12.10\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   # Pop two messages from the front of\
    \ the queue\n   message1 = queue.receive_message()\n   message2 = queue.receive_message()\n\
    \   # We should see message 3 if we peek\n   message3 = queue.peek_messages()[0]\n\
    \n   if not message1 or not message2 or not message3:\n       raise ValueError(\"\
    One of the messages are None.\")\n\n   print(message1.content)\n   print(message2.content)\n\
    \   print(message3.content)\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.receive_messages
  name: receive_messages
  summary: 'Removes one or more messages from the front of the queue.


    When a message is retrieved from the queue, the response includes the message

    content and a pop_receipt value, which is required to delete the message.

    The message is not automatically deleted from the queue, but after it has

    been retrieved, it is not visible to other clients for the time interval

    specified by the visibility_timeout parameter. The iterator will continuously

    fetch messages until the queue is empty or max_messages is reached (if max_messages

    is set).


    If the key-encryption-key or resolver field is set on the local service object,
    the messages will be

    decrypted before being returned.'
  signature: 'receive_messages(*, messages_per_page: int | None = None, visibility_timeout:
    int | None = None, max_messages: int | None = None, timeout: int | None = None,
    **kwargs: Any) -> ItemPaged[QueueMessage]'
  keywordOnlyParameters:
  - name: visibility_timeout
    description: 'If not specified, the default value is 30. Specifies the

      new visibility timeout value, in seconds, relative to server time.

      The value must be larger than or equal to 1, and cannot be

      larger than 7 days. The visibility timeout of a message cannot be

      set to a value later than the expiry time. visibility_timeout

      should be set to a value smaller than the time-to-live value.'
    defaultValue: None
    types:
    - <xref:int>
  - name: max_messages
    description: An integer that specifies the maximum number of messages to retrieve
      from the queue.
    defaultValue: None
    types:
    - <xref:int>
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  - name: messages_per_page
    defaultValue: None
  return:
    description: Returns a message iterator of dict-like Message objects.
    types:
    - <xref:azure.core.paging.ItemPaged>[<xref:azure.storage.queue.QueueMessage>]
  examples:
  - "Receive messages from the queue.<!--[!code-python[Main](les\\queue_samples_message.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\\
    3.12.10\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   # Receive messages one-by-one\n   messages\
    \ = queue.receive_messages()\n   for msg in messages:\n       print(msg.content)\n\
    \n   # Receive messages by batch\n   messages = queue.receive_messages(messages_per_page=5)\n\
    \   for msg_batch in messages.by_page():\n       for msg in msg_batch:\n     \
    \      print(msg.content)\n           queue.delete_message(msg)\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.send_message
  name: send_message
  summary: 'Adds a new message to the back of the message queue.


    The visibility timeout specifies the time that the message will be

    invisible. After the timeout expires, the message will become visible.

    If a visibility timeout is not specified, the default value of 0 is used.


    The message time-to-live specifies how long a message will remain in the

    queue. The message will be deleted from the queue when the time-to-live

    period expires.


    If the key-encryption-key field is set on the local service object, this method
    will

    encrypt the content before uploading.'
  signature: 'send_message(content: object | None, *, visibility_timeout: int | None
    = None, time_to_live: int | None = None, timeout: int | None = None, **kwargs:
    Any) -> QueueMessage'
  parameters:
  - name: content
    description: 'Message content. Allowed type is determined by the encode_function

      set on the service. Default is str. The encoded message can be up to

      64KB in size.'
    isRequired: true
    types:
    - <xref:typing.Optional>[<xref:object>]
  keywordOnlyParameters:
  - name: visibility_timeout
    description: 'If not specified, the default value is 0. Specifies the

      new visibility timeout value, in seconds, relative to server time.

      The value must be larger than or equal to 0, and cannot be

      larger than 7 days. The visibility timeout of a message cannot be

      set to a value later than the expiry time. visibility_timeout

      should be set to a value smaller than the time-to-live value.'
    defaultValue: None
    types:
    - <xref:int>
  - name: time_to_live
    description: 'Specifies the time-to-live interval for the message, in

      seconds. The time-to-live may be any positive number or -1 for infinity. If
      this

      parameter is omitted, the default time-to-live is 7 days.'
    defaultValue: None
    types:
    - <xref:int>
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: 'A ~azure.storage.queue.QueueMessage object.

      This object is also populated with the content, although it is not

      returned from the service.'
    types:
    - <xref:azure.storage.queue.QueueMessage>
  examples:
  - "Send messages.<!--[!code-python[Main](les\\queue_samples_message.py )]-->\n\n\
    <!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   queue.send_message(\"message1\")\n \
    \  queue.send_message(\"message2\", visibility_timeout=30)  # wait 30s before\
    \ becoming visible\n   queue.send_message(\"message3\")\n   queue.send_message(\"\
    message4\")\n   queue.send_message(\"message5\")\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.set_queue_access_policy
  name: set_queue_access_policy
  summary: 'Sets stored access policies for the queue that may be used with Shared

    Access Signatures.


    When you set permissions for a queue, the existing permissions are replaced.

    To update the queue''s permissions, call <xref:azure.storage.queue.QueueClient.get_queue_access_policy>
    to fetch

    all access policies associated with the queue, modify the access policy

    that you wish to change, and then call this function with the complete

    set of data to perform the update.


    When you establish a stored access policy on a queue, it may take up to

    30 seconds to take effect. During this interval, a shared access signature

    that is associated with the stored access policy will throw an

    ~azure.core.exceptions.HttpResponseError until the access policy becomes active.'
  signature: 'set_queue_access_policy(signed_identifiers: Dict[str, AccessPolicy],
    *, timeout: int | None = None, **kwargs: Any) -> None'
  parameters:
  - name: signed_identifiers
    description: 'SignedIdentifier access policies to associate with the queue.

      This may contain up to 5 elements. An empty dict

      will clear the access policies set on the service.'
    isRequired: true
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:azure.storage.queue.AccessPolicy>]
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  examples:
  - "Set an access policy on the queue.<!--[!code-python[Main](les\\queue_samples_message.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\\
    3.12.10\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   # Create an access policy\n   from azure.storage.queue\
    \ import AccessPolicy, QueueSasPermissions\n\n   access_policy = AccessPolicy()\n\
    \   access_policy.start = datetime.utcnow() - timedelta(hours=1)\n   access_policy.expiry\
    \ = datetime.utcnow() + timedelta(hours=1)\n   access_policy.permission = QueueSasPermissions(read=True)\n\
    \   identifiers = {\"my-access-policy-id\": access_policy}\n\n   # Set the access\
    \ policy\n   queue.set_queue_access_policy(identifiers)\n\n   ````\n"
- uid: azure.storage.queue.QueueClient.set_queue_metadata
  name: set_queue_metadata
  summary: 'Sets user-defined metadata on the specified queue.


    Metadata is associated with the queue as name-value pairs.'
  signature: 'set_queue_metadata(metadata: Dict[str, str] | None = None, *, timeout:
    int | None = None, **kwargs: Any) -> Dict[str, Any]'
  parameters:
  - name: metadata
    description: 'A dict containing name-value pairs to associate with the

      queue as metadata.'
    defaultValue: None
    types:
    - <xref:typing.Optional>[<xref:typing.Dict>[<xref:str>, <xref:str>]]
  keywordOnlyParameters:
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: A dictionary of response headers.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:typing.Any>]
  examples:
  - "Set metadata on the queue.<!--[!code-python[Main](les\\queue_samples_message.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\\
    3.12.10\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   metadata = {\"foo\": \"val1\", \"bar\"\
    : \"val2\", \"baz\": \"val3\"}\n   queue.set_queue_metadata(metadata=metadata)\n\
    \n   ````\n"
- uid: azure.storage.queue.QueueClient.update_message
  name: update_message
  summary: 'Updates the visibility timeout of a message. You can also use this

    operation to update the contents of a message.


    This operation can be used to continually extend the invisibility of a

    queue message. This functionality can be useful if you want a worker role

    to "lease" a queue message. For example, if a worker role calls <xref:azure.storage.queue.QueueClient.receive_messages>

    and recognizes that it needs more time to process a message, it can

    continually extend the message''s invisibility until it is processed. If

    the worker role were to fail during processing, eventually the message

    would become visible again and another worker role could process it.


    If the key-encryption-key field is set on the local service object, this method
    will

    encrypt the content before uploading.'
  signature: 'update_message(message: str | QueueMessage, pop_receipt: str | None
    = None, content: object | None = None, *, visibility_timeout: int | None = None,
    timeout: int | None = None, **kwargs: Any) -> QueueMessage'
  parameters:
  - name: message
    description: The message object or id identifying the message to update.
    isRequired: true
    types:
    - <xref:str>
    - <xref:azure.storage.queue.QueueMessage>
  - name: pop_receipt
    description: 'A valid pop receipt value returned from an earlier call

      to the <xref:azure.storage.queue.QueueClient.receive_messages> or <xref:azure.storage.queue.QueueClient.update_message>
      operation.'
    defaultValue: None
    types:
    - <xref:str>
  - name: content
    description: 'Message content. Allowed type is determined by the encode_function

      set on the service. Default is str.'
    defaultValue: None
    types:
    - <xref:typing.Optional>[<xref:object>]
  keywordOnlyParameters:
  - name: visibility_timeout
    description: 'Specifies the new visibility timeout value, in seconds,

      relative to server time. The new value must be larger than or equal

      to 0, and cannot be larger than 7 days. The visibility timeout of a

      message cannot be set to a value later than the expiry time. A

      message can be updated until it has been deleted or has expired.

      The message object or message id identifying the message to update.'
    defaultValue: None
    types:
    - <xref:int>
  - name: timeout
    description: 'Sets the server-side timeout for the operation in seconds. For more
      details see

      [https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations](https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations).

      This value is not tracked or validated on the client. To configure client-side
      network timesouts

      see [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue#other-client--per-operation-configuration).'
    defaultValue: None
    types:
    - <xref:int>
  return:
    description: 'A ~azure.storage.queue.QueueMessage object. For convenience,

      this object is also populated with the content, although it is not returned
      by the service.'
    types:
    - <xref:azure.storage.queue.QueueMessage>
  examples:
  - "Update a message.<!--[!code-python[Main](les\\queue_samples_message.py )]-->\n\
    \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
    : [], \"backrefs\": [], \"source\": \"C:\\\\ToolCache\\\\Python\\\\3.12.10\\\\\
    x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\276\\\\azure_storage_queue-12.16.0\\\
    \\samples\\\\queue_samples_message.py\", \"xml:space\": \"preserve\", \"force\"\
    : false, \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"\
    linenos\": false} -->\n\n````python\n\n   # Send a message\n   queue.send_message(\"\
    update me\")\n\n   # Receive the message\n   messages = queue.receive_messages()\n\
    \n   # Update the message\n   list_result = next(messages)\n   message = queue.update_message(\n\
    \       list_result.id, pop_receipt=list_result.pop_receipt, visibility_timeout=0,\
    \ content=\"updated\"\n   )\n\n   ````\n"
attributes:
- uid: azure.storage.queue.QueueClient.api_version
  name: api_version
  summary: The version of the Storage API used for requests.
  return:
    types:
    - <xref:str>
- uid: azure.storage.queue.QueueClient.location_mode
  name: location_mode
  summary: 'The location mode that the client is currently using.


    By default this will be "primary". Options include "primary" and "secondary".'
  return:
    description: The current location mode.
    types:
    - <xref:str>
- uid: azure.storage.queue.QueueClient.primary_endpoint
  name: primary_endpoint
  summary: The full primary endpoint URL.
  return:
    description: The full primary endpoint URL.
    types:
    - <xref:str>
- uid: azure.storage.queue.QueueClient.primary_hostname
  name: primary_hostname
  summary: The hostname of the primary endpoint.
  return:
    description: The hostname of the primary endpoint.
    types:
    - <xref:str>
- uid: azure.storage.queue.QueueClient.secondary_endpoint
  name: secondary_endpoint
  summary: 'The full secondary endpoint URL if configured.


    If not available a ValueError will be raised. To explicitly specify a secondary
    hostname, use the optional

    *secondary_hostname* keyword argument on instantiation.'
  return:
    description: The full secondary endpoint URL.
    types:
    - <xref:str>
  exceptions:
  - type: ValueError
    description: If no secondary endpoint is configured.
- uid: azure.storage.queue.QueueClient.secondary_hostname
  name: secondary_hostname
  summary: 'The hostname of the secondary endpoint.


    If not available this will be None. To explicitly specify a secondary hostname,
    use the optional

    *secondary_hostname* keyword argument on instantiation.'
  return:
    description: The hostname of the secondary endpoint, or None if not configured.
    types:
    - <xref:typing.Optional>[<xref:str>]
- uid: azure.storage.queue.QueueClient.url
  name: url
  summary: 'The full endpoint URL to this entity, including SAS token if used.


    This could be either the primary endpoint,

    or the secondary endpoint depending on the current <xref:azure.storage.queue.QueueClient.location_mode>.'
  return:
    description: The full endpoint URL to this entity, including SAS token if used.
    types:
    - <xref:str>
- uid: azure.storage.queue.QueueClient.queue_name
  name: queue_name
  signature: 'queue_name: str'