Class Client (2.26.1)

A subscriber client for Google Cloud Pub/Sub.

This creates an object that is capable of subscribing to messages. Generally, you can instantiate this client with no arguments, and you get sensible defaults.

The underlying gapic API client.

.. versionchanged:: 2.10.0 Instead of a GAPIC SubscriberClient client instance, this property is a proxy object to it with the same interface.

Return the API endpoint used by the client instance.

Return whether the client has been closed and cannot be used anymore.

.. versionadded:: 2.8.0

Returns True if Open Telemetry is enabled. False otherwise.

Return the target (where the API is).

Returns the transport used by the client instance.

Return the universe domain used by the client instance.

Instantiates the subscriber client.

Acknowledges the messages associated with the ack_ids in the AcknowledgeRequest. The Pub/Sub system can remove the relevant messages from the subscription.

Acknowledging a message whose ack deadline has expired may succeed, but such a message may be redelivered later. Acknowledging a message more than once will not result in an error.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_acknowledge():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.AcknowledgeRequest(
        subscription="subscription_value",
        ack_ids=['ack_ids_value1', 'ack_ids_value2'],
    )

    # Make the request
    client.acknowledge(request=request)

Close the underlying channel to release socket resources.

After a channel has been closed, the client instance cannot be used anymore.

This method is idempotent.

Returns a fully-qualified billing_account string.

Returns a fully-qualified folder string.

Returns a fully-qualified location string.

Returns a fully-qualified organization string.

Returns a fully-qualified project string.

Creates a snapshot from the requested subscription. Snapshots are used in Seek <https://cloud.google.com/pubsub/docs/replay-overview>__ operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. If the snapshot already exists, returns ALREADY_EXISTS. If the requested subscription doesn't exist, returns NOT_FOUND. If the backlog in the subscription is too old -- and the resulting snapshot would expire in less than 1 hour -- then FAILED_PRECONDITION is returned. See also the Snapshot.expire_time field. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription, conforming to the resource name format. The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_create_snapshot():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.CreateSnapshotRequest(
        name="name_value",
        subscription="subscription_value",
    )

    # Make the request
    response = client.create_snapshot(request=request)

    # Handle the response
    print(response)

Creates a subscription to a given topic. See the resource name rules. If the subscription already exists, returns ALREADY_EXISTS. If the corresponding topic doesn't exist, returns NOT_FOUND.

If the name is not provided in the request, the server will assign a random name for this subscription on the same project as the topic, conforming to the resource name format. The generated name is populated in the returned Subscription object. Note that for REST API requests, you must specify a name in the request.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_create_subscription():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.Subscription(
        name="name_value",
        topic="topic_value",
    )

    # Make the request
    response = client.create_subscription(request=request)

    # Handle the response
    print(response)

Removes an existing snapshot. Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. When the snapshot is deleted, all messages retained in the snapshot are immediately dropped. After a snapshot is deleted, a new one may be created with the same name, but the new one has no association with the old snapshot or its subscription, unless the same subscription is specified.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_delete_snapshot():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.DeleteSnapshotRequest(
        snapshot="snapshot_value",
    )

    # Make the request
    client.delete_snapshot(request=request)

Deletes an existing subscription. All messages retained in the subscription are immediately dropped. Calls to Pull after deletion will return NOT_FOUND. After a subscription is deleted, a new one may be created with the same name, but the new one has no association with the old subscription or its topic unless the same topic is specified.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_delete_subscription():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.DeleteSubscriptionRequest(
        subscription="subscription_value",
    )

    # Make the request
    client.delete_subscription(request=request)

Creates an instance of this client using the provided credentials file.

Creates an instance of this client using the provided credentials info.

Creates an instance of this client using the provided credentials file.

Gets the IAM access control policy for a function.

Returns an empty policy if the function exists and does not have a policy set.

Deprecated. Return the API endpoint and client cert source for mutual TLS.

The client cert source is determined in the following order: (1) if GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable is not "true", the client cert source is None. (2) if client_options.client_cert_source is provided, use the provided one; if the default client cert source exists, use the default one; otherwise the client cert source is None.

The API endpoint is determined in the following order: (1) if client_options.api_endpoint if provided, use the provided one. (2) if GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable is "always", use the default mTLS endpoint; if the environment variable is "never", use the default API endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise use the default API endpoint.

More details can be found at https://google.aip.dev/auth/4114.

Gets the configuration details of a snapshot. Snapshots are used in Seek <https://cloud.google.com/pubsub/docs/replay-overview>__ operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_get_snapshot():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.GetSnapshotRequest(
        snapshot="snapshot_value",
    )

    # Make the request
    response = client.get_snapshot(request=request)

    # Handle the response
    print(response)

Gets the configuration details of a subscription.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_get_subscription():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.GetSubscriptionRequest(
        subscription="subscription_value",
    )

    # Make the request
    response = client.get_subscription(request=request)

    # Handle the response
    print(response)

Lists the existing snapshots. Snapshots are used in Seek <https://cloud.google.com/pubsub/docs/replay-overview>__ operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_list_snapshots():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.ListSnapshotsRequest(
        project="project_value",
    )

    # Make the request
    page_result = client.list_snapshots(request=request)

    # Handle the response
    for response in page_result:
        print(response)

Lists matching subscriptions.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_list_subscriptions():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.ListSubscriptionsRequest(
        project="project_value",
    )

    # Make the request
    page_result = client.list_subscriptions(request=request)

    # Handle the response
    for response in page_result:
        print(response)

Modifies the ack deadline for a specific message. This method is useful to indicate that more time is needed to process a message by the subscriber, or to make the message available for redelivery if the processing was interrupted. Note that this does not modify the subscription-level ackDeadlineSeconds used for subsequent messages.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_modify_ack_deadline():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.ModifyAckDeadlineRequest(
        subscription="subscription_value",
        ack_ids=['ack_ids_value1', 'ack_ids_value2'],
        ack_deadline_seconds=2066,
    )

    # Make the request
    client.modify_ack_deadline(request=request)

Modifies the PushConfig for a specified subscription.

This may be used to change a push subscription to a pull one (signified by an empty PushConfig) or vice versa, or change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery continuously through the call regardless of changes to the PushConfig.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_modify_push_config():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.ModifyPushConfigRequest(
        subscription="subscription_value",
    )

    # Make the request
    client.modify_push_config(request=request)

Parse a billing_account path into its component segments.

Parse a folder path into its component segments.

Parse a location path into its component segments.

Parse a organization path into its component segments.

Parse a project path into its component segments.

Parses a snapshot path into its component segments.

Parses a subscription path into its component segments.

Parses a topic path into its component segments.

Pulls messages from the server.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_pull():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.PullRequest(
        subscription="subscription_value",
        max_messages=1277,
    )

    # Make the request
    response = client.pull(request=request)

    # Handle the response
    print(response)

Seeks an existing subscription to a point in time or to a given snapshot, whichever is provided in the request. Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. Note that both the subscription and the snapshot must be on the same topic.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_seek():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.SeekRequest(
        subscription="subscription_value",
    )

    # Make the request
    response = client.seek(request=request)

    # Handle the response
    print(response)

Sets the IAM access control policy on the specified function.

Replaces any existing policy.

Returns a fully-qualified snapshot string.

Establishes a stream with the server, which sends messages down to the client. The client streams acknowledgements and ack deadline modifications back to the server. The server will close the stream and return the status on any error. The server may close the stream with status UNAVAILABLE to reassign server-side resources, in which case, the client should re-establish the stream. Flow control can be achieved by configuring the underlying RPC channel.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_streaming_pull():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.StreamingPullRequest(
        subscription="subscription_value",
        stream_ack_deadline_seconds=2813,
    )

    # This method expects an iterator which contains
    # 'pubsub_v1.StreamingPullRequest' objects
    # Here we create a generator that yields a single `request` for
    # demonstrative purposes.
    requests = [request]

    def request_generator():
        for request in requests:
            yield request

    # Make the request
    stream = client.streaming_pull(requests=request_generator())

    # Handle the response
    for response in stream:
        print(response)

Asynchronously start receiving messages on a given subscription.

This method starts a background thread to begin pulling messages from a Pub/Sub subscription and scheduling them to be processed using the provided callback.

The callback will be called with an individual xref_Message. It is the responsibility of the callback to either call ack() or nack() on the message when it finished processing. If an exception occurs in the callback during processing, the exception is logged and the message is nack() ed.

The flow_control argument can be used to control the rate of at which messages are pulled. The settings are relatively conservative by default to prevent "message hoarding" - a situation where the client pulls a large number of messages but can not process them fast enough leading it to "starve" other clients of messages. Increasing these settings may lead to faster throughput for messages that do not take a long time to process.

The use_legacy_flow_control argument disables enforcing flow control settings at the Cloud Pub/Sub server, and only the client side flow control will be enforced.

This method starts the receiver in the background and returns a Future representing its execution. Waiting on the future (calling result()) will block forever or until a non-recoverable error is encountered (such as loss of network connectivity). Cancelling the future will signal the process to shutdown gracefully and exit.

from google.cloud import pubsub_v1

subscriber_client = pubsub_v1.SubscriberClient()

# existing subscription
subscription = subscriber_client.subscription_path(
    'my-project-id', 'my-subscription')

def callback(message):
    print(message)
    message.ack()

future = subscriber_client.subscribe(
    subscription, callback)

try:
    future.result()
except KeyboardInterrupt:
    future.cancel()  # Trigger the shutdown.
    future.result()  # Block until the shutdown is complete.

Returns a fully-qualified subscription string.

Tests the specified IAM permissions against the IAM access control policy for a function.

If the function does not exist, this will return an empty set of permissions, not a NOT_FOUND error.

Returns a fully-qualified topic string.

Updates an existing snapshot by updating the fields specified in the update mask. Snapshots are used in Seek <https://cloud.google.com/pubsub/docs/replay-overview>__ operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_update_snapshot():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    request = pubsub_v1.UpdateSnapshotRequest(
    )

    # Make the request
    response = client.update_snapshot(request=request)

    # Handle the response
    print(response)

Updates an existing subscription by updating the fields specified in the update mask. Note that certain properties of a subscription, such as its topic, are not modifiable.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google import pubsub_v1

def sample_update_subscription():
    # Create a client
    client = pubsub_v1.SubscriberClient()

    # Initialize request argument(s)
    subscription = pubsub_v1.Subscription()
    subscription.name = "name_value"
    subscription.topic = "topic_value"

    request = pubsub_v1.UpdateSubscriptionRequest(
        subscription=subscription,
    )

    # Make the request
    response = client.update_subscription(request=request)

    # Handle the response
    print(response)