יצירת נושא

ב-Pub/Sub, נושא הוא משאב עם שם שמייצג פיד של הודעות. כדי לפרסם נושא או להירשם אליו, צריך קודם ליצור אותו. ב-Pub/Sub יש תמיכה בשני סוגים של נושאים: נושא רגיל ונושא ייבוא.

במאמר הזה מוסבר איך ליצור נושא רגיל ב-Pub/Sub. אם אתם רוצים לקבל מידע נוסף על נושאים לייבוא ועל אופן היצירה שלהם, אתם יכולים לעיין במאמר מידע על נושאים לייבוא.

כדי ליצור נושא, אפשר להשתמש במסוף Google Cloud , ב-Google Cloud CLI, בספריית הלקוח או ב-Pub/Sub API.

לפני שמתחילים

• מידע על שירות Pub/Sub והטרמינולוגיה שלו

• מידע נוסף על תהליך הפרסום

תפקידים והרשאות נדרשים

כדי לקבל את ההרשאות שנדרשות ליצירת נושא, צריך לבקש מהאדמין להקצות לכם את התפקיד 'עורך Pub/Sub' (roles/pubsub.editor) ב-IAM בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

זהו תפקיד שמוגדר מראש וכולל את ההרשאות שנדרשות ליצירת נושא. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי ליצור נושא, צריך את ההרשאות הבאות:

• כדי ליצור נושא בפרויקט, צריך לתת את ההרשאה הזו: pubsub.topics.create

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

אפשר להגדיר בקרת גישה ברמת הפרויקט וברמת המשאב הספציפי. אפשר ליצור מינוי בפרויקט אחד ולצרף אותו לנושא שנמצא בפרויקט אחר. מוודאים שיש לכם את ההרשאות הנדרשות לכל פרויקט.

מאפיינים של נושא

כשיוצרים או מעדכנים נושא, צריך לציין את המאפיינים שלו.

הוספת מינוי ברירת מחדל

הוספת מינוי שמוגדר כברירת מחדל לנושא ב-Pub/Sub. אחרי שיוצרים את הנושא, אפשר ליצור מינוי נוסף לנושא. למינוי שמוגדר כברירת מחדל יש את המאפיינים הבאים:

• מזהה המינוי של -sub
• סוג משלוח Pull
• משך השמירה של ההודעות הוא שבעה ימים
• תוקף המבצע יפוג אחרי 31 ימים ללא פעילות
• מועד האישור הוא 10 שניות
• מדיניות ניסיון חוזר מיידי

שימוש בסכימה

סכימה היא פורמט ששדה הנתונים של ההודעה צריך להיות בהתאם אליו. סכימה היא חוזה בין בעל האתר לבין המנוי, ש-Pub/Sub אוכף. סכימות של נושאים עוזרות לתקנן את סוגי ההודעות וההרשאות כדי לאפשר לצוותים שונים בארגון להשתמש בהן. ב-Pub/Sub נוצרת רשות מרכזית לסוגי הודעות ולהרשאות. כדי ליצור נושא עם סכימה, אפשר לעיין במאמר סקירה כללית על סכימות.

הפעלת ההטמעה

הפעלת המאפיין הזה מאפשרת לכם להטמיע נתונים בזמן אמת ממקורות חיצוניים בנושא, כדי שתוכלו להשתמש בתכונות של Google Cloud. כדי ליצור נושא לייבוא לצורך הטמעה, אפשר לעיין במאמרים הבאים:

• יצירת נושא ייבוא של Amazon Kinesis Data Streams

• יצירת נושא לייבוא ב-Cloud Storage

• יצירת נושא ב-Azure Event Hubs

• יצירת נושא ב-Amazon MSK

• יצירת נושא ב-Confluent Cloud

הפעלת שמירת הודעות

ההגדרה הזו קובעת כמה זמן הודעות בנושא Pub/Sub יישמרו אחרי הפרסום שלהן. אחרי שמשך שמירת ההודעה מסתיים, יכול להיות שמערכת Pub/Sub תמחק את ההודעה בלי קשר למצב האישור שלה. תשלום על אחסון הודעות נגבה על אחסון של כל ההודעות שפורסמו בנושא

• ברירת מחדל = לא מופעל
• ערך מינימלי = 10 דקות
• הערך המקסימלי הוא 31 ימים

ייצוא נתוני הודעות ל-BigQuery

הפעלת המאפיין הזה מאפשרת ליצור מינוי ל-BigQuery שכותב הודעות לטבלה קיימת ב-BigQuery כשהן מתקבלות. לא צריך להגדיר לקוח נפרד של מנויים. מידע נוסף על מינויים ל-BigQuery זמין במאמר מינויים ל-BigQuery.

גיבוי של נתוני הודעות ב-Cloud Storage

הפעלת המאפיין הזה מאפשרת ליצור מינוי ל-Cloud Storage שכותב הודעות לטבלה קיימת ב-Cloud Storage כשהן מתקבלות. לא צריך להגדיר לקוח נפרד של מנויים. מידע נוסף על מינויים ל-Cloud Storage זמין במאמר מינויים ל-Cloud Storage.

טרנספורמציות

נושאי SMT מאפשרים לבצע שינויים קלים בנתוני ההודעות ובמאפיינים שלהן ישירות ב-Pub/Sub. התכונה הזו מאפשרת טיוב נתונים, סינון או המרת פורמט לפני שההודעות מתפרסמות בנושא.

מידע נוסף על SMTs זמין בסקירה הכללית על SMTs.

Google-owned and Google-managed encryption key

מציין שהנושא מוצפן באמצעותGoogle-owned and Google-managed encryption keys. ההצפנה של הודעות ב-Pub/Sub מתבצעת באמצעות Google-owned and Google-managed encryption keys כברירת מחדל, ולכן בחירה באפשרות הזו שומרת על התנהגות ברירת המחדל. ‫Google מטפלת בניהול המפתחות וברוטציה שלהם באופן אוטומטי, כדי להבטיח שההודעות שלכם תמיד יהיו מוגנות באמצעות ההצפנה החזקה ביותר שזמינה. האפשרות הזו לא דורשת הגדרות נוספות. מידע נוסף על Google-owned and Google-managed encryption keysזמין במאמר ברירת המחדל להצפנה עם Google-owned and Google-managed encryption keys.

מפתח Cloud KMS

הגדרה שמציינת אם הנושא מוצפן באמצעות מפתח הצפנה בניהול הלקוח (CMEK). ההודעות ב-Pub/Sub מוצפנות באמצעות Google-owned and Google-managed encryption keys כברירת מחדל. אם מציינים את האפשרות הזו, Pub/Sub משתמש בתבנית הצפנת המעטפה עם CMEK. בגישה הזו, Cloud KMS לא מצפין את ההודעות. במקום זאת, Cloud KMS מצפין את המפתחות להצפנת נתונים (DEK) ש-Pub/Sub יוצר לכל נושא. מערכת Pub/Sub מצפינה את ההודעות באמצעות מפתח הצפנה (DEK) חדש שנוצר עבור הנושא. מערכת Pub/Sub מפענחת את ההודעות זמן קצר לפני שהן נמסרות למנויים. מידע נוסף על יצירת מפתח זמין במאמר הגדרת הצפנה של הודעות.

יצירת נושא

כדי לפרסם נושא או להירשם אליו, צריך ליצור אותו קודם.

המסוף

כדי ליצור נושא, פועלים לפי השלבים הבאים:

1. נכנסים לדף Create topic של Pub/Sub במסוף Google Cloud .

   כניסה לדף Create topic

2. בשדה Topic ID (מזהה הנושא), מזינים מזהה לנושא. מידע נוסף על מתן שמות לנושאים זמין בהנחיות למתן שמות.

3. כדי ליצור מינוי ברירת מחדל לנושא, בוחרים באפשרות הוספת מינוי ברירת מחדל. האפשרות הזו מופעלת כברירת מחדל.

4. זה שינוי אופציונלי. כדי להשתמש בסכימה עם הנושא, לוחצים על שימוש בסכימה ומזינים את הסכימה. מידע נוסף זמין במאמר בנושא יצירה ושיוך של סכימה כשיוצרים נושא.

5. לנושא רגיל, לא מסמנים את התיבה הפעלת ההעברה.

6. זה שינוי אופציונלי. כדי לשמור הודעות אחרי שהן מתפרסמות, בוחרים באפשרות הפעלת שמירת הודעות. בוחרים את תקופת השמירה בימים, בשעות ובדקות. מידע נוסף זמין במאמר בנושא הפעלת שמירת הודעות.

7. זה שינוי אופציונלי. כדי לייצא הודעות שפורסמו לטבלה ב-BigQuery, בוחרים באפשרות ייצוא נתונים ל-BigQuery ומזינים את פרטי הטבלה. מידע נוסף זמין במאמר בנושא יצירת מינויים ל-BigQuery.

8. זה שינוי אופציונלי. כדי לגבות הודעות שפורסמו לקטגוריה של Cloud Storage, בוחרים באפשרות גיבוי נתוני ההודעות ב-Cloud Storage ומזינים את הפרטים של הקטגוריה של Cloud Storage. מידע נוסף מופיע במאמר בנושא יצירת מינויים ל-Cloud Storage.

9. זה שינוי אופציונלי. בקטע Transforms, מוסיפים Single Message Transforms (SMTs) כדי לשנות ולסנן את נתוני ההודעות. מידע נוסף זמין במאמר יצירת נושא באמצעות SMT.

10. זה שינוי אופציונלי. כדי להשתמש במפתח הצפנה בניהול הלקוח (CMEK) להצפנת הודעות, בוחרים באפשרות Cloud KMS key. כברירת מחדל, Pub/Sub משתמש בהצפנה של Google, שלא דורשת CMEK. מידע נוסף זמין במאמר הגדרת הצפנה של הודעות.

11. זה שינוי אופציונלי. כדי לנהל את המפתחות שמשויכים לנושא, לוחצים על ניהול מפתחות. מידע נוסף מופיע במאמר סקירה כללית על תגים.

12. לוחצים על יצירת נושא.

gcloud

1. במסוף Google Cloud , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Google Cloud המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. כדי ליצור נושא, מריצים את הפקודה gcloud pubsub topics create:

   gcloud pubsub topics create TOPIC_ID
   

REST

כדי ליצור נושא, משתמשים בשיטה projects.topics.create:

הבקשה צריכה להיות מאומתת באמצעות אסימון גישה בכותרת Authorization. כדי לקבל אסימון גישה ל-Application Default Credentials הנוכחיים: ‫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 הוא מזהה הפרויקט.
• מספר הנושא שלך הוא TOPIC_ID.

תשובה:

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

C++‎

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C++‎ במאמר תחילת העבודה המהירה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה של Pub/Sub C++ API.

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#‎

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C# ‎ במאמר הפעלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub C# API.

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 ‏ (v2). אם אתם עדיין משתמשים בספרייה v1, כדאי לעיין במדריך להעברה לגרסה v2. כדי לראות רשימה של דוגמאות קוד מגרסה 1, אפשר לעיין ב דוגמאות הקוד שהוצאו משימוש.

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Go במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Go API.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

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

	topic := &pubsubpb.Topic{
		Name: fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
	}
	t, err := client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopic: %w", err)
	}
	fmt.Fprintf(w, "Topic created: %v\n", t)
	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Java API.

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר הפעלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Node.js API.

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר הפעלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Node.js API.

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של PHP במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub PHP API.

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במאמר תחילת העבודה המהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של ה-API בשפת Python של 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

בדוגמה הבאה נעשה שימוש בספריית הלקוח של Ruby Pub/Sub בגרסה 3. אם אתם עדיין משתמשים בספרייה v2, כדאי לעיין במדריך להעברה לגרסה v3. כדי לראות רשימה של דוגמאות קוד של Ruby v2, אפשר לעיין ב דוגמאות הקוד שהוצאו משימוש.

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Ruby במאמר תחילת העבודה המהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Ruby API.

# topic_id = "your-topic-id"

pubsub = Google::Cloud::PubSub.new
topic_admin = pubsub.topic_admin

topic = topic_admin.create_topic name: pubsub.topic_path(topic_id)

puts "Topic #{topic.name} created."

מגבלות שקשורות למדיניות הארגון

לדוגמה, מדיניות ארגונית יכולה להגביל את יצירת הנושאים, או להגביל את אחסון ההודעות באזור של Compute Engine. כדי להימנע משגיאות ביצירת נושאים, כדאי לבדוק ולעדכן את מדיניות הארגון לפי הצורך לפני שיוצרים נושא.

אם הפרויקט נוצר לאחרונה, צריך להמתין כמה דקות עד שמדיניות הארגון תאותחל לפני שיוצרים נושא.

מעבר אל מדיניות הארגון

מידע נוסף מופיע במאמר הגדרת מדיניות לאחסון הודעות.

המאמרים הבאים

• בוחרים את סוג המינוי לנושא.

• איך מפרסמים הודעה בנושא

• פתרון בעיות שקשורות לנושא.

• יוצרים או משנים נושא באמצעות ה-CLI של gcloud,‏ REST APIs או ספריות לקוח.

‫Apache Kafka®‎ הוא סימן מסחרי רשום של The Apache Software Foundation או של השותפים העצמאיים שלה בארצות הברית או במדינות אחרות.