Membuat langganan push

Dokumen ini menjelaskan cara membuat langganan push. Anda dapat menggunakan Google Cloud konsol, Google Cloud CLI, library klien, atau Pub/Sub API untuk membuat langganan push.

Sebelum memulai

• Pelajari langganan.
• Pahami cara kerja langganan push.

Peran dan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat langganan push, minta administrator untuk memberi Anda peran IAM Pub/Sub Editor (roles/pubsub.editor) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat langganan push. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat langganan push:

• pubsub.subscriptions.create di project
• pubsub.topics.attachSubscription di topik

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Langganan lintas project

Jika Anda membuat langganan di satu project untuk topik di project lain, Anda harus memiliki izin pubsub.subscriptions.create di project tempat Anda membuat langganan, dan izin pubsub.topics.attachSubscription di topik.

Properti langganan push

Langganan push mendukung semua properti langganan umum. Bagian berikut menjelaskan properti yang khusus untuk langganan push.

Endpoint

URL endpoint (wajib). Alamat HTTPS yang dapat diakses secara publik. Server untuk endpoint push harus memiliki sertifikat SSL yang valid dan ditandatangani oleh certificate authority. Layanan Pub/Sub mengirimkan pesan ke endpoint push dari region yang sama Google Cloud dengan tempat layanan Pub/Sub menyimpan pesan. Layanan Pub/Sub mengirimkan pesan dari region yang sama Google Cloud sesuai upaya terbaik.

• Jika pelanggan menggunakan firewall, mereka tidak dapat menerima permintaan push. Untuk menerima permintaan push, Anda harus menonaktifkan firewall dan memverifikasi Token Web JSON (JWT) yang digunakan dalam permintaan. Jika pelanggan memiliki firewall, Anda mungkin menerima error 403 permission denied.

• Pub/Sub tidak memerlukan bukti kepemilikan untuk domain URL langganan push. Jika domain Anda menerima permintaan POST yang tidak terduga dari Pub/Sub, Anda dapat melaporkan dugaan penyalahgunaan.

Autentikasi

Aktifkan autentikasi. Jika diaktifkan, pesan yang dikirim oleh Pub/Sub ke endpoint push akan menyertakan header otorisasi untuk memungkinkan endpoint mengautentikasi permintaan. Mekanisme autentikasi dan otorisasi otomatis tersedia untuk endpoint fungsi App Engine Standard dan Cloud Run yang dihosting di project yang sama dengan langganan.

Konfigurasi autentikasi untuk langganan push yang diautentikasi terdiri dari akun layanan yang dikelola pengguna, dan parameter audiens yang ditentukan dalam panggilan create, patch, atau ModifyPushConfig. Anda juga harus memberikan peran tertentu ke akun layanan, seperti yang dibahas di bagian berikutnya.

• Audiens. String tunggal yang tidak peka huruf besar/kecil yang digunakan webhook untuk memvalidasi audiens yang dituju dari token tertentu ini.

• Akun layanan. Pub/Sub otomatis membuat akun layanan untuk Anda dengan format service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Prasyarat untuk mengaktifkan autentikasi

Akun layanan yang dikelola pengguna adalah akun layanan yang terkait dengan langganan push. Akun ini digunakan sebagai klaim email dari Token Web JSON (JWT) yang dibuat. Berikut adalah daftar persyaratan untuk akun layanan:

• Akun layanan yang dikelola pengguna ini harus berada dalam project yang sama dengan langganan push.

• Principal yang membuat atau mengubah langganan push harus memiliki izin iam.serviceAccounts.actAs di akun layanan yang dikelola pengguna agar dapat melampirkan akun layanan ke langganan push. Untuk mengetahui informasi selengkapnya, lihat Melampirkan akun layanan ke resource.

• Izin yang diperlukan: Akun layanan ini harus diberi izin iam.serviceAccounts.getOpenIdToken (termasuk dalam roles/iam.serviceAccountTokenCreator) untuk memungkinkan Pub/Sub membuat token JWT bagi akun layanan yang ditentukan untuk mengautentikasi permintaan push.

Pembukaan payload

Opsi Enable payload unwrapping menghapus semua metadata pesan dari pesan Pub/Sub, kecuali data pesan. Dengan pembukaan payload, data pesan dikirim langsung sebagai isi HTTP.

Anda juga dapat Mengaktifkan opsi Write metadata. Opsi Write metadata menambahkan metadata pesan yang sebelumnya dihapus kembali ke header permintaan.

Mengirim ke alamat VPC pribadi

Pub/Sub beroperasi di luar jaringan VPC dan tidak dapat langsung mengirim pesan ke alamat VPC pribadi. Namun, Anda dapat menggunakan Eventarc untuk merutekan pesan ke layanan dalam VPC. Pub/Sub dapat mengirim pesan ke pemicu Eventarc, yang kemudian dapat meneruskannya ke layanan dalam VPC, seperti layanan Cloud Run atau eksekusi Workflows. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Eventarc.

Kontrol Layanan VPC

Untuk project yang dilindungi oleh Kontrol Layanan VPC, perhatikan batasan berikut untuk langganan push:

• Anda hanya dapat membuat langganan push baru yang endpoint push-nya ditetapkan ke layanan Cloud Run dengan URL run.app default atau eksekusi Workflows. Domain kustom tidak berfungsi.

• Saat merutekan peristiwa melalui Eventarc ke tujuan Workflows yang endpoint push-nya ditetapkan ke eksekusi Workflows, Anda hanya dapat membuat langganan push baru melalui Eventarc.

• Anda tidak dapat memperbarui langganan push yang ada. Langganan push ini akan terus berfungsi, meskipun tidak dilindungi oleh Kontrol Layanan VPC.

Membuat langganan push

Contoh berikut menunjukkan cara membuat langganan dengan pengiriman push, menggunakan setelan default yang disediakan.

Secara default, langganan menggunakan pengiriman pull, kecuali jika Anda menetapkan konfigurasi push secara eksplisit, seperti yang ditunjukkan dalam contoh berikut.

Konsol

Untuk membuat langganan push, selesaikan langkah-langkah berikut:

1. Di Google Cloud konsol, buka halaman Subscriptions.

   Buka Langganan

2. Klik Create subscription.
3. Untuk kolom Subscription ID, masukkan nama.

   Untuk mengetahui informasi tentang cara memberi nama langganan, lihat Panduan memberi nama topik atau langganan.

4. Pilih atau buat topik dari menu drop-down. Langganan akan menerima pesan dari topik.
5. Pilih Delivery type sebagai Push.
6. Tentukan URL endpoint.
7. Pertahankan semua nilai default lainnya.
8. Klik Create.

Anda juga dapat membuat langganan dari bagian Topics. Pintasan ini berguna untuk mengaitkan topik dengan langganan.

1. Di Google Cloud konsol, buka halaman Topics.

   Buka Topik

2. Klik di samping topik yang akan dibuat langganannya.
3. Dari menu konteks, pilih Create subscription.
4. Masukkan Subscription ID.

   Untuk mengetahui informasi tentang cara memberi nama langganan, lihat Panduan memberi nama topik atau langganan.

5. Pilih Delivery type sebagai Push.
6. Tentukan URL endpoint.
7. Pertahankan semua nilai default lainnya.
8. Klik Create.

gcloud

1. Di Google Cloud konsol, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. Untuk membuat langganan push, jalankan perintah gcloud pubsub subscriptions create.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
   --topic=TOPIC_ID \
   --push-endpoint=PUSH_ENDPOINT

   Ganti kode berikut:

   • SUBSCRIPTION_ID: Nama atau ID langganan push baru Anda.
   • TOPIC_ID: Nama atau ID topik Anda.
   • PUSH_ENDPOINT: URL yang akan digunakan sebagai endpoint untuk langganan ini. Contohnya, https://myproject.appspot.com/myhandler.

REST

Untuk membuat langganan push, gunakan projects.subscriptions.create metode:

Permintaan:

Permintaan tersebut harus diautentikasi dengan token akses di header Authorization. Untuk mendapatkan token akses untuk Kredensial Default Aplikasi saat ini: gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

Isi permintaan:

{
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
// Only needed if you are using push delivery
"pushConfig": {
"pushEndpoint": "PUSH_ENDPOINT"
}
}

Dengan:

PROJECT_ID adalah project ID Anda.

SUBSCRIPTION_ID adalah ID langganan Anda.

TOPIC_ID adalah topic ID Anda.

PUSH_ENDPOINT adalah URL yang akan digunakan sebagai endpoint. Contohnya, https://myproject.appspot.com/myhandler.

Respons:

{
"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++

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Pub/Sub C++.

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#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Pub/Sub C#.

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

Contoh berikut menggunakan library klien Pub/Sub Go versi utama (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Pub/Sub Go.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Pub/Sub Node.js.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Pub/Sub Node.js.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub PHP API.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi 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

Contoh berikut menggunakan library klien Pub/Sub Ruby v3. Jika Anda masih menggunakan library v2, lihat panduan migrasi ke v3. Untuk melihat daftar contoh kode Ruby v2, lihat contoh kode yang tidak digunakan lagi.

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi 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."

Memantau langganan push

Cloud Monitoring menyediakan sejumlah metrik untuk memantau langganan.

Untuk mengetahui daftar semua metrik yang tersedia terkait Pub/Sub dan deskripsinya, lihat dokumentasi Monitoring untuk Pub/Sub.

Anda juga dapat memantau langganan dari dalam Pub/Sub.

Langkah berikutnya

• Membuat atau mengubah langganan dengan gcloud perintah.
• Membuat atau mengubah langganan dengan REST API.