יצירת מינויים מסוג 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 בנושא.

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

המסוף

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

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

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

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

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

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

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

5. בקטע Delivery type, בוחרים באפשרות Pull.

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

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

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

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

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

   2. ברשימה Dead letter topic, בוחרים או יוצרים את הנושא להודעות ללא מוצא.

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

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

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

    • סדר ההודעות

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

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

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

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

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

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

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

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

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

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

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

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

   מעבר אל "נושאים"

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

3. בתפריט ההקשר, לוחצים על Create subscription.

4. בדף Add subscription to topic, מבצעים את השלבים שמתוארים בתהליך הקודם. מזהה הנושא מתמלא באופן אוטומטי.

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

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

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

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."

Rust

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

use google_cloud_pubsub::client::SubscriptionAdmin;

pub async fn sample(
    client: &SubscriptionAdmin,
    project_id: &str,
    topic_id: &str,
    subscription_id: &str,
) -> anyhow::Result<()> {
    let subscription_name = format!("projects/{project_id}/subscriptions/{subscription_id}");
    let topic_name = format!("projects/{project_id}/topics/{topic_id}");

    let subscription = client
        .create_subscription()
        .set_name(subscription_name)
        .set_topic(topic_name)
        .send()
        .await?;

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

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

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

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

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

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

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