push サブスクリプションを作成する

このドキュメントでは、push サブスクリプションの作成方法について説明します。push サブスクリプションを作成するには、Google Cloud コンソール、Google Cloud CLI、クライアントライブラリ、または Pub/Sub API を使用できます。

準備

サブスクリプションについて確認する。
push サブスクリプションの仕組みを理解する。

必要なロールと権限

サブスクリプションを作成するには、プロジェクトレベルでアクセス制御を構成する必要があります。このセクションで後述するように、サブスクリプションとトピックが異なるプロジェクトにある場合は、リソースレベルの権限も必要です。

push サブスクリプションの作成に必要な権限を取得するには、管理者にプロジェクトに対する Pub/Sub 編集者（roles/pubsub.editor）IAM ロールを付与するよう依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。

この事前定義ロールには、push サブスクリプションの作成に必要な権限が含まれています。必要な権限を正確に確認するには、[必要な権限] セクションを開いてください。

必要な権限

push サブスクリプションを作成するには、次の権限が必要です。

サブスクリプションを作成する: pubsub.subscriptions.create
サブスクリプションを削除する: pubsub.subscriptions.delete
サブスクリプションを取得する: pubsub.subscriptions.get
サブスクリプションを一覧表示する: pubsub.subscriptions.list
サブスクリプションを更新する: pubsub.subscriptions.update
サブスクリプションをトピックに接続する: pubsub.topics.attachSubscription
サブスクリプションの IAM ポリシーを取得する: pubsub.subscriptions.getIamPolicy
サブスクリプションの IAM ポリシーを構成する: pubsub.subscriptions.setIamPolicy

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

別のプロジェクトのトピックに関連付けられているプロジェクトで push サブスクリプションを作成する必要がある場合は、トピック管理者にトピックに対する Pub/Sub 編集者の (roles/pubsub.editor) IAM ロールも付与するよう依頼してください。

push サブスクリプションプロパティ

push サブスクリプションを構成するときに、次のプロパティを指定できます。

共通の特徴

すべてのサブスクリプションで設定できる共通のサブスクリプションプロパティについて学習する。

エンドポイント

エンドポイント URL（必須）。 一般公開されている HTTPS アドレス。push エンドポイントのサーバーには、認証局が署名した有効な SSL 証明書が必要です。Pub/Sub サービスでは、Pub/Sub サービスがメッセージを格納するのと同じ Google Cloud リージョンから push エンドポイントにメッセージを配信します。Pub/Sub サービスでは、同じ Google Cloud リージョンからベストエフォート方式でメッセージを配信します。

Pub/Sub では、push サブスクリプションの URL ドメインの所有権の証明が不要になりました。ドメインが Pub/Sub からの予期しない POST リクエストを受信した場合は、不正行為を報告できます。

Authentication

認証を有効にする。有効にすると、Pub/Sub によって push エンドポイントに配信されるメッセージに、エンドポイントがリクエストを認証するための承認ヘッダーが含まれます。サブスクリプションと同じプロジェクトでホストされる App Engine Standard エンドポイントと Cloud Functions エンドポイントでは、自動認証と自動承認のメカニズムを使用できます。

認証済み push サブスクリプションの認証構成は、ユーザーが管理するサービスアカウントと、create、patch または ModifyPushConfig 呼び出しで指定されるオーディエンスパラメータで構成されます。また、次のセクションで説明するように、特別な Google が管理するサービスアカウントに特定のロールを付与する必要もあります。

ユーザーが管理するサービスアカウント（必須）。push サブスクリプションに関連付けられているサービスアカウント。このアカウントは、生成された JSON Web Token（JWT）の email クレームとして使用されます。サービスアカウントの要件は次のとおりです。
- このサービスアカウントは、push サブスクリプションと同じプロジェクトに存在する必要があります。
- push サブスクリプションを作成または変更するプリンシパルには、サービスアカウントに対する iam.serviceAccounts.actAs 権限が必要です。プロジェクト、フォルダ、または組織に対してこの権限を付与することで、呼び出し元が複数のサービスアカウントの権限を借用することを許可するか、サービスアカウントでこの権限を持つロールを付与して、呼び出し元がこのサービスアカウントのみの権限を借用するできるようにすることができます。
オーディエンス。Webhook が特定のトークンの対象オーディエンスの検証に使用する、大文字と小文字が区別されない単一の文字列。
Google が管理するサービスアカウント（必須）。
- Pub/Sub により、service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com 形式のサービスアカウントが自動的に作成されます。
- このサービスアカウントに、Pub/Sub が認証された push リクエスト用の JWT トークンを作成できるように、iam.serviceAccounts.getOpenIdToken 権限（roles/iam.serviceAccountTokenCreator ロールに含まれる）が付与されている必要があります。

ペイロードのラップ解除

[ペイロードのラップ解除を有効にする] オプションは、メッセージデータを除くすべてのメッセージメタデータの Pub/Sub メッセージを削除します。ペイロードのラップ解除により、メッセージデータは HTTP 本文として直接配信されます。

メタデータを書き込む。前に削除されたメッセージメタデータをリクエストヘッダーに追加し直します。

VPC Service Controls

VPC Service Controls で保護されているプロジェクトの場合、push サブスクリプションに関する次の制限事項に注意してください。

push エンドポイントがデフォルトの run.app URL または Workflows の実行を使用して Cloud Run サービスに設定されている新しい push サブスクリプションのみを作成できます。カスタムドメインは機能しません。
push エンドポイントが Workflows 実行に設定されている Workflows の宛先に Eventarc を介してイベントをルーティングする場合、新しい push サブスクリプションは Eventarc を介してのみ作成できます。
既存の push サブスクリプションを更新することはできません。これらの push サブスクリプションは引き続き機能しますが、VPC Service Controls で保護されません。

push サブスクリプションを作成する

次のサンプルは、指定されたデフォルト設定を使用して、push 配信でサブスクリプションを作成する方法を示しています。

次の例に示すように、デフォルトでは、push 構成を明示的に設定しない限りサブスクリプションでは pull 配信を使用します。

Console

push サブスクリプションを作成する際の手順は、次のとおりです。

Google Cloud コンソールで、[サブスクリプション] ページに移動します。
サブスクリプションに移動
[サブスクリプションを作成] をクリックします。
[サブスクリプション ID] フィールドに名前を入力します。
サブスクリプションの指定方法については、トピックまたはサブスクリプションの指定方法のガイドラインをご覧ください。
プルダウンメニューからトピックを選択するか、作成します。サブスクリプションがトピックからメッセージを受信します。
[配信タイプ] で [push] を選択します。
エンドポイント URL を指定します。
他のすべてのデフォルト値は保持されます。
[作成] をクリックします。

[トピック] セクションからサブスクリプションを作成することもできます。このショートカットは、トピックとサブスクリプションの関連付けに使用できます。

Google Cloud コンソールの トピック ページに移動します。
[トピック] に移動
サブスクリプションを作成するトピックの横のをクリックします。
コンテキストメニューから [サブスクリプションを作成] を選択します。
[サブスクリプション ID] を入力します。
サブスクリプションの指定方法については、トピックまたはサブスクリプションの指定方法のガイドラインをご覧ください。
[配信タイプ] で [push] を選択します。
エンドポイント URL を指定します。
他のすべてのデフォルト値は保持されます。
[作成] をクリックします。

gcloud

Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。

Cloud Shell をアクティブにする

Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
push サブスクリプションを作成するには、gcloud pubsub subscriptions create コマンドを実行します。
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --push-endpoint=PUSH_ENDPOINT
```
以下を置き換えます。
- SUBSCRIPTION_ID: 新しい push サブスクリプションの名前または ID。
- TOPIC_ID: トピックの名前または ID。
- PUSH_ENDPOINT: このサブスクリプションのエンドポイントとして使用する URL。例: https://myproject.appspot.com/myhandler

REST

push サブスクリプションを作成するには、projects.subscriptions.create メソッドを使用します。

リクエスト:

リクエストは、Authorization ヘッダー内のアクセストークンにより認証を受ける必要があります。現在のアプリケーションのデフォルト認証情報のアクセストークンを取得するには、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 はプロジェクト ID です。

SUBSCRIPTION_ID はサブスクリプション ID です。

TOPIC_ID はトピック 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#

このサンプルを試す前に、Pub/Sub クイックスタート: クライアントライブラリの使用にある C# 向けの手順に従って設定を行ってください。詳細については、Pub/Sub C# API のリファレンスドキュメントをご覧ください。

Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。


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 クイックスタート: クライアントライブラリの使用にある Go 向けの手順に従って設定を行ってください。詳細については、Pub/Sub Go API のリファレンスドキュメントをご覧ください。

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

このサンプルを試す前に、Pub/Sub クイックスタート: クライアントライブラリの使用にある 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

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

このサンプルを試す前に、Pub/Sub クイックスタート: クライアントライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、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

このサンプルを試す前に、Pub/Sub クイックスタート: クライアントライブラリの使用にある 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

このサンプルを試す前に、Pub/Sub クイックスタート: クライアントライブラリの使用にある 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

topic        = pubsub.topic topic_id
subscription = topic.subscribe subscription_id,
                               endpoint: endpoint

puts "Push subscription #{subscription_id} created."

次のステップ

gcloud コマンドを使用して、サブスクリプションを作成または変更する。
REST API を使用してサブスクリプションを作成または変更する。

push サブスクリプションを作成する

準備

必要なロールと権限

必要な権限

push サブスクリプション プロパティ

共通の特徴

エンドポイント

Authentication

ペイロードのラップ解除

VPC Service Controls

push サブスクリプションを作成する

Console

gcloud

REST

C++

C#

Go

Java

Node.js

Node.js

PHP

Python

Ruby

次のステップ

push サブスクリプションプロパティ