Pub/Sub surfaces JSON/HTTP interfaces (commonly associated with RESTful systems) and gRPC interfaces.
If you don't want to use our client libraries to access the Pub/Sub API, you have the option of writing your own client libraries that use its REST or gRPC API surface. We recommend this approach only if your programming language or other needs are not met by the provided client libraries.
gRPC interface
You can generate your own gRPC client libraries in any gRPC-supported language
for the Pub/Sub API from its .proto service definition using these
resources:
- Pub/Sub service
definition:
The official Pub/Sub API
.protoservice definition. - gRPC documentation: Everything you need to generate and use your own gRPC client code
- RPC API Reference: Language-independent overview of the RPC surface
JSON/HTTP interface
If you prefer working with the JSON/HTTP interface, you can use these resources:
- Pub/Sub REST API reference: Provides a detailed specification for available methods and resources.
- Working with Google HTTP APIs: Describes how Google APIs work with different HTTP versions and implementations.
- API Discovery Service: Exposes machine-readable metadata about the JSON/HTTP API surface, useful for creating client libraries, tools, and plugins.
- Directory of client samples built with JSON/HTTP APIs and the Google API Discovery Service.
About Pub/Sub endpoints
An endpoint, in the context of publish-subscribe messaging systems such as Pub/Sub, refers to a location or address where a publisher client can publish messages or where a subscriber client can receive messages.
Pub/Sub has three types of endpoints:
- Global
- Regional
- Locational
Each of these endpoint types use a different value or pattern.
Global endpoint
A global endpoint in Google Cloud provides a single access point for a service.
The global endpoint for Pub/Sub is https://pubsub.googleapis.com.
Requests originating within Google Cloud
Examples of origins considered within Google Cloud include clients running on Compute Engine or App Engine. Requests to the global endpoint originating from within Google Cloud are routed to Pub/Sub in the region where they originate.
In case Pub/Sub becomes unavailable in a region, requests originating within the same Google Cloud region are not re-routed to a different region.
Requests sent over Cloud Interconnect
Requests sent to the global endpoint over Cloud Interconnect are routed just like any other request originating in the region associated with the interconnection.
Requests sent from outside of Google Cloud
Requests sent to the global endpoint from outside of Google Cloud are routed to a nearby available region. The requests may be routed to a region with insufficient project quota for the request type. The region is also not guaranteed to be the closest geographically.
Regional endpoints
Requests sent to a regional endpoint are always routed to Pub/Sub in the specified region.
Requests are never re-routed to other regions. The message storage policy must include the target region to complete the request. This helps enforce strong data residency guarantees.
For example, if you publish a Pub/Sub message to a topic through
an endpoint such as pubsub.us-central1.rep.googleapis.com, the publish
operation only succeeds if all of the following are true:
- The topic has a message storage policy configured.
- The message storage policy has
enforce_in_transitset to true. - The message storage policy's
allowed_persistence_regionslist includesus-central1.
When to use regional endpoints
We recommend using regional endpoints as an alternative to the global one in the following cases:
- Applications that have strict data residency constraints, requiring data to be processed in a specific region.
- High volume applications running outside of Google Cloud that require sufficient quota in all regions where traffic might be routed.
- Applications where the publishers or subscribers run outside of Google Cloud and are not geographically close to each other. In such cases, you can reduce Google Cloud outbound message costs by configuring the applications outside of Google Cloud to use the regional endpoint corresponding to the region used by the application inside of Google Cloud. If both publishers and subscribers are outside of Google Cloud, configure them to use the same regional endpoint.
- When publishing with ordering.
- When subscribing with exactly-once delivery.
Locational endpoints
Requests to a locational endpoint are almost always routed to Pub/Sub in the specified region. However, it's important to understand that locational endpoints don't provide strong data residency guarantees (like regional endpoints do).
For instance, a request to a locational endpoint might be routed to Pub/Sub in another region if you have configured a message storage policy that dictates that messages must be stored in a specific region.
When to use locational endpoints
We recommend using locational endpoints as an alternative to the global one in the following cases:
- High volume applications running outside of Google Cloud that require sufficient quota in all regions where traffic might be routed.
- Applications where the publishers or subscribers run outside of Google Cloud and are not geographically close to each other. In such cases, you can reduce Google Cloud outbound message costs by configuring the applications outside of Google Cloud to use the locational endpoint corresponding to the region used by the application inside of Google Cloud. If both publishers and subscribers are outside of Google Cloud, configure them to use the same locational endpoint.
- When publishing with ordering.
- When subscribing with exactly-once delivery.
Using endpoints
This section describes how to specify a Pub/Sub endpoint in your client.
Set a locational endpoint override
You can set a locational endpoint override for any Pub/Sub operation that calls a Pub/Sub endpoint (JSON/HTTP or gRPC).
gcloud
To set a locational endpoint override, use the
CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB environment variable with
the applicable gcloud pubsub ... command. The following example uses a
locational override to publish to a topic.
CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB=ENDPOINT_OVERRIDE \ gcloud pubsub topics publish TOPIC_ID \ --message='MESSAGE_DATA'
Replace the following:
- ENDPOINT_OVERRIDE: the locational endpoint override. Must
be an absolute URI that begins with
https://and ends with a trailing/. For example,https://us-west1-pubsub.googleapis.com/. - TOPIC_ID: the ID of the topic.
- MESSAGE_DATA: a string with the message data.
You can also set the a global CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB
environment variable. If you do this, all your following Google Cloud CLI commands
use the override, without requiring you to prefix the command. For example:
export CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB=ENDPOINT_OVERRIDE
List of locational endpoints
To send requests directly to a locational endpoint, use the following Pub/Sub endpoints:
| Region | Endpoint |
|---|---|
| africa-south1 | https://africa-south1-pubsub.googleapis.com |
| asia-east1 | https://asia-east1-pubsub.googleapis.com |
| asia-east2 | https://asia-east2-pubsub.googleapis.com |
| asia-northeast1 | https://asia-northeast1-pubsub.googleapis.com |
| asia-northeast2 | https://asia-northeast2-pubsub.googleapis.com |
| asia-northeast3 | https://asia-northeast3-pubsub.googleapis.com |
| asia-south1 | https://asia-south1-pubsub.googleapis.com |
| asia-south2 | https://asia-south2-pubsub.googleapis.com |
| asia-southeast1 | https://asia-southeast1-pubsub.googleapis.com |
| asia-southeast2 | https://asia-southeast2-pubsub.googleapis.com |
| australia-southeast1 | https://australia-southeast1-pubsub.googleapis.com |
| australia-southeast2 | https://australia-southeast2-pubsub.googleapis.com |
| europe-central2 | https://europe-central2-pubsub.googleapis.com |
| europe-north1 | https://europe-north1-pubsub.googleapis.com |
| europe-north2 | https://europe-north2-pubsub.googleapis.com |
| europe-southwest1 | https://europe-southwest1-pubsub.googleapis.com |
| europe-west1 | https://europe-west1-pubsub.googleapis.com |
| europe-west10 | https://europe-west10-pubsub.googleapis.com |
| europe-west12 | https://europe-west12-pubsub.googleapis.com |
| europe-west2 | https://europe-west2-pubsub.googleapis.com |
| europe-west3 | https://europe-west3-pubsub.googleapis.com |
| europe-west4 | https://europe-west4-pubsub.googleapis.com |
| europe-west6 | https://europe-west6-pubsub.googleapis.com |
| europe-west8 | https://europe-west8-pubsub.googleapis.com |
| europe-west9 | https://europe-west9-pubsub.googleapis.com |
| me-central1 | https://me-central1-pubsub.googleapis.com |
| me-central2 | https://me-central2-pubsub.googleapis.com |
| me-west1 | https://me-west1-pubsub.googleapis.com |
| northamerica-northeast1 | https://northamerica-northeast1-pubsub.googleapis.com |
| northamerica-northeast2 | https://northamerica-northeast2-pubsub.googleapis.com |
| northamerica-south1 | https://northamerica-south1-pubsub.googleapis.com |
| southamerica-east1 | https://southamerica-east1-pubsub.googleapis.com |
| southamerica-west1 | https://southamerica-west1-pubsub.googleapis.com |
| us-central1 | https://us-central1-pubsub.googleapis.com |
| us-east1 | https://us-east1-pubsub.googleapis.com |
| us-east4 | https://us-east4-pubsub.googleapis.com |
| us-east5 | https://us-east5-pubsub.googleapis.com |
| us-south1 | https://us-south1-pubsub.googleapis.com |
| us-west1 | https://us-west1-pubsub.googleapis.com |
| us-west2 | https://us-west2-pubsub.googleapis.com |
| us-west3 | https://us-west3-pubsub.googleapis.com |
| us-west4 | https://us-west4-pubsub.googleapis.com |
List of regional endpoints
To send requests directly to a regional endpoint, use the following Pub/Sub endpoints:
| Region | Endpoint |
|---|---|
| europe-west3 | https://pubsub.europe-west3.rep.googleapis.com |
| europe-west8 | https://pubsub.europe-west8.rep.googleapis.com |
| europe-west9 | https://pubsub.europe-west9.rep.googleapis.com |
| me-central2 | https://pubsub.me-central2.rep.googleapis.com |
| us-central1 | https://pubsub.us-central1.rep.googleapis.com |
| us-central2 | https://pubsub.us-central2.rep.googleapis.com |
| us-east1 | https://pubsub.us-east1.rep.googleapis.com |
| us-east4 | https://pubsub.us-east4.rep.googleapis.com |
| us-east5 | https://pubsub.us-east5.rep.googleapis.com |
| us-south1 | https://pubsub.us-south1.rep.googleapis.com |
| us-west1 | https://pubsub.us-west1.rep.googleapis.com |
| us-west2 | https://pubsub.us-west2.rep.googleapis.com |
| us-west3 | https://pubsub.us-west3.rep.googleapis.com |
| us-west4 | https://pubsub.us-west4.rep.googleapis.com |
What's next
- Pub/Sub REST reference
- Pub/Sub RPC reference