주제 만들기

Pub/Sub 내에서 주제는 이름이 지정된 리소스이며, 메시지 피드를 나타냅니다. 주제를 게시하거나 구독하려면 주제를 만들어야 합니다. Pub/Sub는 표준 주제와 가져오기 주제 등 두 가지 종류의 주제를 지원합니다.

이 문서에서는 Pub/Sub 표준 주제를 만드는 방법을 설명합니다. 가져오기 주제와 만드는 방법에 대한 자세한 내용은 가져오기 주제 정보를 참고하세요.

주제를 만들려면 Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리, Pub/Sub API를 사용하면 됩니다.

시작하기 전에

주제 관리를 위한 필수 역할 및 권한

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

이 사전 정의된 역할에는 주제 생성 및 관리를 위해 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

주제를 만들고 관리하려면 다음 권한이 필요합니다.

  • 주제 만들기: pubsub.topics.create
  • 주제 삭제: pubsub.topics.delete
  • 주제에서 구독 분리: pubsub.topics.detachSubscription
  • 주제 가져오기: pubsub.topics.get
  • 주제 나열: pubsub.topics.list
  • 주제에 게시: pubsub.topics.publish
  • 주제 업데이트: pubsub.topics.update
  • 주제의 IAM 정책 가져오기: pubsub.topics.getIamPolicy
  • 주제의 IAM 정책 구성: pubsub.topics.setIamPolicy

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

프로젝트 수준 및 개별 리소스 수준에서 액세스 제어를 구성할 수 있습니다. 한 프로젝트에서 구독을 만들고 이를 다른 프로젝트에 있는 주제에 연결할 수 있습니다. 각 프로젝트에 필요한 권한이 있는지 확인합니다.

주제 속성

주제를 만들거나 업데이트할 때 해당 속성을 지정해야 합니다.

기본 구독 추가

Pub/Sub 주제에 기본 구독을 추가합니다. 주제가 생성된 후에 주제의 다른 구독을 만들 수 있습니다. 기본 구독에는 다음과 같은 속성이 있습니다.

  • -sub의 구독 ID
  • 가져오기 전송 유형
  • 메시지 보관 기간 7일
  • 31일 동안 활동이 없으면 만료됨
  • 확인 기한 10초
  • 즉시 재시도 정책

스키마 사용

스키마는 메시지 데이터 필드가 따라야 하는 형식입니다. 스키마는 Pub/Sub가 적용하는 게시자와 구독자 간의 계약입니다. 주제 스키마는 메시지 유형과 권한을 표준화하여 조직의 여러 팀에서 사용할 수 있도록 합니다. Pub/Sub는 메시지 유형 및 권한을 위한 중앙 권한을 만듭니다. 스키마를 사용해서 주제를 만들려면 스키마 개요를 참조하세요.

수집 사용 설정

이 속성을 사용 설정하면 Google Cloud의 기능을 활용할 수 있도록 외부 소스의 스트리밍 데이터를 주제로 수집할 수 있습니다. 수집을 위한 가져오기 주제를 만들려면 다음을 참고하세요.

메시지 보관 사용

게시 후 Pub/Sub 주제에서 메시지를 보관하는 기간을 지정합니다. 메시지 보관 기간이 끝나면 Pub/Sub는 확인 상태에 관계없이 메시지를 삭제할 수 있습니다. 주제에 게시된 모든 메시지를 저장할 때 메시지 스토리지 요금이 청구됩니다.

  • 기본값 = 사용 설정되지 않음
  • 최솟값 = 10분
  • 최댓값 = 31일

BigQuery로 메시지 데이터 내보내기

이 속성을 사용 설정하면 수신되는 메시지를 기존 BigQuery 테이블에 쓰는 BigQuery 구독을 만들 수 있습니다. 별도의 구독자 클라이언트를 구성할 필요가 없습니다. BigQuery 구독에 대한 자세한 내용은 BigQuery 구독을 참조하세요.

Cloud Storage로 메시지 데이터 내보내기

이 속성을 사용 설정하면 수신되는 메시지를 기존 Cloud Storage 테이블에 쓰는 Cloud Storage 구독을 만들 수 있습니다. 별도의 구독자 클라이언트를 구성할 필요가 없습니다. Cloud Storage 구독에 대한 자세한 내용은 Cloud Storage 구독을 참조하세요.

Google 관리 암호화 키

주제가 Google 관리 암호화 키를 사용하여 암호화된다고 지정합니다. Pub/Sub는 기본적으로 Google 관리 키로 메시지를 암호화하므로 이 옵션을 선택하면 기본 동작이 유지됩니다. Google은 키 관리 및 순환을 자동으로 처리하므로 메시지가 항상 사용 가능한 가장 강력한 암호화로 보호됩니다. 이 옵션에는 추가 구성이 필요하지 않습니다. Google 관리 암호화 키에 대한 자세한 내용은 Google 소유 키 및 Google 관리 키를 사용한 기본 암호화를 참조하세요.

Cloud KMS 키

주제가 고객 관리 암호화 키(CMEK)로 암호화되는지 여부를 지정합니다. Pub/Sub는 기본적으로 Google 소유 및 Google 관리 키로 메시지를 암호화합니다. 이 옵션을 지정하면 Pub/Sub에서 CMEK를 사용하는 봉투 암호화 패턴을 사용합니다. 이 방식에서 Cloud KMS는 메시지를 암호화하지 않습니다. 대신 Cloud KMS는 Pub/Sub에서 각 주제에 만드는 데이터 암호화 키(DEK)를 암호화합니다. Pub/Sub는 주제에 생성된 최신 DEK를 사용하여 메시지를 암호화합니다. Pub/Sub는 메시지가 구독자에게 전달되기 직전에 메시지를 복호화합니다. 키 만들기에 대한 자세한 내용은 메시지 암호화 구성을 참조하세요.

주제 만들기

주제를 게시하거나 구독하려면 먼저 주제를 만들어야 합니다.

콘솔

주제를 만들려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 Pub/Sub 주제 페이지로 이동합니다.

    주제로 이동

  2. 주제 만들기를 클릭합니다.

  3. 주제 ID 필드에 주제의 ID를 입력합니다. 주제 이름 지정에 대한 자세한 내용은 이름 지정 가이드라인을 참조하세요.

  4. 기본 구독 추가 옵션을 유지합니다.

  5. 선택사항. 다른 옵션을 선택하지 마세요.

  6. 주제 만들기를 클릭합니다.

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. 주제를 만들려면 gcloud pubsub topics create 명령어를 실행합니다.

    gcloud pubsub topics create TOPIC_ID

REST

주제를 만들려면 projects.topics.create 메서드를 사용합니다.

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

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
    

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

  • PROJECT_ID는 프로젝트 ID입니다.
  • TOPIC_ID는 주제 ID입니다.
  • 응답:

    {
     "name": "projects/PROJECT_ID/topics/TOPIC_ID"
    }

    C++

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

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

    namespace pubsub = ::google::cloud::pubsub;
    namespace pubsub_admin = ::google::cloud::pubsub_admin;
    [](pubsub_admin::TopicAdminClient client, std::string project_id,
       std::string topic_id) {
      auto topic = client.CreateTopic(
          pubsub::Topic(std::move(project_id), std::move(topic_id)).FullName());
      // Note that kAlreadyExists is a possible error when the library retries.
      if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
        std::cout << "The topic already exists\n";
        return;
      }
      if (!topic) throw std::move(topic).status();
    
      std::cout << "The topic was successfully created: " << topic->DebugString()
                << "\n";
    }

    C#

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

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

    
    using Google.Cloud.PubSub.V1;
    using Grpc.Core;
    using System;
    
    public class CreateTopicSample
    {
        public Topic CreateTopic(string projectId, string topicId)
        {
            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
            var topicName = TopicName.FromProjectTopic(projectId, topicId);
            Topic topic = null;
    
            try
            {
                topic = publisher.CreateTopic(topicName);
                Console.WriteLine($"Topic {topic.Name} created.");
            }
            catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
            {
                Console.WriteLine($"Topic {topicName} already exists.");
            }
            return topic;
        }
    }

    Go

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

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

    import (
    	"context"
    	"fmt"
    	"io"
    
    	"cloud.google.com/go/pubsub"
    )
    
    func create(w io.Writer, projectID, topicID string) error {
    	// projectID := "my-project-id"
    	// topicID := "my-topic"
    	ctx := context.Background()
    	client, err := pubsub.NewClient(ctx, projectID)
    	if err != nil {
    		return fmt.Errorf("pubsub.NewClient: %w", err)
    	}
    	defer client.Close()
    
    	t, err := client.CreateTopic(ctx, topicID)
    	if err != nil {
    		return fmt.Errorf("CreateTopic: %w", err)
    	}
    	fmt.Fprintf(w, "Topic created: %v\n", t)
    	return nil
    }
    

    Java

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

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

    
    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.Topic;
    import com.google.pubsub.v1.TopicName;
    import java.io.IOException;
    
    public class CreateTopicExample {
      public static void main(String... args) throws Exception {
        // TODO(developer): Replace these variables before running the sample.
        String projectId = "your-project-id";
        String topicId = "your-topic-id";
    
        createTopicExample(projectId, topicId);
      }
    
      public static void createTopicExample(String projectId, String topicId) throws IOException {
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
          TopicName topicName = TopicName.of(projectId, topicId);
          Topic topic = topicAdminClient.createTopic(topicName);
          System.out.println("Created topic: " + topic.getName());
        }
      }
    }

    Node.js

    /**
     * TODO(developer): Uncomment this variable before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_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 createTopic(topicNameOrId) {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }

    Node.js

    /**
     * TODO(developer): Uncomment this variable before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_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 createTopic(topicNameOrId: string) {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }

    PHP

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

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

    use Google\Cloud\PubSub\PubSubClient;
    
    /**
     * Creates a Pub/Sub topic.
     *
     * @param string $projectId  The Google project ID.
     * @param string $topicName  The Pub/Sub topic name.
     */
    function create_topic($projectId, $topicName)
    {
        $pubsub = new PubSubClient([
            'projectId' => $projectId,
        ]);
        $topic = $pubsub->createTopic($topicName);
    
        printf('Topic created: %s' . PHP_EOL, $topic->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"
    
    publisher = pubsub_v1.PublisherClient()
    topic_path = publisher.topic_path(project_id, topic_id)
    
    topic = publisher.create_topic(request={"name": topic_path})
    
    print(f"Created topic: {topic.name}")

    Ruby

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

    Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

    # topic_id = "your-topic-id"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic = pubsub.create_topic topic_id
    
    puts "Topic #{topic.name} created."

    조직 정책 제약조건

    조직 정책은 주제 생성을 제한할 수 있습니다. 예를 들어 정책이 Compute Engine 리전의 메시지 스토리지를 제한할 수 있습니다. 주제 생성 오류를 방지하려면 주제를 만들기 전에 필요에 따라 조직 정책을 검사하고 업데이트합니다.

    프로젝트가 새로 생성된 경우 조직 정책이 초기화될 때까지 몇 분 정도 기다린 후에 주제를 만듭니다.

    조직 정책으로 이동

    자세한 내용은 메시지 스토리지 정책 구성을 참조하세요.

    다음 단계