יצירת מינויים לקבלת עדכונים

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

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

• מידע נוסף על מינויים
• הסבר על מינויים לשליחת הודעות.

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

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

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

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

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

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

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

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

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

מאפיינים של מינויי דחיפה

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

נקודות קצה

כתובת URL של נקודת קצה (חובה). כתובת HTTPS שנגישה לכולם. לשרת של נקודת הקצה של הודעת הפוש צריך להיות אישור SSL תקף שנחתם על ידי רשות אישורים. שירות Pub/Sub מעביר הודעות לנקודות קצה של Push מאותו אזור שבו שירות Pub/Sub מאחסן את ההודעות. Google Cloud שירות Pub/Sub מעביר הודעות מאותו אזור כמיטב היכולת. Google Cloud

• אם המנויים משתמשים בחומת אש, הם לא יכולים לקבל בקשות לשליחת הודעות פוש. כדי לקבל בקשות לשליחת הודעות פוש, צריך להשבית את חומת האש ולאמת את אסימון האינטרנט מבוסס ה-JSON‏ (JWT) שמשמש בבקשה. אם למנוי יש חומת אש, יכול להיות שתקבלו שגיאה 403 permission denied.

• ב-Pub/Sub לא נדרש אישור בעלות על דומיינים של כתובות URL של מינויים מסוג Push. אם הדומיין שלכם מקבל בקשות POST לא צפויות מ-Pub/Sub, אתם יכולים לדווח על חשד לניצול לרעה.

אימות

מפעילים אימות. כשההגדרה הזו מופעלת, ההודעות שמועברות מ-Pub/Sub לנקודת הקצה של הדחיפה כוללות כותרת הרשאה כדי לאפשר לנקודת הקצה לאמת את הבקשה. מנגנוני אימות והרשאה אוטומטיים זמינים לנקודות קצה של פונקציות Cloud Run ו-App Engine Standard שמתארחות באותו פרויקט כמו המינוי.

הגדרת האימות של מינוי push מאומת כוללת חשבון שירות שמנוהל על ידי משתמש, ופרמטרים של קהל שצוינו בקריאה create,‏ patch או ModifyPushConfig. צריך גם להקצות תפקיד ספציפי לחשבון שירות, כמו שמוסבר בקטע הבא.

• קהל. מחרוזת יחידה שלא תלויה באותיות רישיות או קטנות, שמשמשת את ה-webhook לאימות קהל היעד של הטוקן הספציפי הזה.

• חשבון שירות.מערכת Pub/Sub יוצרת בשבילכם באופן אוטומטי חשבון שירות בפורמט service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

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

חשבון השירות בניהול המשתמש הוא חשבון השירות שמשויך למינוי ה-push. החשבון הזה משמש כהצהרת email של אסימון ה-JWT‏ (JSON Web Token) שנוצר. בהמשך מפורטות הדרישות מחשבון השירות:

• חשבון השירות בניהול המשתמשים צריך להיות באותו פרויקט כמו מינוי ה-Push.

• למשתמש שיוצר או משנה את מינוי הדחיפה צריכה להיות ההרשאה iam.serviceAccounts.actAs בחשבון השירות שמנוהל על ידי המשתמש כדי לצרף את חשבון השירות למינוי הדחיפה. מידע נוסף מופיע במאמר צירוף חשבונות שירות למשאבים.

• הרשאות נדרשות: צריך להעניק לחשבון השירות הזה את ההרשאה iam.serviceAccounts.getOpenIdToken (שכלולה בתפקיד roles/iam.serviceAccountTokenCreator) כדי לאפשר ל-Pub/Sub ליצור אסימוני JWT בשביל חשבון השירות שצוין, לצורך אימות של בקשות push.

הסרת העטיפה של המטען הייעודי (payload)

האפשרות Enable payload unwrapping (הפעלת פריקת מטען ייעודי) מסירה מהודעות Pub/Sub את כל המטא-נתונים של ההודעות, חוץ מנתוני ההודעות. במקרה של ביטול העטיפה של מטען ייעודי (payload), נתוני ההודעה מועברים ישירות כגוף ה-HTTP.

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

משלוח לכתובות VPC פרטיות

‫Pub/Sub פועל מחוץ לרשתות VPC ולא יכול לדחוף הודעות ישירות לכתובות VPC פרטיות. עם זאת, אפשר להשתמש ב-Eventarc כדי לנתב הודעות לשירותים ב-VPC. שירות Pub/Sub יכול לשלוח הודעות לטריגר של Eventarc, שיכול להעביר אותן לשירות ב-VPC, כמו שירות Cloud Run או הפעלה של Workflows. מידע נוסף זמין במסמכי התיעוד של Eventarc.

VPC Service Controls

בפרויקט שמוגן על ידי VPC Service Controls, שימו לב למגבלות הבאות לגבי מינויים מסוג Push:

• אפשר ליצור רק מינויים חדשים לשליחת הודעות פוש שבהם נקודת הקצה של הפוש מוגדרת לשירות Cloud Run עם כתובת URL של run.app כברירת מחדל או להפעלה של Workflows. דומיינים מותאמים אישית לא פועלים.

• כשמנתבים אירועים דרך Eventarc ליעדים של Workflows שבהם נקודת הקצה של הדחיפה מוגדרת להפעלה של Workflows, אפשר ליצור מינויים חדשים לדחיפה רק דרך Eventarc.

• אי אפשר לעדכן מינויים קיימים לקבלת עדכונים. מינויים לשליחת הודעות פוש ממשיכים לפעול, אבל הם לא מוגנים על ידי VPC Service Controls.

יצירת מינוי דחיפה

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

כברירת מחדל, המינויים משתמשים בשליפת נתונים, אלא אם מגדירים במפורש שליחת נתונים, כמו בדוגמאות הבאות.

המסוף

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

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

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

2. לוחצים על יצירת מינוי.
3. בשדה Subscription ID (מזהה מינוי), מזינים שם.

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

4. בוחרים נושא מהתפריט הנפתח או יוצרים נושא חדש. המינוי מקבל הודעות מהנושא.
5. בוחרים באפשרות Push בתור סוג ההעברה.
6. מציינים כתובת URL של נקודת קצה.
7. משאירים את כל שאר ערכי ברירת המחדל.
8. לוחצים על יצירה.

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

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

   לדף Topics

2. לוחצים עללצד הנושא שרוצים להירשם אליו.
3. בתפריט ההקשר, בוחרים באפשרות יצירת מינוי.
4. מזינים את מזהה המינוי.

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

5. בוחרים באפשרות Push בתור סוג ההעברה.
6. מציינים כתובת URL של נקודת קצה.
7. משאירים את כל שאר ערכי ברירת המחדל.
8. לוחצים על יצירה.

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 \
   --push-endpoint=PUSH_ENDPOINT

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

   • ‫SUBSCRIPTION_ID: השם או המזהה של מינוי הפוש החדש.
   • ‫TOPIC_ID: השם או המזהה של הנושא.
   • ‫PUSH_ENDPOINT: כתובת ה-URL שתשמש כנקודת הקצה של המינוי הזה. לדוגמה, https://myproject.appspot.com/myhandler.

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",
// Only needed if you are using push delivery
"pushConfig": {
"pushEndpoint": "PUSH_ENDPOINT"
}
}

כאשר:

‫PROJECT_ID הוא מזהה הפרויקט.

‫SUBSCRIPTION_ID הוא מזהה המינוי שלך.

מספר הנושא שלך הוא TOPIC_ID.

‫PUSH_ENDPOINT היא כתובת URL לשימוש כנקודת הקצה. לדוגמה, https://myproject.appspot.com/myhandler.

תשובה:

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {
"pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler",
"attributes": {
  "x-goog-version": "v1"
}
},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}

C++‎

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

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& endpoint) {
  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());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  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;

public class CreatePushSubscriptionSample
{
    public Subscription CreatePushSubscription(string projectId, string topicId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        // The approximate amount of time in seconds (on a best-effort basis) Pub/Sub waits for the
        // subscriber to acknowledge receipt before resending the message.
        var ackDeadlineSeconds = 60;
        var subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig, ackDeadlineSeconds);
        return subscription;
    }
}

המשך

בדוגמה הבאה נעשה שימוש בגרסה הראשית של ספריית הלקוח 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 createWithEndpoint(w io.Writer, projectID, topic, subscription, endpoint string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	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,
		AckDeadlineSeconds: 10,
		PushConfig:         &pubsubpb.PushConfig{PushEndpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("failed to create push sub: %w", err)
	}
	fmt.Fprintf(w, "Created push 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 CreatePushSubscriptionExample {
  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";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push 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, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// 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 createPushSubscription(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId,
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

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

async function createPushSubscription(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

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

use Google\Cloud\PubSub\PubSubClient;

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

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

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

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# endpoint = "https://my-test-project.appspot.com/push"

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)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

# 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,
            "push_config": push_config,
        }
    )

print(f"Push subscription created: {subscription}.")
print(f"Endpoint for subscription is: {endpoint}")

Ruby

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

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

# topic_id          = "your-topic-id"
# subscription_id   = "your-subscription-id"
# endpoint          = "https://your-test-project.appspot.com/push"

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),
  push_config: {
    push_endpoint: endpoint
  }

puts "Push subscription #{subscription_id} created."

מעקב אחר הרשמות ל-Push

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

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

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

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

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