push 구독 만들기

이 문서에서는 push 구독을 만드는 방법을 설명합니다. Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리, Pub/Sub API를 사용하여 push 구독을 만들 수 있습니다.

시작하기 전에

필수 역할 및 권한

구독을 만들려면 프로젝트 수준에서 액세스 제어를 구성해야 합니다. 또한 이 섹션의 뒷부분에서 설명하는 것처럼 구독과 주제가 다른 프로젝트에 있는 경우 리소스 수준 권한도 필요합니다.

push 구독을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Pub/Sub 편집자(roles/pubsub.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 push 구독을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

push 구독을 만들려면 다음 권한이 필요합니다.

  • 구독 만들기: pubsub.subscriptions.create
  • 구독 삭제: pubsub.subscriptions.delete
  • 구독 가져오기: pubsub.subscriptions.get
  • 구독 나열: pubsub.subscriptions.list
  • 구독 업데이트: pubsub.subscriptions.update
  • 주제에 구독 연결하기: pubsub.topics.attachSubscription
  • 구독의 IAM 정책 가져오기: pubsub.subscriptions.getIamPolicy
  • 구독의 IAM 정책 구성: pubsub.subscriptions.setIamPolicy

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

한 프로젝트에서 다른 프로젝트의 주제와 연결된 push 구독을 만들어야 하는 경우 주제 관리자에게 주제에 대한 Pub/Sub 편집자 (roles/pubsub.editor) IAM 역할도 부여해 달라고 요청하세요.

push 구독 속성

push 구독을 구성할 때 다음 속성을 지정할 수 있습니다.

일반 속성

모든 구독에 설정할 수 있는 일반적인 구독 속성에 대해 알아봅니다.

엔드포인트

엔드포인트 URL(필수) 공개적으로 액세스 가능한 HTTPS 주소입니다. push 엔드포인트의 서버에는 인증 기관에서 서명된 유효한 SSL 인증서가 있어야 합니다. Pub/Sub 서비스는 Pub/Sub 서비스가 메시지를 저장하는 것과 동일한 Google Cloud 리전에서 엔드포인트를 push하는 메시지를 전송합니다. Pub/Sub 서비스는 최선의 방식으로 Google Cloud 리전에서 메시지를 전송합니다.

Pub/Sub에는 push 구독 URL 도메인의 소유권 증명이 더 이상 필요하지 않습니다. 도메인에서 Pub/Sub의 예상치 못한 POST 요청을 받으면 악용 사례로 의심되는 항목을 신고할 수 있습니다.

인증

인증 사용 설정. 사용 설정하면 Pub/Sub에서 push 엔드포인트로 전달되는 메시지에는 엔드포인트가 요청을 인증할 수 있는 승인 헤더가 포함됩니다. 구독과 동일한 프로젝트에 호스팅된 App Engine 표준 및 Cloud Run 함수 엔드포인트에 자동 인증 및 승인 메커니즘을 사용할 수 있습니다.

인증된 push 구독의 인증 구성은 사용자 관리형 서비스 계정 및 create, patch, 또는 ModifyPushConfig 호출에 지정된 잠재고객 매개변수로 구성됩니다. 또한 다음 섹션에서 설명하는 것처럼 서비스 에이전트에 특정 역할을 부여해야 합니다.

  • 사용자 관리형 서비스 계정(필수). push 구독과 관련된 서비스 계정입니다. 이 계정은 생성된 JSON 웹 토큰(JWT)의 email 클레임으로 사용됩니다. 다음은 서비스 계정의 요구사항 목록입니다.

  • 잠재고객. 특정 토큰의 의도한 잠재고객을 검증하기 위해 웹훅에서 사용하는 대소문자를 구분하지 않는 단일 문자열입니다.

  • 서비스 에이전트(필수).

    • Pub/Sub는 service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com 형식으로 서비스 계정을 자동으로 만듭니다.

    • Pub/Sub가 인증된 push 요청에 대한 JWT 토큰을 만들도록 허용하려면 이 서비스 에이전트에 roles/iam.serviceAccountTokenCreator 역할에 포함된 iam.serviceAccounts.getOpenIdToken 권한을 부여해야 합니다.

페이로드 래핑 해제

페이로드 래핑 해제 사용 설정 옵션은 메시지 데이터를 제외한 모든 메시지 메타데이터의 Pub/Sub 메시지를 제거합니다. 페이로드의 래핑을 해제하면 메시지 데이터가 HTTP 본문으로 직접 전달됩니다.

  • 메타데이터 쓰기. 이전에 삭제된 메시지 메타데이터를 요청 헤더에 다시 추가합니다.

VPC 서비스 제어

VPC 서비스 제어로 보호되는 프로젝트의 경우 push 구독의 다음 제한사항에 유의하세요.

  • push 엔드포인트가 기본 run.app URL 또는 Workflows 실행을 통해 Cloud Run 서비스로 설정된 새로운 push 구독만 만들 수 있습니다. 커스텀 도메인은 작동하지 않습니다.

  • push 엔드포인트가 Workflows 실행으로 설정된 Workflows 대상으로 Eventarc를 통해 이벤트를 라우팅하는 경우 Eventarc를 통해서만 새 push 구독을 만들 수 있습니다.

  • 기존의 push 구독은 업데이트할 수 없습니다. 이러한 push 구독은 VPC 서비스 제어로 보호되지 않더라도 계속 작동합니다.

푸시 구독 만들기

다음 샘플은 제공된 기본 설정을 사용하여 내보내기 전송으로 구독을 만드는 방법을 보여줍니다.

다음 예시와 같이 push 구성을 명시적으로 설정하지 않는 한 기본적으로 구독은 pull 전송을 사용합니다.

콘솔

push 구독을 수정하려면 다음 단계를 완료하세요.

  1. Google Cloud 콘솔에서 구독 페이지로 이동합니다.

    구독 페이지로 이동

  2. 구독 만들기를 클릭합니다.
  3. 구독 ID 필드에 이름을 입력합니다.

    구독 이름 지정 방법은 주제 또는 구독 이름 지정 안내를 참조하세요.

  4. 드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다. 구독은 주제에서 메시지를 수신합니다.
  5. 전송 유형을 push로 선택합니다.
  6. 엔드포인트 URL을 지정합니다.
  7. 다른 모든 기본값을 유지합니다.
  8. 만들기를 클릭합니다.

주제 섹션에서도 구독을 만들 수 있습니다. 이 단축키는 주제를 구독과 연결하는 데 유용합니다.

  1. Google Cloud console에서 IAM 페이지로 이동합니다.

    주제로 이동

  2. 구독을 만들 주제 옆에 있는 를 클릭합니다.
  3. 컨텍스트 메뉴에서 구독 만들기를 선택합니다.
  4. 구독 ID를 입력합니다.

    구독 이름 지정 방법은 주제 또는 구독 이름 지정 안내를 참조하세요.

  5. 전송 유형을 push로 선택합니다.
  6. 엔드포인트 URL을 지정합니다.
  7. 다른 모든 기본값을 유지합니다.
  8. 만들기를 클릭합니다.

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. push 구독을 만들려면 gcloud pubsub subscriptions create 명령어를 실행합니다.

    gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --push-endpoint=PUSH_ENDPOINT

    다음을 바꿉니다.

    • SUBSCRIPTION_ID: 새 push 구독의 이름 또는 ID
    • TOPIC_ID: 주제의 이름 또는 ID
    • PUSH_ENDPOINT: 이 구독의 엔드포인트로 사용할 URL. 예를 들면 https://myproject.appspot.com/myhandler입니다.

REST

push 구독을 만들려면 projects.subscriptions.create 메서드를 사용합니다.

요청:

요청은 Authorization 헤더의 액세스 토큰으로 인증해야 합니다. 현재 애플리케이션 기본 사용자 인증 정보의 액세스 토큰을 얻으려면 gcloud auth application-default print-access-token을 실행합니다.

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

요청 본문:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  // Only needed if you are using push delivery
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  }
}

각 항목의 의미는 다음과 같습니다.

  • PROJECT_ID는 프로젝트 ID입니다.
  • SUBSCRIPTION_ID는 구독 ID입니다.
  • TOPIC_ID는 주제 ID입니다.
  • PUSH_ENDPOINT는 엔드포인트로 사용할 URL입니다. 예를 들면 https://myproject.appspot.com/myhandler입니다.

    • 응답:

    {
  "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "pushConfig": {
    "pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler",
    "attributes": {
      "x-goog-version": "v1"
    }
  },
  "ackDeadlineSeconds": 10,
  "messageRetentionDuration": "604800s",
  "expirationPolicy": {
    "ttl": "2678400s"
  }
}

    C++

    이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C++ 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C++ API 참고 문서를 확인하세요. 

    namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& endpoint) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";

    C#

    이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C# API 참고 문서를 확인하세요.

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

    
using Google.Cloud.PubSub.V1;

public class CreatePushSubscriptionSample
{
    public Subscription CreatePushSubscription(string projectId, string topicId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        // The approximate amount of time in seconds (on a best-effort basis) Pub/Sub waits for the
        // subscriber to acknowledge receipt before resending the message.
        var ackDeadlineSeconds = 60;
        var subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig, ackDeadlineSeconds);
        return subscription;
    }
}

    Go

    이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참고 문서를 확인하세요.

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

    import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

func createWithEndpoint(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// 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()

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:       topic,
		AckDeadline: 10 * time.Second,
		PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created push subscription: %v\n", sub)
	return nil
}

    Java

    이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Java API 참고 문서를 확인하세요.

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

    
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 com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePushSubscriptionExample {
  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 topicId = "your-topic-id";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(subscriptionName, topicName, pushConfig, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

    Node.js

    /**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// 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 createPushSubscription(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

    Node.js

    /**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// 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 createPushSubscription(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

    PHP

    이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 PHP 설정 안내를 따르세요. 자세한 내용은 Pub/Sub PHP API 참고 문서를 확인하세요.

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

    use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub push subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $endpoint  The endpoint for the push subscription.
 */
function create_push_subscription($projectId, $topicName, $subscriptionName, $endpoint)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'pushConfig' => ['pushEndpoint' => $endpoint]
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

    Python

    이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Python API 참고 문서를 확인하세요.

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

    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"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "push_config": push_config,
        }
    )

print(f"Push subscription created: {subscription}.")
print(f"Endpoint for subscription is: {endpoint}")

    Ruby

    이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Ruby API 참고 문서를 확인하세요.

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

    # topic_id          = "your-topic-id"
# subscription_id   = "your-subscription-id"
# endpoint          = "https://your-test-project.appspot.com/push"

pubsub = Google::Cloud::Pubsub.new

topic        = pubsub.topic topic_id
subscription = topic.subscribe subscription_id,
                               endpoint: endpoint

puts "Push subscription #{subscription_id} created."

    푸시 구독 모니터링

    Cloud Monitoring은 구독을 모니터링하기 위한 여러 측정항목을 제공합니다.

    Pub/Sub와 관련하여 사용 가능한 모든 측정항목 및 설명 목록은 Pub/Sub 모니터링 문서를 참조하세요.

    Pub/Sub 내에서도 구독을 모니터링할 수 있습니다.

    다음 단계