このページは Cloud Translation API によって翻訳されました。

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 リクエストを受信した場合は、不正行為を報告できます。

認証

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

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

ユーザーが管理するサービスアカウント（必須）。push サブスクリプションに関連付けられているサービスアカウント。このアカウントは、生成された JSON Web Token（JWT）の email クレームとして使用されます。サービスアカウントの要件は次のとおりです。
- このサービスアカウントは、プッシュサブスクリプションと同じプロジェクトに存在する必要があります。
- push サブスクリプションを作成または変更するプリンシパルには、サービスアカウントに対する iam.serviceAccounts.actAs 権限が必要です。プロジェクト、フォルダ、または組織に対してこの権限を付与することで、呼び出し元が複数のサービスアカウントの権限を借用することを許可するか、サービスアカウントでこの権限を持つロールを付与して、呼び出し元がこのサービスアカウントのみの権限を借用するできるようにすることができます。
オーディエンス。Webhook が特定のトークンの対象オーディエンスの検証に使用する、大文字と小文字が区別されない単一の文字列。
サービスエージェント（必須）。
- 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 サブスクリプションを作成できるのは、push エンドポイントがデフォルトの run.app URL または Workflows の実行で Cloud Run サービスに設定されている場合のみです。カスタムドメインは機能しません。
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

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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."

push サブスクリプションをモニタリングする

Cloud Monitoring には、サブスクリプションをモニタリングするための指標がいくつか用意されています。

Pub/Sub に関連する使用可能なすべての指標とその説明については、Pub/Sub のモニタリングドキュメントをご覧ください。

Pub/Sub 内からサブスクリプションをモニタリングすることもできます。

次のステップ

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

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

準備

必要なロールと権限

必要な権限

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

共通の特徴

エンドポイント

認証

ペイロードのラップ解除

VPC Service Controls

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

Console

gcloud

REST

C++

C#

Go

Java

Node.js

Node.js

PHP

Python

Ruby

push サブスクリプションをモニタリングする

次のステップ

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