Pub/Sub APIs overview

Pub/Sub surfaces JSON/HTTP (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:

JSON/HTTP interface

If you prefer working with the JSON/HTTP interface, you can use these resources:

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 global and locational service endpoints.

  • The global HTTP endpoint for JSON/HTTP is https://pubsub.googleapis.com.
  • The global endpoint for gRPC is pubsub.googleapis.com:443.

Global endpoints

Requests to the global endpoint originating from within Google Cloud are routed to the Pub/Sub in the region where they originate. Examples of origins considered within Google Cloud include clients running on Compute Engine or App Engine. Requests to the global endpoint made over Interconnect are routed similarly to requests originating in the region associated with the interconnection. In case Pub/Sub becomes unavailable in a region, requests originating within the same Google Cloud region are not load balanced to a different region.

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.

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.
  • Applications which require that data be processed in a specific region.

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 region, use the following locational Pub/Sub endpoints:

Region JSON/HTTP endpoint gRPC Service
africa-south1 https://africa-south1-pubsub.googleapis.com africa-south1-pubsub.googleapis.com:443
asia-east1 https://asia-east1-pubsub.googleapis.com asia-east1-pubsub.googleapis.com:443
asia-east2 https://asia-east2-pubsub.googleapis.com asia-east2-pubsub.googleapis.com:443
asia-northeast1 https://asia-northeast1-pubsub.googleapis.com asia-northeast1-pubsub.googleapis.com:443
asia-northeast2 https://asia-northeast2-pubsub.googleapis.com asia-northeast2-pubsub.googleapis.com:443
asia-northeast3 https://asia-northeast3-pubsub.googleapis.com asia-northeast3-pubsub.googleapis.com:443
asia-south1 https://asia-south1-pubsub.googleapis.com asia-south1-pubsub.googleapis.com:443
asia-south2 https://asia-south2-pubsub.googleapis.com asia-south2-pubsub.googleapis.com:443
asia-southeast1 https://asia-southeast1-pubsub.googleapis.com asia-southeast1-pubsub.googleapis.com:443
asia-southeast2 https://asia-southeast2-pubsub.googleapis.com asia-southeast2-pubsub.googleapis.com:443
australia-southeast1 https://australia-southeast1-pubsub.googleapis.com australia-southeast1-pubsub.googleapis.com:443
australia-southeast2 https://australia-southeast2-pubsub.googleapis.com australia-southeast2-pubsub.googleapis.com:443
europe-central2 https://europe-central2-pubsub.googleapis.com europe-central2-pubsub.googleapis.com:443
europe-north1 https://europe-north1-pubsub.googleapis.com europe-north1-pubsub.googleapis.com:443
europe-north2 https://europe-north2-pubsub.googleapis.com europe-north2-pubsub.googleapis.com:443
europe-southwest1 https://europe-southwest1-pubsub.googleapis.com europe-southwest1-pubsub.googleapis.com:443
europe-west1 https://europe-west1-pubsub.googleapis.com europe-west1-pubsub.googleapis.com:443
europe-west10 https://europe-west10-pubsub.googleapis.com europe-west10-pubsub.googleapis.com:443
europe-west12 https://europe-west12-pubsub.googleapis.com europe-west12-pubsub.googleapis.com:443
europe-west2 https://europe-west2-pubsub.googleapis.com europe-west2-pubsub.googleapis.com:443
europe-west3 https://europe-west3-pubsub.googleapis.com europe-west3-pubsub.googleapis.com:443
europe-west4 https://europe-west4-pubsub.googleapis.com europe-west4-pubsub.googleapis.com:443
europe-west6 https://europe-west6-pubsub.googleapis.com europe-west6-pubsub.googleapis.com:443
europe-west8 https://europe-west8-pubsub.googleapis.com europe-west8-pubsub.googleapis.com:443
europe-west9 https://europe-west9-pubsub.googleapis.com europe-west9-pubsub.googleapis.com:443
me-central1 https://me-central1-pubsub.googleapis.com me-central1-pubsub.googleapis.com:443
me-central2 https://me-central2-pubsub.googleapis.com me-central2-pubsub.googleapis.com:443
me-west1 https://me-west1-pubsub.googleapis.com me-west1-pubsub.googleapis.com:443
northamerica-northeast1 https://northamerica-northeast1-pubsub.googleapis.com northamerica-northeast1-pubsub.googleapis.com:443
northamerica-northeast2 https://northamerica-northeast2-pubsub.googleapis.com northamerica-northeast2-pubsub.googleapis.com:443
northamerica-south1 https://northamerica-south1-pubsub.googleapis.com northamerica-south1-pubsub.googleapis.com:443
southamerica-east1 https://southamerica-east1-pubsub.googleapis.com southamerica-east1-pubsub.googleapis.com:443
southamerica-west1 https://southamerica-west1-pubsub.googleapis.com southamerica-west1-pubsub.googleapis.com:443
us-central1 https://us-central1-pubsub.googleapis.com us-central1-pubsub.googleapis.com:443
us-east1 https://us-east1-pubsub.googleapis.com us-east1-pubsub.googleapis.com:443
us-east4 https://us-east4-pubsub.googleapis.com us-east4-pubsub.googleapis.com:443
us-east5 https://us-east5-pubsub.googleapis.com us-east5-pubsub.googleapis.com:443
us-south1 https://us-south1-pubsub.googleapis.com us-south1-pubsub.googleapis.com:443
us-west1 https://us-west1-pubsub.googleapis.com us-west1-pubsub.googleapis.com:443
us-west2 https://us-west2-pubsub.googleapis.com us-west2-pubsub.googleapis.com:443
us-west3 https://us-west3-pubsub.googleapis.com us-west3-pubsub.googleapis.com:443
us-west4 https://us-west4-pubsub.googleapis.com us-west4-pubsub.googleapis.com:443