[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-17。"],[],[],null,["# Best practices to subscribe to a Pub/Sub topic\n\nIn subscribing, a subscriber client receives messages from a Pub/Sub topic. Here are some best practices for subscribing to Pub/Sub.\n\n\u003cbr /\u003e\n\nThis document assumes that you are already familiar with the process of\nsubscribing to a Pub/Sub topic and receiving messages in your\nsubscriber client.\n\nIf you're new to Pub/Sub, see one of the Quickstart guides and\nlearn how to run Pub/Sub using the\n[console](/pubsub/docs/publish-receive-messages-console),\n[Google Cloud CLI](/pubsub/docs/publish-receive-messages-gcloud), or the\n[client libraries](/pubsub/docs/publish-receive-messages-client-library).\n\nChoose the right subscription\n-----------------------------\n\nPub/Sub offers standard subscriptions such as *push* and *pull*\nsubscriptions. In addition to the standard subscriptions, Pub/Sub\nalso offers *export* subscriptions that lets you store messages directly to a\nGoogle Cloud resource, without requiring Dataflow as an intermediary.\nFor example, BigQuery subscriptions store messages in a\nBigQuery table.\n\nPush subscriptions are recommended for the following scenarios:\n\n- You cannot include any code in your subscriber application that imports\n the client library as a dependency.\n\n- The subscriber client cannot make any outgoing requests.\n\n- You want to use the same instance to process messages from different topics\n and subscriptions where the subscriber client doesn't know the list of\n subscriptions.\n\nFor general cases, we recommend using the\n[high-level client library](/pubsub/docs/reference/libraries). If you're\ninstead using unary pull, don't set\n[returnImmediately](/pubsub/docs/reference/rest/v1/projects.subscriptions/pull#request-body)\nto `true`. Setting it to `true` adversely impacts pull performance.\nThe field `returnImmediately`is now deprecated.\n\n- To compare all the subscription types and choose the one that best fits your\n business needs, see the\n [Pub/Sub subscription comparison table](/pubsub/docs/subscriber#subscription_type_comparison).\n\n- To learn about the benefits of an export subscription, see\n [When to use an export subscription](/pubsub/docs/subscriber#export_subscription).\n\nProcess messages before acknowledging them\n------------------------------------------\n\nBy default, Pub/Sub discards a message from a subscription after\nthe message is acknowledged. If you don't process a message before sending an\nacknowledgment and the processing fails, the service does not redeliver the\nmessage. The exception is when you have configured retaining acknowledged\nmessages or topic retention and you perform\na [seek operation](/pubsub/docs/replay-overview).\n\nIf you have high-latency subscribers, you might need to set custom values for\n[flow control](/pubsub/docs/flow-control) and\n[lease management](/pubsub/docs/lease-management).\n\nConfigure subscriber flow control for transient traffic spikes\n--------------------------------------------------------------\n\nFlow control on the subscriber side lets you prevent subscribers from being\noverloaded by traffic spikes. It can allow time for autoscaling mechanisms to\nrespond to an increased load or it can spread the processing of the load over a\nlonger period of time. The former method saves latency, while the latter saves\ncosts.\n\nTo configure [flow control](/pubsub/docs/flow-control), you must set\nappropriate values for `maximum outstanding messages` and\n`total outstanding message bytes`. The default values for these flow control\nvariables and the names of the variables might differ across client libraries.\n\n- **Maximum outstanding messages** defines the maximum number of messages\n delivered to the client for which Pub/Sub has not received\n acknowledgments or negative acknowledgments.\n\n- **Total outstanding message bytes** defines the maximum total size of\n messages delivered to the client for which Pub/Sub has not\n received acknowledgments or negative acknowledgments.\n\nIf the limit for one of these options is crossed, the subscriber client does not\npull more messages. This behavior continues until the messages that are already\npulled get acknowledged or negatively acknowledged. In this way, you can\ntradeoff throughput with the cost associated with running more subscribers.\n\nHandle duplicate deliveries\n---------------------------\n\nBy default, Pub/Sub provides at-least-once delivery of messages\nto subscribers. That means messages can be delivered multiple times, even if\nthey were acknowledged. The following sections discuss how to address common\nredelivery scenarios.\n\n### Consistent redelivery of many messages\n\nIf you are experiencing cases where many messages are always getting\nredelivered, then your subscribers are overloaded or they are not\nacknowledging the messages before the deadline expires.\n\nIf you are using a pull subscription, you might need to set custom values to\n[flow control](/pubsub/docs/flow-control) values or increase the lease extension\nperiods using [lease management](/pubsub/docs/lease-management).\n\nIf you are using push subscriptions, you might need to increase the\nacknowledgement deadline setting. You can also follow best practices regarding\nhow to [maintain a healthy subscription](/pubsub/docs/monitoring#maintain_a_healthy_subscription).\n\n### Occasional redelivery of messages\n\nWhen you see messages get redelivered before the acknowledgement deadline has\npassed or after the messages were acknowledged within a few seconds,\nPub/Sub is behaving as expected. You shouldn't see these\nredelivery spikes frequently, but when redeliveries do occur, they are likely to\noccur on several messages simultaneously. Your system must be built to tolerate\nthese occasional duplicates.\n\n### Repeated redelivery of a few messages\n\nWhen you see a small number of messages get delivered several times, first confirm\nthat you are acknowledging them. If you are not, figure out why your subscriber\nis not handling the messages properly. You might want to configure a\n[dead letter topic](/pubsub/docs/handling-failures#dead_letter_topic) to prevent\nfurther redelivery. If you are acknowledging the message, Pub/Sub\nmight still be operating as expected. While very rare, it is still possible for\na small number of messages to get delivered multiple times if there are internal\nnetwork or hardware disruptions. The service attempts to self-heal in these\ncases, but it can take several minutes for the remedies to activate.\n\nYour system must be tolerant to redeliveries. You can reduce their likelihood\nby ensuring you process and acknowledge messages as quickly as possible.\n\nIf your application can't tolerate any duplicates, you can enable\n[exactly-once delivery](/pubsub/docs/exactly-once-delivery). Remember that this\nfeature is only available for pull subscriptions and that it also results in\nhigher publish-to-subscribe latency. Evaluate whether the trade-off of higher\nlatency is acceptable for your use case before enabling this feature.\n\nBest practices for ordered messaging in subscribing\n---------------------------------------------------\n\nIf you use message ordering, ensure the following:\n\n- **Choose either StreamingPull or Pull subscriptions.** For a push\n subscription, Pub/Sub supports only one outstanding message\n for each ordering key at a time. Sending parallel push requests in such a\n scenario would be similar to sending multiple batches of messages for the\n same ordering key to pull subscribers simultaneously. Therefore, push\n subscriptions are not recommended for topics where multiple messages are\n frequently published with the same ordering key or where latency is\n extremely important.\n\n- **Enable message ordering in the subscription**. On the publisher side, if\n you send messages with an ordering key and in the same region, you can\n configure the subscribers to receive those messages in order. On the\n subscriber side, enable the message ordering property for only those\n subscriptions for which you want to receive ordered messages. Depending on\n the property status, each subscription attached to the topic can determine\n if they need ordered delivery without impacting each other.\n\n- **Acknowledge messages in order**. When using ordered delivery,\n acknowledgments for later messages are not processed until acknowledgments\n for earlier messages are processed per ordering key. For example, if you\n have messages 1, 2, and 3 with the same ordering key and you receive them\n all and only acknowledge message 3, the service does not consider message 3\n as acknowledged until messages 1 and 2 are also acknowledged. If the\n acknowledgments for messages 1 and 2 are never received, then messages 1,\n 2, and 3 are all redelivered.\n\nSummary of best practices\n-------------------------\n\nThe following table summarizes the best practices recommended in this document:\n\nWhat's next\n-----------\n\n- [Best practices to publish to a Pub/Sub topic](/pubsub/docs/publish-best-practices).\n\n- [Best practices for using Pub/Sub metrics as a scaling signal](/pubsub/docs/metrics-autoscaling-best-practices)."]]
