azure.servicebus.ServiceBusSender.yml

### YamlMime:PythonClass
uid: azure.servicebus.ServiceBusSender
name: ServiceBusSender
fullName: azure.servicebus.ServiceBusSender
module: azure.servicebus
inheritances:
- azure.servicebus._base_handler.BaseHandler
- azure.servicebus._servicebus_sender.SenderMixin
summary: 'The ServiceBusSender class defines a high level interface for

  sending messages to the Azure Service Bus Queue or Topic.


  **Please use the `get_<queue/topic>_sender` method of ~azure.servicebus.ServiceBusClient
  to create a

  ServiceBusSender instance.**'
constructor:
  syntax: 'ServiceBusSender(fully_qualified_namespace: str, credential: TokenCredential
    | AzureSasCredential | AzureNamedKeyCredential, *, queue_name: str | None = None,
    topic_name: str | None = None, **kwargs: Any)'
  parameters:
  - name: fully_qualified_namespace
    description: 'The fully qualified host name for the Service Bus namespace.

      The namespace format is: *<yournamespace>.servicebus.windows.net*.'
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: 'The credential object used for authentication which

      implements a particular interface for getting tokens. It accepts

      credential objects generated by the azure-identity library and objects that
      implement the

      *get_token(self, *scopes)* method, or alternatively, an AzureSasCredential can
      be provided too.'
    isRequired: true
    types:
    - <xref:azure.core.credentials.TokenCredential>
    - <xref:azure.core.credentials.AzureSasCredential>
    - <xref:azure.core.credentials.AzureNamedKeyCredential>
  keywordOnlyParameters:
  - name: queue_name
    description: The path of specific Service Bus Queue the client connects to.
    types:
    - <xref:str>
  - name: topic_name
    description: The path of specific Service Bus Topic the client connects to.
    types:
    - <xref:str>
  - name: logging_enable
    description: Whether to output network trace logs to the logger. Default is *False*.
    types:
    - <xref:bool>
  - name: transport_type
    description: 'The type of transport protocol that will be used for communicating
      with

      the Service Bus service. Default is *TransportType.Amqp*.'
    types:
    - <xref:azure.servicebus.TransportType>
  - name: http_proxy
    description: 'HTTP proxy settings. This must be a dictionary with the following

      keys: *''proxy_hostname''* (str value) and *''proxy_port''* (int value).

      Additionally the following keys may also be present: *''username'', ''password''*.'
    types:
    - <xref:typing.Dict>
  - name: user_agent
    description: If specified, this will be added in front of the built-in user agent
      string.
    types:
    - <xref:str>
  - name: client_identifier
    description: 'A string-based identifier to uniquely identify the client instance.

      Service Bus will associate it with some error messages for easier correlation
      of errors.

      If not specified, a unique id will be generated.'
    types:
    - <xref:str>
  - name: socket_timeout
    description: 'The time in seconds that the underlying socket on the connection
      should

      wait when sending and receiving data before timing out. The default value is
      0.2 for TransportType.Amqp

      and 1 for TransportType.AmqpOverWebsocket. If connection errors are occurring
      due to write timing out,

      a larger than default value may need to be passed in.'
    types:
    - <xref:float>
variables:
- description: 'The fully qualified host name for the Service Bus namespace.

    The namespace format is: *<yournamespace>.servicebus.windows.net*.'
  name: fully_qualified_namespace
  types:
  - <xref:str>
- description: The name of the entity that the client connects to.
  name: entity_name
  types:
  - <xref:str>
methods:
- uid: azure.servicebus.ServiceBusSender.cancel_scheduled_messages
  name: cancel_scheduled_messages
  summary: Cancel one or more messages that have previously been scheduled and are
    still pending.
  signature: 'cancel_scheduled_messages(sequence_numbers: int | List[int], *, timeout:
    float | None = None, **kwargs: Any) -> None'
  parameters:
  - name: sequence_numbers
    description: The sequence numbers of the scheduled messages.
    isRequired: true
    types:
    - <xref:int>
    - <xref:list>[<xref:int>]
  keywordOnlyParameters:
  - name: timeout
    description: 'The total operation timeout in seconds including all the retries.
      The value must be

      greater than 0 if specified. The default value is None, meaning no timeout.'
    types:
    - <xref:float>
  return:
    types:
    - <xref:None>
  exceptions:
  - type: azure.servicebus.exceptions.ServiceBusError if messages cancellation failed
      due to message alreadycancelled or enqueued.
  examples:
  - "Cancelling messages scheduled to be sent in future<!--[!code-python[Main](les\\\
    sync_samples\\sample_code_servicebus.py )]-->\n\n<!-- literal_block {\"ids\":\
    \ [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"source\"\
    : \"C:\\\\hostedtoolcache\\\\windows\\\\Python\\\\3.11.9\\\\x64\\\\Lib\\\\site-packages\\\
    \\py2docfx\\\\dist_temp\\\\221\\\\azure-servicebus-7.12.2\\\\samples\\\\sync_samples\\\
    \\sample_code_servicebus.py\", \"xml:space\": \"preserve\", \"force\": false,\
    \ \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"linenos\"\
    : false} -->\n\n````python\n\n   with servicebus_sender:\n       servicebus_sender.cancel_scheduled_messages(sequence_nums)\n\
    \n   ````\n"
- uid: azure.servicebus.ServiceBusSender.close
  name: close
  summary: 'Close down the handler links (and connection if the handler uses a separate
    connection).


    If the handler has already closed, this operation will do nothing.'
  signature: close() -> None
  return:
    types:
    - <xref:None>
- uid: azure.servicebus.ServiceBusSender.create_message_batch
  name: create_message_batch
  summary: 'Create a ServiceBusMessageBatch object with the max size of all content
    being constrained by

    max_size_in_bytes. The max_size should be no greater than the max allowed message
    size defined by the service.'
  signature: 'create_message_batch(max_size_in_bytes: int | None = None) -> ServiceBusMessageBatch'
  parameters:
  - name: max_size_in_bytes
    description: 'The maximum size of bytes data that a ServiceBusMessageBatch object
      can

      hold. By default, the value is determined by your Service Bus tier.'
    defaultValue: None
    types:
    - <xref:typing.Optional>[<xref:int>]
  return:
    description: A ServiceBusMessageBatch object
    types:
    - <xref:azure.servicebus.ServiceBusMessageBatch>
  examples:
  - "Create ServiceBusMessageBatch object within limited size<!--[!code-python[Main](les\\\
    sync_samples\\sample_code_servicebus.py )]-->\n\n<!-- literal_block {\"ids\":\
    \ [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"source\"\
    : \"C:\\\\hostedtoolcache\\\\windows\\\\Python\\\\3.11.9\\\\x64\\\\Lib\\\\site-packages\\\
    \\py2docfx\\\\dist_temp\\\\221\\\\azure-servicebus-7.12.2\\\\samples\\\\sync_samples\\\
    \\sample_code_servicebus.py\", \"xml:space\": \"preserve\", \"force\": false,\
    \ \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"linenos\"\
    : false} -->\n\n````python\n\n   with servicebus_sender:\n       batch_message\
    \ = servicebus_sender.create_message_batch()\n       batch_message.add_message(ServiceBusMessage(\"\
    Single message inside batch\"))\n\n   ````\n"
- uid: azure.servicebus.ServiceBusSender.schedule_messages
  name: schedule_messages
  summary: 'Send Message or multiple Messages to be enqueued at a specific time.

    Returns a list of the sequence numbers of the enqueued messages.'
  signature: 'schedule_messages(messages: MessageTypes, schedule_time_utc: datetime,
    *, timeout: float | None = None, **kwargs: Any) -> List[int]'
  parameters:
  - name: messages
    description: The message or list of messages to schedule.
    isRequired: true
    types:
    - <xref:typing.Union>[<xref:azure.servicebus.ServiceBusMessage>, <xref:azure.servicebus.amqp.AmqpAnnotatedMessage>,
      <xref:typing.List>[<xref:typing.Union>[<xref:azure.servicebus.ServiceBusMessage>,
      <xref:azure.servicebus.amqp.AmqpAnnotatedMessage>]]]
  - name: schedule_time_utc
    description: The utc date and time to enqueue the messages.
    isRequired: true
    types:
    - <xref:datetime.datetime>
  keywordOnlyParameters:
  - name: timeout
    description: 'The total operation timeout in seconds including all the retries.
      The value must be

      greater than 0 if specified. The default value is None, meaning no timeout.'
    types:
    - <xref:float>
  return:
    description: A list of the sequence numbers of the enqueued messages.
    types:
    - <xref:list>[<xref:int>]
  examples:
  - "Schedule a message to be sent in future<!--[!code-python[Main](les\\sync_samples\\\
    sample_code_servicebus.py )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\"\
    : [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\\
    hostedtoolcache\\\\windows\\\\Python\\\\3.11.9\\\\x64\\\\Lib\\\\site-packages\\\
    \\py2docfx\\\\dist_temp\\\\221\\\\azure-servicebus-7.12.2\\\\samples\\\\sync_samples\\\
    \\sample_code_servicebus.py\", \"xml:space\": \"preserve\", \"force\": false,\
    \ \"language\": \"python\", \"highlight_args\": {\"linenostart\": 1}, \"linenos\"\
    : false} -->\n\n````python\n\n   with servicebus_sender:\n       scheduled_time_utc\
    \ = datetime.datetime.utcnow() + datetime.timedelta(seconds=30)\n       scheduled_messages\
    \ = [ServiceBusMessage(\"Scheduled message\") for _ in range(10)]\n       sequence_nums\
    \ = servicebus_sender.schedule_messages(scheduled_messages, scheduled_time_utc)\n\
    \n   ````\n"
- uid: azure.servicebus.ServiceBusSender.send_messages
  name: send_messages
  summary: 'Sends message and blocks until acknowledgement is received or operation
    times out.


    If a list of messages was provided, attempts to send them as a single batch, throwing
    a

    *ValueError* if they cannot fit in a single batch.'
  signature: 'send_messages(message: MessageTypes | ServiceBusMessageBatch, *, timeout:
    float | None = None, **kwargs: Any) -> None'
  parameters:
  - name: message
    description: The ServiceBus message to be sent.
    isRequired: true
    types:
    - <xref:typing.Union>[<xref:azure.servicebus.ServiceBusMessage>, <xref:azure.servicebus.ServiceBusMessageBatch>,
      <xref:azure.servicebus.amqp.AmqpAnnotatedMessage>, <xref:typing.List>[<xref:typing.Union>[<xref:azure.servicebus.ServiceBusMessage>,
      <xref:azure.servicebus.amqp.AmqpAnnotatedMessage>]]]
  keywordOnlyParameters:
  - name: timeout
    description: 'The total operation timeout in seconds including all the retries.

      The value must be greater than 0 if specified. The default value is None, meaning
      no timeout.'
    types:
    - <xref:typing.Optional>[<xref:float>]
  return:
    types:
    - <xref:None>
  exceptions:
  - type: azure.servicebus.exceptions.OperationTimeoutError if sending times out.
  examples:
  - "Send message.<!--[!code-python[Main](les\\sync_samples\\sample_code_servicebus.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\hostedtoolcache\\\\windows\\\
    \\Python\\\\3.11.9\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\\
    221\\\\azure-servicebus-7.12.2\\\\samples\\\\sync_samples\\\\sample_code_servicebus.py\"\
    , \"xml:space\": \"preserve\", \"force\": false, \"language\": \"python\", \"\
    highlight_args\": {\"linenostart\": 1}, \"linenos\": false} -->\n\n````python\n\
    \n   with servicebus_sender:\n       message_send = ServiceBusMessage(\"Hello\
    \ World\")\n       servicebus_sender.send_messages(message_send)\n\n   ````\n"
attributes:
- uid: azure.servicebus.ServiceBusSender.client_identifier
  name: client_identifier
  summary: Get the ServiceBusSender client_identifier associated with the sender instance.
  return:
    types:
    - <xref:str>