יצירת נושא

ב-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
• סוג המסירה 'משיכה'
• משך השמירה של ההודעות הוא שבעה ימים
• תפוגה אחרי 31 ימים ללא פעילות
• מועד האחרון לאישור הוא 10 שניות
• מדיניות ניסיון חוזר מיידי

שימוש בסכימה

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

הפעלת ההטמעה

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

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

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

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

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

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

הפעלת שמירת הודעות בנושא

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

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

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

כדי לראות מדדים לגבי הודעות שנשמרו, משתמשים במדדים הבאים של Cloud Monitoring:

• ‫topic/num_retained_messages: מספר ההודעות שנשמרו
• ‫topic/oldest_retained_message_age: הגיל של ההודעה הכי ישנה שנשמרה
• ‫topic/retained_bytes: הגודל הכולל של ההודעות שנשמרו, בבייטים

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

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

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

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

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

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

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

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

כדי ליצור נושא, משתמשים ב-method‏ 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."

חלודה

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

use google_cloud_pubsub::client::TopicAdmin;

pub async fn sample(client: &TopicAdmin, project_id: &str, topic_id: &str) -> anyhow::Result<()> {
    let topic = client
        .create_topic()
        .set_name(format!("projects/{project_id}/topics/{topic_id}"))
        .send()
        .await?;

    println!("successfully created topic {topic:?}");
    Ok(())
}

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

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

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

מעבר אל Organization Policies

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

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

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

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

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

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

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