יצירת מינויים מסוג pull

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

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

• מידע נוסף על מינויים
• בודקים אם העסק שלכם צריך מינוי שליפה.
• הסבר על מינויים לשליפת הודעות.

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

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

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

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

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

• ‫pubsub.subscriptions.create בפרויקט
• pubsub.topics.attachSubscription בנושא

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

מינויים חוצי-פרויקטים

אם יוצרים מינוי בפרויקט אחד לנושא בפרויקט אחר, צריכה להיות לכם הרשאת pubsub.subscriptions.create בפרויקט שבו אתם יוצרים את המינוי, והרשאת pubsub.topics.attachSubscription בנושא.

יצירת מינוי שליפה

המסוף

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

1. נכנסים לדף Subscriptions במסוף Google Cloud .

   אל הדף "מינויים"

2. לוחצים על יצירת מינוי.

3. כותבים שם בשדה Subscription ID.

   מידע על מתן שם למינוי זמין במאמר הנחיות למתן שם לנושא או למינוי.

4. ברשימה Pub/Sub topic, בוחרים נושא שהמינוי יקרא ממנו.

5. בקטע סוג העברה, בוחרים באפשרות משיכה.

6. אופציונלי: בקטע Transforms, מוסיפים Single Message Transforms (SMTs)‎ אחד או יותר. מידע נוסף זמין במאמר יצירת מינוי באמצעות SMT.

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

8. בוחרים אפשרות בהגדרה Retry policy (מדיניות ניסיון חוזר). מידע נוסף זמין במאמר בנושא מדיניות הניסיון החוזר לחיוב מינוי.

9. אופציונלי: מפעילים נושא להודעות ללא מוצא כדי לקבל הודעות שלא ניתן למסור.

   1. מסמנים את תיבת הסימון Dead lettering (הודעות שלא ניתן למסור).

   2. ברשימה Dead letter topic, בוחרים את נושא ה-dead-letter או יוצרים אותו.

   3. בשדה מספר ניסיונות המסירה המקסימלי, מזינים את המספר המקסימלי של ניסיונות המסירה.

10. אופציונלי: בקטע מאפייני משלוח, מפעילים או משביתים את אפשרויות המשלוח הבאות:

    • מסירה בדיוק פעם אחת

    • סדר ההודעות

11. אופציונלי: בקטע Acknowledgement deadline (מועד אחרון לאישור), מגדירים את המועד האחרון לעיבוד ולאישור ההודעות על ידי המנוי. מידע נוסף זמין במאמר הארכת זמן האישור באמצעות ניהול חכירה.

12. אופציונלי: בקטע Lifetime options (אפשרויות לכל החיים), מגדירים כמה זמן המינוי ישמור את ההודעות.

    1. בקטע משך השמירה של ההודעות, מציינים לכמה זמן יישמרו הודעות שלא אושרו.

    2. כדי לשמור הודעות שאושרה קבלתן וגם הודעות שלא אושרה קבלתן, מסמנים את תיבת הסימון שמירת הודעות שאושרה קבלתן.

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

13. אופציונלי: בשדה תקופת התפוגה, בוחרים אפשרות:

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

    2. כדי להשבית את תפוגת המינוי, מסמנים את התיבה Never expire (לעולם לא יפוג).

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

14. לוחצים על יצירה.

אפשר גם ליצור מינוי מהקטע נושאים. מקש הקיצור הזה שימושי לקישור נושאים למינויים.

1. נכנסים לדף Topics במסוף Google Cloud .

   לדף Topics

2. לוחצים על לצד הנושא שרוצים ליצור לו מינוי.

3. בתפריט ההקשר, בוחרים באפשרות יצירת מינוי.

4. בדף הוספת מינוי לנושא, משלימים את השלבים שמתוארים בהליך הקודם. מזהה הנושא מתמלא אוטומטית.

gcloud

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

   הפעלת Cloud Shell

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

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

   gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫SUBSCRIPTION_ID: השם או המזהה של מינוי המשיכה החדש.
   • ‫TOPIC_ID: השם או המזהה של הנושא.

REST

כדי ליצור מינוי מסוג pull, משתמשים בשיטה projects.subscriptions.create:

בקשה:

הבקשה צריכה להיות מאומתת באמצעות אסימון גישה בכותרת Authorization. כדי לקבל טוקן גישה ל-Application Default Credentials הנוכחי: 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"
}

כאשר:

• ‫PROJECT_ID הוא מזהה הפרויקט.
• ‫SUBSCRIPTION_ID הוא מזהה המינוי שלך.
• מספר הנושא שלך הוא TOPIC_ID.

תשובה:

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}

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& topic_id,
   std::string const& subscription_id) {
  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());
  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#‎

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

using Google.Cloud.PubSub.V1;
using Grpc.Core;

public class CreateSubscriptionSample
{
    public Subscription CreateSubscription(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);

        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

המשך

בדוגמה הבאה נעשה שימוש בגרסה הראשית של ספריית הלקוח 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"
)

func create(w io.Writer, projectID, topic, subscription string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	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.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	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 com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePullSubscriptionExample {
  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";

    createPullSubscriptionExample(projectId, subscriptionId, topicId);
  }

  public static void createPullSubscriptionExample(
      String projectId, String subscriptionId, String topicId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      // Create a pull 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.getDefaultInstance(), 10);
      System.out.println("Created pull subscription: " + subscription.getName());
    }
  }
}

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 createSubscription(topicNameOrId, subscriptionNameOrId) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

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} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

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

use Google\Cloud\PubSub\PubSubClient;

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

    printf('Subscription created: %s' . PHP_EOL, $subscription->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"
# subscription_id = "your-subscription-id"

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)

# 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}
    )

print(f"Subscription created: {subscription}")

Ruby

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

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

# topic_id        = "your-topic-id"
# subscription_id = "your-subscription-id"

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

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id)

puts "Pull subscription #{subscription_id} created."

מעקב אחר מינויים מסוג pull

ב-Cloud Monitoring יש מספר מדדים למעקב אחרי מינויים.

רשימה של כל המדדים שקשורים ל-Pub/Sub והתיאורים שלהם מופיעה במסמכי התיעוד בנושא מעקב אחרי Pub/Sub.

אפשר גם לעקוב אחרי מינויים מתוך Pub/Sub.

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

• קבלת הודעות ממינוי שליפה.
• ליצור או לשנות מינוי באמצעות פקודות של gcloud.
• יצירה או שינוי של מינוי באמצעות ממשקי API ל-REST.