Client(batch_settings=(), publisher_options=(), **kwargs)A publisher client for Google Cloud Pub/Sub.
This creates an object that is capable of publishing messages. Generally, you can instantiate this client with no arguments, and you get sensible defaults.
Parameters | |
|---|---|
| Name | Description |
kwargs |
dict Example: .. code-block:: python from google.cloud import pubsub_v1 publisher_client = pubsub_v1.PublisherClient( # Optional batch_settings = pubsub_v1.types.BatchSettings( max_bytes=1024, # One kilobyte max_latency=1, # One second ), # Optional publisher_options = pubsub_v1.types.PublisherOptions( enable_message_ordering=False, flow_control=pubsub_v1.types.PublishFlowControl( message_limit=2000, limit_exceeded_behavior=pubsub_v1.types.LimitExceededBehavior.BLOCK, ), ), # Optional client_options = { "api_endpoint": REGIONAL_ENDPOINT } )
Any additional arguments provided are sent as keyword arguments to the underlying PublisherClient. Generally you should not need to set additional keyword arguments. Regional endpoints can be set via |
batch_settings |
BatchSettings
The settings for batch publishing. |
publisher_options |
PublisherOptions
The options for the publisher client. Note that enabling message ordering will override the publish retry timeout to be infinite. |
Properties
target
Return the target (where the API is).
| Returns | |
|---|---|
| Type | Description |
str | The location of the API. |
Methods
common_billing_account_path
common_billing_account_path(billing_account: str)Return a fully-qualified billing_account string.
common_folder_path
common_folder_path(folder: str)Return a fully-qualified folder string.
common_location_path
common_location_path(project: str, location: str)Return a fully-qualified location string.
common_organization_path
common_organization_path(organization: str)Return a fully-qualified organization string.
common_project_path
common_project_path(project: str)Return a fully-qualified project string.
create_topic
create_topic(request: google.cloud.pubsub_v1.types.Topic = None, *, name: str = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Creates the given topic with the given name. See the resource
name
rules <https://cloud.google.com/pubsub/docs/admin#resource_names>__.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. A topic resource. |
name |
Required. The name of the topic. It must have the format |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| A topic resource. |
delete_topic
delete_topic(request: google.cloud.pubsub_v1.types.DeleteTopicRequest = None, *, topic: str = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Deletes the topic with the given name. Returns NOT_FOUND if
the topic does not exist. After a topic is deleted, a new topic
may be created with the same name; this is an entirely new topic
with none of the old configuration or subscriptions. Existing
subscriptions to this topic are not deleted, but their topic
field is set to _deleted-topic_.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the |
topic |
Required. Name of the topic to delete. Format is |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
detach_subscription
detach_subscription(request: google.cloud.pubsub_v1.types.DetachSubscriptionRequest = None, *, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Detaches a subscription from this topic. All messages retained
in the subscription are dropped. Subsequent Pull and
StreamingPull requests will return FAILED_PRECONDITION. If
the subscription is a push subscription, pushes to the endpoint
will stop.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the DetachSubscription method. |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Response for the DetachSubscription method. Reserved for future use. |
ensure_cleanup_and_commit_timer_runs
ensure_cleanup_and_commit_timer_runs()Ensure a cleanup/commit timer thread is running.
If a cleanup/commit timer thread is already running, this does nothing.
from_service_account_file
from_service_account_file(filename, batch_settings=(), **kwargs)Creates an instance of this client using the provided credentials file.
| Parameters | |
|---|---|
| Name | Description |
filename |
str
The path to the service account private key json file. |
batch_settings |
BatchSettings
The settings for batch publishing. |
from_service_account_json
from_service_account_json(filename, batch_settings=(), **kwargs)Creates an instance of this client using the provided credentials file.
| Parameters | |
|---|---|
| Name | Description |
filename |
str
The path to the service account private key json file. |
batch_settings |
BatchSettings
The settings for batch publishing. |
get_iam_policy
get_iam_policy(request: google.iam.v1.iam_policy_pb2.GetIamPolicyRequest = None, *, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Gets the IAM access control policy for a function. Returns an empty policy if the function exists and does not have a policy set.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request message for |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Defines an Identity and Access Management (IAM) policy. It is used to specify access control policies for Cloud Platform resources. A Policy is a collection of bindings. A binding binds one or more members to a single role. Members can be user accounts, service accounts, Google groups, and domains (such as G Suite). A role is a named list of permissions (defined by IAM or configured by users). A binding can optionally specify a condition, which is a logic expression that further constrains the role binding based on attributes about the request and/or target resource. **JSON Example**:: { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": ["user:eve@example.com"], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01t00:00:00.000z')",="" }="" }="" ]="" }="" **yaml="" example**::="" bindings:="" -="" members:="" -="" user:mike@example.com="" -="" group:admins@example.com="" -="" domain:google.com="" -="" serviceaccount:my-project-id@appspot.gserviceaccount.com="" role:="" roles/resourcemanager.organizationadmin="" -="" members:="" -="" user:eve@example.com="" role:="" roles/resourcemanager.organizationviewer="" condition:="" title:="" expirable="" access="" description:="" does="" not="" grant="" access="" after="" sep="" 2020="" expression:="" request.time="">< timestamp('2020-10-01t00:00:00.000z')="" for="" a="" description="" of="" iam="" and="" its="" features,="" see="" the="">IAM developer's guide __. |
get_topic
get_topic(request: google.cloud.pubsub_v1.types.GetTopicRequest = None, *, topic: str = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Gets the configuration of a topic.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the GetTopic method. |
topic |
Required. The name of the topic to get. Format is |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| A topic resource. |
list_topic_snapshots
list_topic_snapshots(request: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest = None, *, topic: str = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Lists the names of the snapshots on this topic. 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.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the |
topic |
Required. The name of the topic that snapshots are attached to. Format is |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Response for the ListTopicSnapshots method. Iterating over this object will yield results and resolve additional pages automatically. |
list_topic_subscriptions
list_topic_subscriptions(request: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest = None, *, topic: str = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Lists the names of the attached subscriptions on this topic.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the |
topic |
Required. The name of the topic that subscriptions are attached to. Format is |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Response for the ListTopicSubscriptions method. Iterating over this object will yield results and resolve additional pages automatically. |
list_topics
list_topics(request: google.cloud.pubsub_v1.types.ListTopicsRequest = None, *, project: str = None, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Lists matching topics.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the |
project |
Required. The name of the project in which to list topics. Format is |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Response for the ListTopics method. Iterating over this object will yield results and resolve additional pages automatically. |
parse_common_billing_account_path
parse_common_billing_account_path(path: str)Parse a billing_account path into its component segments.
parse_common_folder_path
parse_common_folder_path(path: str)Parse a folder path into its component segments.
parse_common_location_path
parse_common_location_path(path: str)Parse a location path into its component segments.
parse_common_organization_path
parse_common_organization_path(path: str)Parse a organization path into its component segments.
parse_common_project_path
parse_common_project_path(path: str)Parse a project path into its component segments.
parse_subscription_path
parse_subscription_path(path: str)Parse a subscription path into its component segments.
parse_topic_path
parse_topic_path(path: str)Parse a topic path into its component segments.
publish
publish(topic, data, ordering_key='', retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, **attrs)Publish a single message.
The reason that this is so important (and why we do not try to coerce for you) is because Pub/Sub is also platform independent and there is no way to know how to decode messages properly on the other side; therefore, encoding and decoding is a required exercise for the developer.
Add the given message to this object; this will cause it to be published once the batch either has enough messages or a sufficient period of time has elapsed. This method may block if LimitExceededBehavior.BLOCK is used in the flow control settings.
.. rubric:: Example
from google.cloud import pubsub_v1 client = pubsub_v1.PublisherClient() topic = client.topic_path('[PROJECT]', '[TOPIC]') data = b'The rain in Wales falls mainly on the snails.' response = client.publish(topic, data, username='guido')
| Parameters | |
|---|---|
| Name | Description |
attrs |
Mapping[str, str]
A dictionary of attributes to be sent as metadata. (These may be text strings or byte strings.) |
topic |
str
The topic to publish messages to. |
data |
bytes
A bytestring representing the message body. This must be a bytestring. |
retry |
Optional[google.api_core.retry.Retry]
Designation of what errors, if any, should be retried. If |
| Exceptions | |
|---|---|
| Type | Description |
RuntimeError | If called after publisher has been stopped by a stop() method call. |
pubsub_v1.publisher.exceptions.MessageTooLargeError | If publishing the message would exceed the max size limit on the backend. |
resume_publish
resume_publish(topic, ordering_key)Resume publish on an ordering key that has had unrecoverable errors.
| Parameter | |
|---|---|
| Name | Description |
topic |
str
The topic to publish messages to. |
| Exceptions | |
|---|---|
| Type | Description |
RuntimeError | If called after publisher has been stopped by a stop() method call. |
ValueError | If the topic/ordering key combination has not been seen before by this client. |
set_iam_policy
set_iam_policy(request: google.iam.v1.iam_policy_pb2.SetIamPolicyRequest = None, *, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Sets the IAM access control policy on the specified function. Replaces any existing policy.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request message for |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Defines an Identity and Access Management (IAM) policy. It is used to specify access control policies for Cloud Platform resources. A Policy is a collection of bindings. A binding binds one or more members to a single role. Members can be user accounts, service accounts, Google groups, and domains (such as G Suite). A role is a named list of permissions (defined by IAM or configured by users). A binding can optionally specify a condition, which is a logic expression that further constrains the role binding based on attributes about the request and/or target resource. **JSON Example**:: { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": ["user:eve@example.com"], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01t00:00:00.000z')",="" }="" }="" ]="" }="" **yaml="" example**::="" bindings:="" -="" members:="" -="" user:mike@example.com="" -="" group:admins@example.com="" -="" domain:google.com="" -="" serviceaccount:my-project-id@appspot.gserviceaccount.com="" role:="" roles/resourcemanager.organizationadmin="" -="" members:="" -="" user:eve@example.com="" role:="" roles/resourcemanager.organizationviewer="" condition:="" title:="" expirable="" access="" description:="" does="" not="" grant="" access="" after="" sep="" 2020="" expression:="" request.time="">< timestamp('2020-10-01t00:00:00.000z')="" for="" a="" description="" of="" iam="" and="" its="" features,="" see="" the="">IAM developer's guide __. |
stop
stop()Immediately publish all outstanding messages.
Asynchronously sends all outstanding messages and
prevents future calls to publish(). Method should
be invoked prior to deleting this Client() object
in order to ensure that no pending messages are lost.
| Exceptions | |
|---|---|
| Type | Description |
RuntimeError | If called after publisher has been stopped by a stop() method call. |
subscription_path
subscription_path(project: str, subscription: str)Return a fully-qualified subscription string.
test_iam_permissions
test_iam_permissions(request: google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest = None, *, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Tests the specified 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.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request message for |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| Response message for TestIamPermissions method. |
topic_path
topic_path(project: str, topic: str)Return a fully-qualified topic string.
update_topic
update_topic(request: google.cloud.pubsub_v1.types.UpdateTopicRequest = None, *, retry: google.api_core.retry.Retry = <_MethodDefault._DEFAULT_VALUE: <object object>>, timeout: float = None, metadata: Sequence[Tuple[str, str]] = ())Updates an existing topic. Note that certain properties of a topic are not modifiable.
| Parameters | |
|---|---|
| Name | Description |
request |
The request object. Request for the UpdateTopic method. |
retry |
google.api_core.retry.Retry
Designation of what errors, if any, should be retried. |
timeout |
float
The timeout for this request. |
metadata |
Sequence[Tuple[str, str]]
Strings which should be sent along with the request as metadata. |
| Returns | |
|---|---|
| Type | Description |
| A topic resource. |