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.
• Pahami cara kerja langganan push.

Peran dan izin yang diperlukan

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

Untuk mendapatkan izin yang diperlukan untuk 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.

Peran yang telah ditetapkan 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:

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

Anda mung juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaanlainnya.

Jika Anda perlu membuat langganan push dalam satu project yang terkait dengan topik di project lain, minta administrator topik Anda untuk memberi Anda juga peran IAM (roles/pubsub.editor) Pub/Sub Editor 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 valid yang 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 atas dasar 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.

Authentication

Aktifkan autentikasi. Jika diaktifkan, pesan yang dikirim oleh Pub/Sub ke endpoint push akan menyertakan header otorisasi agar endpoint dapat mengautentikasi permintaan. Mekanisme autentikasi dan otorisasi otomatis tersedia untuk endpoint App Engine Standar dan Cloud Functions 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 spesifik kepada akun layanan khusus yang dikelola Google - 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 JSON Web Token (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 agar pemanggil dapat meniru identitas beberapa akun layanan atau memberikan peran dengan izin ini di akun layanan agar pemanggil hanya meniru identitas akun layanan ini.

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

• Akun layanan yang dikelola Google (wajib).

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

  • Akun layanan ini harus diberi izin iam.serviceAccounts.getOpenIdToken (termasuk dalam peran roles/iam.serviceAccountTokenCreator) agar Pub/Sub dapat membuat token JWT untuk permintaan push yang diautentikasi.

Pembukaan payload

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

• Menulis metadata. Menambahkan kembali metadata pesan yang telah dihapus sebelumnya 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 mengarahkan peristiwa melalui Eventarc ke tujuan Workflows yang endpoint push-nya ditetapkan ke eksekusi Workflow, Anda hanya dapat membuat langganan push baru melalui Eventarc.

• Anda tidak dapat memperbarui langganan push yang sudah 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 ID Langganan, 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 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 Topics. Pintasan ini berguna untuk mengaitkan topik dengan langganan.

1. Di konsol Google Cloud, buka halaman Topics.

   Buka Topik

2. Klik di samping topik tempat langganan dibuat.
3. Dari menu konteks, pilih Buat langganan.
4. Masukkan ID Langganan.

   Untuk mengetahui 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 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 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 informasi selengkapnya, lihat dokumentasi referensi API C# Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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 informasi selengkapnya, lihat dokumentasi referensi API Go Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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 informasi selengkapnya, lihat dokumentasi referensi API Java Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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 informasi selengkapnya, lihat dokumentasi referensi API PHP Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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 informasi selengkapnya, lihat dokumentasi referensi API Python Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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 informasi selengkapnya, lihat dokumentasi referensi API Ruby Pub/Sub.

Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui 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."

Langkah selanjutnya

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