Python Client for Google Cloud Pub / Sub

Google Cloud Pub / Sub_ 是一项完全托管的实时消息服务，允许您在独立应用程序之间发送和接收消息。您可以利用 Cloud Pub/Sub 的灵活性来解耦托管在 Google Cloud Platform 或互联网其他位置的系统与组件。基于 Google 使用的相同技术构建，Cloud Pub / Sub 旨在提供低延迟的 “至少一次” 投递，并具备按需扩展至每秒 100 万条消息（甚至更多）的能力。

发布者应用程序可以向 topic 发送消息，而其他应用程序可以订阅该主题以接收消息。通过解耦发送者和接收者，Google Cloud Pub/Sub 允许开发者在独立编写的应用程序之间进行通信。

Product Documentation_
Client Library Documentation_

.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability .. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-pubsub.svg :target: https://pypi.org/project/google-cloud-pubsub/ .. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-pubsub.svg :target: https://pypi.org/project/google-cloud-pubsub/ .. _Google Cloud Pub / Sub: https://cloud.google.com/pubsub/ .. _Product Documentation: https://cloud.google.com/pubsub/docs .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/pubsub/latest/summary_overview

快速入门

要使用此库，您首先需要完成以下步骤：

Select or create a Cloud Platform project._
Enable billing for your project._
Enable the Google Cloud Pub / Sub API._
Setup Authentication._

.. _选择或创建 Cloud Platform 项目。: https://console.cloud.google.com/project .. _为您的项目启用计费。: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project .. _启用 Google Cloud Pub / Sub API。: https://cloud.google.com/pubsub .. _设置身份验证。: https://googleapis.dev/python/google-api-core/latest/auth.html

安装


使用 pip 在 `virtualenv`_ 中安装此库。`virtualenv`_ 是一个用于
创建隔离 Python 环境的工具。它解决的基本问题是依赖项和版本，以及间接的权限问题。

使用 `virtualenv`_，可以在无需系统
安装权限的情况下安装此库，并且不会与已安装的系统
依赖项发生冲突。

.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/

支持的 Python 版本
^^^^^^^^^^^^^^^^^^^^^
Python >= 3.9

已弃用的 Python 版本
^^^^^^^^^^^^^^^^^^^^^^
Python < 3.9

兼容 Python 3.7 和 3.8 的此库最后一个版本是 google-cloud-pubsub==2.34.0。

兼容 Python 2.7 的此库最后一个版本是 google-cloud-pubsub==1.7.0。

Mac/Linux
^^^^^^^^^

.. code-block:: console

    pip install virtualenv
    virtualenv <your-env>
    source <your-env>/bin/activate
    <your-env>/bin/pip install google-cloud-pubsub

Windows
^^^^^^^

.. code-block:: console

    pip install virtualenv
    virtualenv <your-env>
    <your-env>\Scripts\activate
    <your-env>\Scripts\pip.exe install google-cloud-pubsub

使用示例

发布 ^^^^^^^^^^

要将数据发布到 Cloud Pub/Sub，您必须创建一个主题，然后向该主题发布消息

.. code-block:: python

import os
from google.cloud import pubsub_v1

publisher = pubsub_v1.PublisherClient()
topic_name = 'projects/{project_id}/topics/{topic}'.format(
    project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
    topic='MY_TOPIC_NAME',  # 将此设置为适当的值。
)
publisher.create_topic(name=topic_name)
future = publisher.publish(topic_name, b'My first message!', spam='eggs')
future.result()

要了解更多信息，请参阅 publishing documentation_。

.. _publishing documentation: https://cloud.google.com/python/docs/reference/pubsub/latest/google.cloud.pubsub_v1.publisher.client.Client

订阅 ^^^^^^^^^^^

要订阅 Cloud Pub/Sub 中的数据，您基于主题创建一个订阅，并订阅该订阅，同时传递一个回调函数。

.. code-block:: python

import os
from google.cloud import pubsub_v1

topic_name = 'projects/{project_id}/topics/{topic}'.format(
    project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
    topic='MY_TOPIC_NAME',  # 将此设置为适当的值。
)

subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format(
    project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
    sub='MY_SUBSCRIPTION_NAME',  # 将此设置为适当的值。
)

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

with pubsub_v1.SubscriberClient() as subscriber: subscriber.create_subscription( name=subscription_name, topic=topic_name) future = subscriber.subscribe(subscription_name, callback)

对 subscriber.subscribe 的调用返回的 future 可用于阻塞当前线程，直到满足给定条件：

.. code-block:: python

try:
    future.result()
except KeyboardInterrupt:
    future.cancel()

也可以以同步（阻塞）方式拉取消息。有关订阅的更多信息，请参阅 subscriber documentation_。

.. _subscriber documentation: https://cloud.google.com/python/docs/reference/pubsub/latest/google.cloud.pubsub_v1.subscriber.client.Client

身份验证 ^^^^^^^^^^^^^^

可以指定与 Pub/Sub 客户端一起使用的身份验证方法。这可以通过提供显式的 Credentials_ 实例来完成。对多种身份验证方法的支持可从 google-auth_ 库中获得。

例如，要使用 JSON Web Tokens，请提供一个 google.auth.jwt.Credentials_ 实例：

.. code-block:: python

import json
from google.auth import jwt

service_account_info = json.load(open("service-account-info.json"))
audience = "https://pubsub.googleapis.com/google.pubsub.v1.Subscriber"

credentials = jwt.Credentials.from_service_account_info(
    service_account_info, audience=audience
)

subscriber = pubsub_v1.SubscriberClient(credentials=credentials)

发布者同理，但需要调整 "audience" 声明

publisher_audience = "https://pubsub.googleapis.com/google.pubsub.v1.Publisher"
credentials_pub = credentials.with_claims(audience=publisher_audience)
publisher = pubsub_v1.PublisherClient(credentials=credentials_pub)

.. _Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials .. _google-auth: https://google-auth.readthedocs.io/en/latest/index.html .. _google.auth.jwt.Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.jwt.html#google.auth.jwt.Credentials

版本控制

本库遵循 Semantic Versioning_。

当前处于主版本一（1.y.z），这意味着公共 API 应被视为稳定。

.. _Semantic Versioning: http://semver.org/

贡献

我们随时欢迎并高度鼓励对本库的贡献。

有关如何入门的更多信息，请参阅 CONTRIBUTING doc_。

.. _CONTRIBUTING doc: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst

社区

提问的最佳场所是通过 Stackoverflow: https://stackoverflow.com/questions/tagged/google-cloud-pubsub

许可证

Apache 2.0 - 有关更多信息，请参阅 the LICENSE_。

.. _the LICENSE: https://github.com/googleapis/google-cloud-python/blob/main/LICENSE