Change subscription types

After you create a subscription, you can change the delivery method to push, pull, or export.

Before you begin

Required roles and permissions

To get the permission that you need to change a subscription type, ask your administrator to grant you the Pub/Sub Editor (roles/pubsub.editor) IAM role on the subscription. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the pubsub.subscriptions.update permission, which is required to change a subscription type.

You might also be able to get this permission with custom roles or other predefined roles.

You can configure access control at the project level and at the individual resource level. You can create a subscription in one project and attach it to a topic located in a different project. Ensure that you have the required permissions for each project.

Change the delivery type of a subscription

To change a subscription's delivery type, perform the following steps.

Console

  1. In the Google Cloud console, go to the Subscriptions page.

    Go to Subscriptions

  2. Click the name of the subscription that you want to update.

  3. In the subscription details page, click Edit.

  4. For Delivery type, select the new delivery type.

  5. Fill in the properties for the new subscription type. For more information, see the following topics:

  6. Optional. Update other subscription properties as required.

  7. Click Update.

gcloud

To change the delivery type, use the gcloud pubsub subscriptions update command. Clear the configuration for the current delivery type and set the configuration for the new type, as follows:

gcloudpubsubsubscriptionsupdateSUBSCRIPTION_ID\
CLEAR_CONFIG_FLAG\
NEW_CONFIG_FLAGS

Replace the following:

  • SUBSCRIPTION_ID: The name of the subscription to update.

  • CLEAR_CONFIG_FLAG: A flag to clear the existing configuration for the delivery type. Use one of the following flags, depending on the current delivery type:

    • Pull subscription: --no-enable-exactly-once-delivery

    • Push subscription: --push-endpoint=""

    • BigQuery subscription: --clear-bigquery-config

    • Bigtable subscription: --clear-bigtable-config

    • Cloud Storage subscription: --clear-cloud-storage-config

  • NEW_CONFIG_FLAGS: Flags to configure the new delivery type. For more information, see the documentation for the gcloud pubsub subscriptions update command.

Examples

Change a BigQuery subscription to a pull subscription:

gcloudpubsubsubscriptionsupdateSUBSCRIPTION_ID\
--clear-bigquery-config

Change a push subscription to a BigQuery subscription:

gcloudpubsubsubscriptionsupdateSUBSCRIPTION_ID\
--push-endpoint=""\
--bigquery-table=BIGQUERY_TABLE

Update a push subscription endpoint

To update the endpoint URL on a push subscription, perform the following steps.

Console

To modify the endpoint URL, complete the following steps.

  1. In the Google Cloud console, go to the Subscriptions page.

    Go to Subscriptions

  2. Click next to the subscription to update.
  3. In the Delivery type, choose a delivery option.
  4. Fill in other subscription properties as required.
  5. Click Update.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To modify the endpoint URL, run the gcloud pubsub subscriptions modify-push-config command:

    gcloudpubsubsubscriptionsmodify-push-configSUBSCRIPTION_ID\
--push-endpoint=PUSH_ENDPOINT

    If the subscription is already using pull delivery, setting the push endpoint switches the delivery method to push delivery.

    You can switch from push to pull delivery by changing the push endpoint to an empty string.

REST

To modify the push configurations of a subscription, use the projects.subscriptions.modifyPushConfig method:

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID:modifyPushConfig
Authorization: Bearer ACCESS_TOKEN

Request body:

{
"pushConfig": {
 "pushEndpoint": "PUSH_ENDPOINT"
}
}

Where:

  • PROJECT_ID is your project ID.
  • SUBSCRIPTION_ID is your subscription ID.
  • PUSH_ENDPOINT is a modified URL that you want to apply as your new push endpoint. For example, https://myproject.appspot.com/myhandler.

    • Response:

    If the request is successful, the response is an empty JSON object.

    C++

    Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation. 

    namespacepubsub_admin=::google::cloud::pubsub_admin;
namespacepubsub=::google::cloud::pubsub;
[](pubsub_admin::SubscriptionAdminClientclient,
std::stringconst&project_id,std::stringconst&subscription_id,
std::stringconst&endpoint){
google::pubsub::v1::ModifyPushConfigRequestrequest;
request.set_subscription(
pubsub::Subscription(project_id,subscription_id).FullName());
request.mutable_push_config()->set_push_endpoint(endpoint);
autostatus=client.ModifyPushConfig(request);
if(!status.ok())throwstd::runtime_error(status.message());
std::cout << "The subscription push configuration was successfully"
 << " modified\n";
}

    C#

    Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation. 

    
usingGoogle.Cloud.PubSub.V1 ;
publicclassUpdatePushConfigurationSample
{
publicvoidUpdatePushConfiguration(stringprojectId,stringsubscriptionId,stringpushEndpoint)
{
SubscriberServiceApiClient subscriber=SubscriberServiceApiClient .Create ();
SubscriptionName subscriptionName=SubscriptionName .FromProjectSubscription (projectId,subscriptionId);
PushConfig pushConfig=newPushConfig {PushEndpoint=pushEndpoint};
subscriber.ModifyPushConfig (subscriptionName,pushConfig);
}
}

    Go

    The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, see the migration guide to v2. To see a list of v1 code samples, see the deprecated code samples.

    Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.

    import(
"context"
"fmt"
"io"
"cloud.google.com/go/pubsub/v2"
"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
"google.golang.org/protobuf/types/known/fieldmaskpb"
)
funcupdateEndpoint(wio.Writer,projectID,subscriptionName,endpointstring)error{
// projectID := "my-project-id"
// subscriptionName := "projects/my-project/subscriptions/my-sub"
// endpoint := "https://my-test-project.appspot.com/push"
ctx:=context.Background()
client,err:=pubsub.NewClient(ctx,projectID)
iferr!=nil{
returnfmt.Errorf("pubsub.NewClient: %w",err)
}
deferclient.Close()
req:=&pubsubpb.UpdateSubscriptionRequest{
Subscription:&pubsubpb.Subscription{
Name:subscriptionName,
PushConfig:&pubsubpb.PushConfig{
PushEndpoint:endpoint,
},
},
UpdateMask:&fieldmaskpb.FieldMask{
Paths:[]string{"push_config"},
},
}
subConfig,err:=client.SubscriptionAdminClient.UpdateSubscription(ctx,req)
iferr!=nil{
returnfmt.Errorf("Update: %w",err)
}
fmt.Fprintf(w,"Updated subscription config: %v\n",subConfig)
returnnil
}

    Java

    Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

    
importcom.google.cloud.pubsub.v1.SubscriptionAdminClient ;
importcom.google.pubsub.v1.PushConfig ;
importcom.google.pubsub.v1.Subscription ;
importcom.google.pubsub.v1.SubscriptionName ;
importjava.io.IOException;
publicclass UpdatePushConfigurationExample{
publicstaticvoidmain(String...args)throwsException{
// TODO(developer): Replace these variables before running the sample.
StringprojectId="your-project-id";
StringsubscriptionId="your-subscription-id";
StringpushEndpoint="https://my-test-project.appspot.com/push";
updatePushConfigurationExample(projectId,subscriptionId,pushEndpoint);
}
publicstaticvoidupdatePushConfigurationExample(
StringprojectId,StringsubscriptionId,StringpushEndpoint)throwsIOException{
try(SubscriptionAdminClient subscriptionAdminClient=SubscriptionAdminClient .create()){
SubscriptionName subscriptionName=SubscriptionName .of(projectId,subscriptionId);
PushConfig pushConfig=PushConfig .newBuilder().setPushEndpoint (pushEndpoint).build();
subscriptionAdminClient.modifyPushConfig(subscriptionName,pushConfig);
Subscription subscription=subscriptionAdminClient.getSubscription(subscriptionName);
System.out.println(
"Updated push endpoint to: "+subscription.getPushConfig ().getPushEndpoint());
}
}
}

    Node.js

    Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

    /**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// Imports the Google Cloud client library
const{PubSub}=require('@google-cloud/pubsub');
// Creates a client; cache this for further use
constpubSubClient=newPubSub();
asyncfunctionmodifyPushConfig(topicNameOrId,subscriptionNameOrId){
constoptions={
// Set to an HTTPS endpoint of your choice. If necessary, register
// (authorize) the domain on which the server is hosted.
pushEndpoint:`https://${pubSubClient.projectId}.appspot.com/push`,
};
awaitpubSubClient
.topic(topicNameOrId)
.subscription(subscriptionNameOrId)
.modifyPushConfig(options);
console.log(`Modifiedpushconfigforsubscription${subscriptionNameOrId}.`);
}

    Node.ts

    Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

    /**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// Imports the Google Cloud client library
import{PubSub, CreateSubscriptionOptions} from'@google-cloud/pubsub';
// Creates a client; cache this for further use
const pubSubClient = new PubSub();
async function modifyPushConfig(
 topicNameOrId: string,
 subscriptionNameOrId: string,
) {
 const options: CreateSubscriptionOptions = {
 // Set to an HTTPS endpoint of your choice. If necessary, register
 // (authorize) the domain on which the server is hosted.
 pushEndpoint: `https://${pubSubClient.projectId}.appspot.com/push`,
 };
 await pubSubClient
 .topic(topicNameOrId)
 .subscription(subscriptionNameOrId)
 .modifyPushConfig(options);
 console.log(`Modified push config for subscription ${subscriptionNameOrId}.`);
}

    Python

    Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

    fromgoogle.cloudimport pubsub_v1
# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# endpoint = "https://my-test-project.appspot.com/push"
subscriber = pubsub_v1.SubscriberClient ()
subscription_path = subscriber.subscription_path(project_id, subscription_id)
push_config = pubsub_v1.types.PushConfig (push_endpoint=endpoint)
subscription = pubsub_v1.types.Subscription (
 name=subscription_path, topic=topic_id, push_config=push_config
)
update_mask = {"paths": {"push_config"}}
# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
 result = subscriber.update_subscription(
 request={"subscription": subscription, "update_mask": update_mask}
 )
print(f"Subscription updated: {subscription_path}")
print(f"New endpoint for subscription is: {result.push_config}.")

    Ruby

    The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3. To see a list of Ruby v2 code samples, see the deprecated code samples.

    Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

    # subscription_id = "your-subscription-id"
# new_endpoint = "Endpoint where your app receives messages""
pubsub=Google::Cloud::PubSub .new
subscription_admin=pubsub.subscription_admin
subscription=subscription_admin.get_subscription\
subscription:pubsub.subscription_path(subscription_id)
subscription.push_config=Google::Cloud::PubSub ::V1 ::PushConfig.new \
push_endpoint:new_endpoint
subscription_admin.update_subscriptionsubscription:subscription,
update_mask:{
paths:["push_config"]
}
puts"Push endpoint updated."

    What's next

    Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

    Last updated 2026年08月26日 UTC.