變更訂閱類型

建立訂閱項目後，您可以將傳送方式變更為推送、提取或匯出。

事前準備

必要角色和權限

如要取得變更訂閱類型的權限，請要求管理員授予您訂閱項目的 Pub/Sub 編輯者 (roles/pubsub.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 pubsub.subscriptions.update 權限，可變更訂閱類型。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

您可以在專案層級和個別資源層級設定存取控管。您可以在一個專案中建立訂閱項目，並將其附加至其他專案中的主題。請確認您具備每個專案的必要權限。

變更訂閱項目的貨品交付類型

如要變更訂閱項目的運送方式，請按照下列步驟操作。

控制台

  1. 前往 Google Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。

    前往「訂閱項目」頁面

  2. 按一下要更新的訂閱項目名稱。

  3. 在訂閱詳細資料頁面中，按一下「編輯」。

  4. 在「傳送類型」中，選取新的傳送類型。

  5. 填寫新訂閱類型的屬性。詳情請參閱下列主題：

  6. 選用。視需要更新其他訂閱方案屬性。

  7. 按一下「Update」。

gcloud

如要變更傳送類型，請使用 gcloud pubsub subscriptions update 指令。清除目前運送類型的設定，並為新類型設定，如下所示：

gcloud pubsub subscriptions update SUBSCRIPTION_ID \
  CLEAR_CONFIG_FLAG \
  NEW_CONFIG_FLAGS

更改下列內容：

  • SUBSCRIPTION_ID：要更新的訂閱項目名稱。

  • CLEAR_CONFIG_FLAG：清除遞送類型現有設定的旗標。請根據目前的運送方式，使用下列其中一個標記：

    • 提取訂閱項目：--no-enable-exactly-once-delivery

    • 推送訂閱項目：--push-endpoint=""

    • BigQuery 訂閱項目：--clear-bigquery-config

    • 儲存空間訂閱方案：--clear-cloud-storage-config

  • NEW_CONFIG_FLAGS：設定新放送類型的旗標。詳情請參閱 gcloud pubsub subscriptions update 指令的說明文件。

範例

將 BigQuery 訂閱項目變更為提取訂閱項目：

gcloud pubsub subscriptions update SUBSCRIPTION_ID \
  --clear-bigquery-config

將推送訂閱項目變更為 BigQuery 訂閱項目：

gcloud pubsub subscriptions update SUBSCRIPTION_ID \
  --push-endpoint="" \
  --bigquery-table=BIGQUERY_TABLE

更新推送訂閱項目端點

如要更新推送訂閱項目的端點網址，請按照下列步驟操作。

控制台

如要修改端點網址，請完成下列步驟。

  1. 前往 Google Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。

    前往「訂閱」頁面

  2. 按一下要更新的訂閱項目旁邊的 。
  3. 在「配送類型」中，選擇配送選項。
  4. 視需要填寫其他訂閱屬性。
  5. 按一下「Update」。

gcloud

  1. 在 Google Cloud 控制台中啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

  2. 如要修改端點網址，請執行 gcloud pubsub subscriptions modify-push-config 指令：

    gcloud pubsub subscriptions modify-push-config SUBSCRIPTION_ID \
  --push-endpoint=PUSH_ENDPOINT

    如果訂閱項目已使用提取傳送，設定推送端點會將傳送方式切換為推送傳送。

    如要從推送傳送切換為提取傳送，請將推送端點變更為空字串。

REST

如要修改訂閱的推送設定，請使用 projects.subscriptions.modifyPushConfig 方法：

要求：

要求必須使用 Authorization 標頭中的存取權杖進行驗證。如要取得目前應用程式預設憑證的存取權杖，請執行 gcloud auth application-default print-access-token。

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

要求主體：

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

其中：

  • PROJECT_ID 是您的專案 ID。
  • SUBSCRIPTION_ID 是您的訂閱 ID。
  • PUSH_ENDPOINT 是您要套用為新推送端點的修改後網址。例如：https://myproject.appspot.com/myhandler。

    • 回應：

    如果要求成功，回應會是空白的 JSON 物件。

    C++

    在試用這個範例之前，請先按照快速入門導覽課程：使用用戶端程式庫中的 C++ 設定操作說明進行操作。詳情請參閱 Pub/Sub C++ API 參考文件。

    namespace pubsub_admin = ::google::cloud::pubsub_admin;
namespace pubsub = ::google::cloud::pubsub;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& subscription_id,
   std::string const& endpoint) {
  google::pubsub::v1::ModifyPushConfigRequest request;
  request.set_subscription(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  auto status = client.ModifyPushConfig(request);
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "The subscription push configuration was successfully"
            << " modified\n";
}

    C#

    在嘗試這個範例之前，請先按照快速入門：使用用戶端程式庫中的 C# 設定操作說明進行操作。詳情請參閱 Pub/Sub C# API 參考文件。

    
using Google.Cloud.PubSub.V1;

public class UpdatePushConfigurationSample
{
    public void UpdatePushConfiguration(string projectId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        subscriber.ModifyPushConfig(subscriptionName, pushConfig);
    }
}

    Go

    下列範例使用 Go Pub/Sub 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫，請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單，請參閱 已淘汰的程式碼範例。

    在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的操作說明設定 Go 環境。詳情請參閱 Pub/Sub Go API 參考文件。

    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"
)

func updateEndpoint(w io.Writer, projectID, subscriptionName, endpoint string) 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)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.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)
	if err != nil {
		return fmt.Errorf("Update: %w", err)
	}
	fmt.Fprintf(w, "Updated subscription config: %v\n", subConfig)
	return nil
}

    Java

    在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的 Java 設定操作說明進行操作。詳情請參閱 Pub/Sub Java API 參考說明文件。 

    
import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
import java.io.IOException;

public class UpdatePushConfigurationExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    updatePushConfigurationExample(projectId, subscriptionId, pushEndpoint);
  }

  public static void updatePushConfigurationExample(
      String projectId, String subscriptionId, String pushEndpoint) throws IOException {
    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

    在嘗試這個範例之前，請先按照快速入門導覽課程：使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 Pub/Sub Node.js API 參考文件。

    /**
 * 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
const pubSubClient = new PubSub();

async function modifyPushConfig(topicNameOrId, subscriptionNameOrId) {
  const options = {
    // 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}.`);
}

    Node.ts

    在嘗試這個範例之前，請先按照快速入門導覽課程：使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 Pub/Sub Node.js API 參考文件。

    /**
 * 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

    在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 Pub/Sub Python API 參考說明文件。 

    from google.cloud import 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

    以下範例使用 Ruby Pub/Sub 用戶端程式庫 v3。如果您仍在使用第 2 版程式庫，請參閱 第 3 版遷移指南。如要查看 Ruby 第 2 版程式碼範例清單，請參閱 已淘汰的程式碼範例。

    在試用這個範例之前，請先按照「快速入門：使用用戶端程式庫」的操作說明設定 Ruby 環境。詳情請參閱 Pub/Sub Ruby API 參考文件。

    # 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_subscription subscription: subscription,
                                       update_mask: {
                                         paths: ["push_config"]
                                       }

puts "Push endpoint updated."

    後續步驟