Membuat langganan push

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

Sebelum memulai

• Pelajari langganan.
• Memahami cara kerja langganan push.

Peran dan izin yang diperlukan

Untuk membuat langganan, Anda harus mengonfigurasi kontrol akses di tingkat project. Anda juga memerlukan izin tingkat resource jika langganan dan topik berada di project yang berbeda, seperti yang akan dibahas nanti di bagian ini.

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

Peran yang telah ditentukan ini berisi izin yang diperlukan untuk membuat langganan push. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat langganan push:

• Buat langganan: pubsub.subscriptions.create
• Menghapus langganan: pubsub.subscriptions.delete
• Mendapatkan langganan: pubsub.subscriptions.get
• Mencantumkan langganan: pubsub.subscriptions.list
• Memperbarui langganan: pubsub.subscriptions.update
• Lampirkan langganan ke topik: pubsub.topics.attachSubscription
• Dapatkan kebijakan IAM untuk langganan: pubsub.subscriptions.getIamPolicy
• Konfigurasikan kebijakan IAM untuk langganan: pubsub.subscriptions.setIamPolicy

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

Jika Anda perlu membuat langganan push di satu project yang terkait dengan topik di project lain, minta administrator topik untuk juga memberi Anda peran IAM (roles/pubsub.editor) Editor Pub/Sub pada topik tersebut.

Properti langganan push

Saat mengonfigurasi langganan push, Anda dapat menentukan properti berikut.

Properti umum

Pelajari properti langganan umum yang dapat Anda tetapkan di semua langganan.

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 Google Cloud yang sama dengan tempat layanan Pub/Sub menyimpan pesan. Layanan Pub/Sub mengirimkan pesan dari region Google Cloud yang sama berdasarkan upaya terbaik.

Pub/Sub tidak lagi 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 kepada agen layanan, seperti yang dibahas di bagian berikutnya.

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

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

  • Akun utama yang membuat atau mengubah langganan push harus memiliki izin iam.serviceAccounts.actAs di akun layanan. Anda dapat memberikan peran dengan izin ini di project, folder, atau organisasi untuk mengizinkan pemanggil meniru identitas beberapa akun layanan atau memberikan peran dengan izin ini di akun layanan untuk mengizinkan pemanggil hanya meniru identitas akun layanan ini.

• Audiens. Satu string yang tidak peka huruf besar/kecil yang digunakan webhook untuk memvalidasi audiens yang dimaksud dari token tertentu ini.

• Agen layanan (wajib).

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

  • Agen layanan ini harus diberi izin iam.serviceAccounts.getOpenIdToken (disertakan dalam peran roles/iam.serviceAccountTokenCreator) untuk mengizinkan Pub/Sub membuat token JWT untuk permintaan push yang diautentikasi.

Pembukaan payload

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

• Menulis metadata. Menambahkan metadata pesan yang sebelumnya dihapus kembali ke header permintaan.

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 Alur Kerja. 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 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 konsol Google Cloud, buka halaman Langganan.

   Buka Langganan

2. Klik Buat langganan.
3. Untuk kolom Subscription ID, masukkan nama.

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

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

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

1. Di konsol Google Cloud, buka halaman Topics.

   Buka Topik

2. Klikdi samping topik yang akan digunakan untuk membuat langganan.
3. Dari menu konteks, pilih Buat langganan.
4. Masukkan ID Langganan.

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

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

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah 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 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. Contoh, https://myproject.appspot.com/myhandler.

REST

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

Permintaan:

Permintaan 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 keterangan:

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. Contoh, 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 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#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API C# Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Go Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

func createWithEndpoint(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// 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.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:       topic,
		AckDeadline: 10 * time.Second,
		PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %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 Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Java Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

/**
 * 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.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 Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API PHP Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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 Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Python Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Ruby Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

pubsub = Google::Cloud::Pubsub.new

topic        = pubsub.topic topic_id
subscription = topic.subscribe subscription_id,
                               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 pemantauan untuk Pub/Sub.

Anda juga dapat memantau langganan dari dalam Pub/Sub.

Langkah selanjutnya

• Buat atau ubah langganan dengan perintah gcloud.
• Buat atau ubah langganan dengan REST API.