Console
    Contact Us Start free

    Detach subscriptions

    When you create a subscription, you attach the subscription to a topic, and subscribers can receive messages from the subscription. To stop subscribers from receiving messages, you can detach subscriptions from the topic.

    Before you detach a subscription, you need the pubsub.topics.detachSubscription permission on the topic. You can detach a subscription without permissions on the subscription, which is useful for managing a topic that is in a different project than the subscription. For more information, see Pub/Sub access control .

    Before you begin

    Required roles and permissions

    To get the permissions that you need to detach subscriptions and manage them, ask your administrator to grant you the Pub/Sub Editor ( roles/pubsub.editor ) IAM role on your topic or project. For more information about granting roles, see Manage access to projects, folders, and organizations .

    This predefined role contains the permissions required to detach subscriptions and manage them. To see the exact permissions that are required, expand the Required permissionssection:

    Required permissions

    The following permissions are required to detach subscriptions and manage them:

    • Pull from a subscription: pubsub.subscriptions.consume
    • Create a subscription: pubsub.subscriptions.create
    • Delete a subscription: pubsub.subscriptions.delete
    • Get a subscription: pubsub.subscriptions.get
    • List a subscription: pubsub.subscriptions.list
    • Update a subscription: pubsub.subscriptions.update
    • Attach a subscription to a topic: pubsub.topics.attachSubscription
    • Get the IAM policy for a subscription: pubsub.subscriptions.getIamPolicy
    • Configure the IAM policy for a subscription: pubsub.subscriptions.setIamPolicy

    You might also be able to get these permissions 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.

    Detach a subscription from a topic

    You can detach a subscription from a topic using the Google Cloud console, the Google Cloud CLI, the client library, or the Pub/Sub API.

    Console

    To detach a subscription, follow these steps:

    1. In the Google Cloud console, go to the Topicspage.

      Go to Topics

    2. Select the topic from which you want to detach a subscription.

    3. In the Subscriptionstab, select the subscription to detach.

    4. In the Subscription detailspage, click Detach.

    5. In the dialog that appears, click Detachagain.

    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 detach a subscription, use the gcloud pubsub topics detach-subscription command:

      gcloud  
pubsub  
topics  
detach-subscription  
 SUBSCRIPTION_ID

      If the request is successful, the command line displays a confirmation:

      Detached subscription [ SUBSCRIPTION_ID 
].

    REST

    To detach a subscription, use the projects.subscriptions.detach 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, use the gcloud auth application-default print-access-token command.

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

    Where:

    • PROJECT_ID is your project ID.
    • SUBSCRIPTION_ID is your subscription ID.

    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 .

      namespace 
  
 pubsub 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 pubsub 
 ; 
 namespace 
  
 pubsub_admin 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 pubsub_admin 
 ; 
 []( 
 pubsub_admin 
 :: 
 TopicAdminClient 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 project_id 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 subscription_id 
 ) 
  
 { 
  
 google 
 :: 
 pubsub 
 :: 
 v1 
 :: 
 DetachSubscriptionRequest 
  
 request 
 ; 
  
 request 
 . 
 set_subscription 
 ( 
  
 pubsub 
 :: 
 Subscription 
 ( 
 project_id 
 , 
  
 subscription_id 
 ). 
 FullName 
 ()); 
  
 auto 
  
 response 
  
 = 
  
 client 
 . 
 DetachSubscription 
 ( 
 request 
 ); 
  
 if 
  
 ( 
 ! 
 response 
 . 
 ok 
 ()) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 response 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "The subscription was successfully detached: " 
 << 
 response 
 - 
> DebugString 
 () 
 << 
 " 
 \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 .

      using 
  
  Google.Cloud.PubSub.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 DetachSubscriptionSample 
 { 
  
 public 
  
 void 
  
 DetachSubscription 
 ( 
 string 
  
 projectId 
 , 
  
 string 
  
 subscriptionId 
 ) 
  
 { 
  
  PublisherServiceApiClient 
 
  
 publisher 
  
 = 
  
  PublisherServiceApiClient 
 
 . 
  Create 
 
 (); 
  
  DetachSubscriptionRequest 
 
  
 detachSubscriptionRequest 
  
 = 
  
 new 
  
  DetachSubscriptionRequest 
 
  
 { 
  
 SubscriptionAsSubscriptionName 
  
 = 
  
  SubscriptionName 
 
 . 
  FromProjectSubscription 
 
 ( 
 projectId 
 , 
  
 subscriptionId 
 ), 
  
 }; 
  
 publisher 
 . 
  DetachSubscription 
 
 ( 
 detachSubscriptionRequest 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Subscription {subscriptionId} is detached." 
 ); 
  
 } 
 }

    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" 
 ) 
 func 
  
 detachSubscription 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
 , 
  
 subName 
  
 string 
 ) 
  
 error 
  
 { 
  
 // projectID is the project which contains the topic you manage. 
  
 // This might differ from the project which contains the subscription 
  
 // you wish to detach, which can exist in any GCP project. 
  
 // projectID := "my-project-id" 
  
 // subName := "projects/some-project/subscriptions/my-sub" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 pubsub 
 . 
 NewClient 
 ( 
 ctx 
 , 
  
 projectID 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "pubsub.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 // Call DetachSubscription, which detaches a subscription from 
  
 // a topic. This can only be done if you have the 
  
 // `pubsub.topics.detachSubscription` role on the topic the 
  
 // subscription is attached to. 
  
 req 
  
 := 
  
& pubsubpb 
 . 
 DetachSubscriptionRequest 
 { 
  
 Subscription 
 : 
  
 subName 
 , 
  
 } 
  
 _ 
 , 
  
 err 
  
 = 
  
 client 
 . 
 TopicAdminClient 
 . 
 DetachSubscription 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "detach subscription failed: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Detached subscription %s" 
 , 
  
 subName 
 ) 
  
 return 
  
 nil 
 }

    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 .

      import 
  
 com.google.cloud.pubsub.v1. SubscriptionAdminClient 
 
 ; 
 import 
  
 com.google.cloud.pubsub.v1. TopicAdminClient 
 
 ; 
 import 
  
 com.google.pubsub.v1. DetachSubscriptionRequest 
 
 ; 
 import 
  
 com.google.pubsub.v1. Subscription 
 
 ; 
 import 
  
 com.google.pubsub.v1. SubscriptionName 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 DetachSubscriptionExample 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 ... 
  
 args 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 // Choose an existing subscription. 
  
 String 
  
 subscriptionId 
  
 = 
  
 "your-subscription-id" 
 ; 
  
 detachSubscriptionExample 
 ( 
 projectId 
 , 
  
 subscriptionId 
 ); 
  
 } 
  
 public 
  
 static 
  
 void 
  
 detachSubscriptionExample 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 subscriptionId 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
  SubscriptionName 
 
  
 subscriptionName 
  
 = 
  
  SubscriptionName 
 
 . 
 of 
 ( 
 projectId 
 , 
  
 subscriptionId 
 ); 
  
 try 
  
 ( 
  TopicAdminClient 
 
  
 topicAdminClient 
  
 = 
  
  TopicAdminClient 
 
 . 
 create 
 ()) 
  
 { 
  
 topicAdminClient 
 . 
 detachSubscription 
 ( 
  
  DetachSubscriptionRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setSubscription 
 ( 
 subscriptionName 
 . 
  toString 
 
 ()) 
  
 . 
 build 
 ()); 
  
 } 
  
 try 
  
 ( 
  SubscriptionAdminClient 
 
  
 subscriptionAdminClient 
  
 = 
  
  SubscriptionAdminClient 
 
 . 
 create 
 ()) 
  
 { 
  
  Subscription 
 
  
 subscription 
  
 = 
  
 subscriptionAdminClient 
 . 
 getSubscription 
 ( 
 subscriptionName 
 ); 
  
 if 
  
 ( 
 subscription 
 . 
  getDetached 
 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Subscription is detached." 
 ); 
  
 } 
  
 else 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Subscription is NOT detached." 
 ); 
  
 } 
  
 } 
  
 } 
 }

    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 
  
 subscriptionNameOrId 
  
 = 
  
 'YOUR_EXISTING_SUBSCRIPTION_NAME_OR_ID' 
 ; 
 // 
  
 Imports 
  
 the 
  
 Google 
  
 Cloud 
  
 client 
  
 library 
 const 
  
 { 
 PubSub 
 } 
  
 = 
  
 require 
 ( 
 '@google-cloud/pubsub' 
 ); 
 // 
  
 Creates 
  
 a 
  
 client 
 ; 
  
 cache 
  
 this 
  
 for 
  
 further 
  
 use 
 const 
  
 pubSubClient 
  
 = 
  
 new 
  
 PubSub 
 (); 
 async 
  
 function 
  
 detachSubscription 
 ( 
 subscriptionNameOrId 
 ) 
  
 { 
  
 // 
  
 Gets 
  
 the 
  
 status 
  
 of 
  
 the 
  
 existing 
  
 subscription 
  
 const 
  
 sub 
  
 = 
  
 pubSubClient 
 . 
 subscription 
 ( 
 subscriptionNameOrId 
 ); 
  
 const 
  
 [ 
 detached 
 ] 
  
 = 
  
 await 
  
 sub 
 . 
 detached 
 (); 
  
 console 
 . 
 log 
 ( 
  
 ` 
 Subscription 
  
 ${ 
 subscriptionNameOrId 
 } 
  
 'before' 
  
 detached 
  
 status 
 : 
  
 ${ 
 detached 
 }` 
 , 
  
 ); 
  
 await 
  
 pubSubClient 
 . 
 detachSubscription 
 ( 
 subscriptionNameOrId 
 ); 
  
 console 
 . 
 log 
 ( 
 ` 
 Subscription 
  
 ${ 
 subscriptionNameOrId 
 } 
  
 detach 
  
 request 
  
 was 
  
 sent 
 . 
 ` 
 ); 
  
 const 
  
 [ 
 updatedDetached 
 ] 
  
 = 
  
 await 
  
 sub 
 . 
 detached 
 (); 
  
 console 
 . 
 log 
 ( 
  
 ` 
 Subscription 
  
 ${ 
 subscriptionNameOrId 
 } 
  
 'after' 
  
 detached 
  
 status 
 : 
  
 ${ 
 updatedDetached 
 }` 
 , 
  
 ); 
 }

    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 
 subscriptionNameOrId 
 = 
 'YOUR_EXISTING_SUBSCRIPTION_NAME_OR_ID' 
 ; 
 // 
 Imports 
 the 
 Google 
 Cloud 
 client 
 library 
 import 
  
 { 
 PubSub 
 } 
 from 
  
 '@google-cloud/pubsub' 
 ; 
 // 
 Creates 
 a 
 client 
 ; 
 cache 
 this 
 for 
 further 
 use 
 const 
 pubSubClient 
 = 
 new 
 PubSub 
 (); 
 async 
 function 
 detachSubscription 
 ( 
 subscriptionNameOrId 
 : 
 string 
 ) 
 { 
 // 
 Gets 
 the 
 status 
 of 
 the 
 existing 
 subscription 
 const 
 sub 
 = 
 pubSubClient 
 . 
 subscription 
 ( 
 subscriptionNameOrId 
 ); 
 const 
 [ 
 detached 
 ] 
 = 
 await 
 sub 
 . 
 detached 
 (); 
 console 
 . 
 log 
 ( 
 ` 
 Subscription 
 $ 
 { 
 subscriptionNameOrId 
 } 
 'before' 
 detached 
 status 
 : 
 $ 
 { 
 detached 
 } 
 ` 
 , 
 ); 
 await 
 pubSubClient 
 . 
 detachSubscription 
 ( 
 subscriptionNameOrId 
 ); 
 console 
 . 
 log 
 ( 
 ` 
 Subscription 
 $ 
 { 
 subscriptionNameOrId 
 } 
 detach 
 request 
 was 
 sent 
 . 
 ` 
 ); 
 const 
 [ 
 updatedDetached 
 ] 
 = 
 await 
 sub 
 . 
 detached 
 (); 
 console 
 . 
 log 
 ( 
 ` 
 Subscription 
 $ 
 { 
 subscriptionNameOrId 
 } 
 'after' 
 detached 
 status 
 : 
 $ 
 { 
 updatedDetached 
 } 
 ` 
 , 
 ); 
 }

    PHP

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

      use Google\Cloud\PubSub\PubSubClient; 
 /** 
 * Detach a Pub/Sub subscription from a topic. 
 * 
 * @param string $projectId  The Google project ID. 
 * @param string $subscriptionName  The Pub/Sub subscription name. 
 */ 
 function detach_subscription($projectId, $subscriptionName) 
 { 
 $pubsub = new PubSubClient([ 
 'projectId' => $projectId, 
 ]); 
 $subscription = $pubsub->subscription($subscriptionName); 
 $subscription->detach(); 
 printf('Subscription detached: %s' . PHP_EOL, $subscription->name()); 
 }

    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 .

      from 
  
 google.api_core.exceptions 
  
 import 
 GoogleAPICallError 
 , 
 RetryError 
 from 
  
 google.cloud 
  
 import 
 pubsub_v1 
 # TODO(developer): Choose an existing subscription. 
 # project_id = "your-project-id" 
 # subscription_id = "your-subscription-id" 
 publisher_client 
 = 
 pubsub_v1 
 . 
  PublisherClient 
 
 () 
 subscriber_client 
 = 
 pubsub_v1 
 . 
  SubscriberClient 
 
 () 
 subscription_path 
 = 
  subscriber_client 
 
 . 
 subscription_path 
 ( 
 project_id 
 , 
 subscription_id 
 ) 
 try 
 : 
  publisher_client 
 
 . 
  detach_subscription 
 
 ( 
 request 
 = 
 { 
 "subscription" 
 : 
 subscription_path 
 } 
 ) 
 except 
 ( 
 GoogleAPICallError 
 , 
 RetryError 
 , 
 ValueError 
 , 
 Exception 
 ) 
 as 
 err 
 : 
 print 
 ( 
 err 
 ) 
 subscription 
 = 
  subscriber_client 
 
 . 
 get_subscription 
 ( 
 request 
 = 
 { 
 "subscription" 
 : 
 subscription_path 
 } 
 ) 
 if 
 subscription 
 . 
 detached 
 : 
 print 
 ( 
 f 
 " 
 { 
 subscription_path 
 } 
 is detached." 
 ) 
 else 
 : 
 print 
 ( 
 f 
 " 
 { 
 subscription_path 
 } 
 is NOT detached." 
 )

    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" 
 pubsub 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  PubSub 
 
 . 
  new 
 
 topic_admin 
  
 = 
  
 pubsub 
 . 
  topic_admin 
 
 subscription_admin 
  
 = 
  
 pubsub 
 . 
  subscription_admin 
 
 subscription_path 
  
 = 
  
 pubsub 
 . 
 subscription_path 
  
 subscription_id 
 topic_admin 
 . 
 detach_subscription 
  
 subscription 
 : 
  
 subscription_path 
 sleep 
  
 120 
 subscription 
  
 = 
  
 subscription_admin 
 . 
 get_subscription 
  
 \ 
  
 subscription 
 : 
  
 subscription_path 
 if 
  
 subscription 
 . 
  detached 
 
  
 puts 
  
 "Subscription is detached." 
 else 
  
 puts 
  
 "Subscription is NOT detached." 
 end

    The Pub/Sub service might take several minutes to finish detaching the subscription from the topic.

    After the Pub/Sub service detaches the subscription from the topic, the Pub/Sub service deletes any messages that it retains for the subscription. You can't retrieve these messages from the subscription or reattach the subscription to a topic. To free up your Google Cloud project quota, delete the subscription .

    If the subscription and the topic are in different Google Cloud projects, the Pub/Sub service adds an entry to the audit logs of both projects.

    What's next
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: