google-pubsub

Google Cloud Pub/Sub の主要知識

完全なリファレンス：Java／Python／Go のプロデューサーパターン、Spring Cloud GCP のコンシューマー、プッシュサブスクリプションのハンドラー、DLT、IAM、VPC Service Controls、監視アラート向けの Terraform については、advanced.md を参照してください。

詳細な知識：包括的なドキュメントについては、テクノロジーに google-pubsub を指定して mcp__documentation__fetch_docs を使用してください。

クイックスタート（エミュレーター）

# docker-compose.yml
services:
  pubsub:
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:emulators
    command: gcloud beta emulators pubsub start --host-port=0.0.0.0:8085
    ports:
      - "8085:8085"

docker-compose up -d

# Set emulator env
export PUBSUB_EMULATOR_HOST=localhost:8085

# Create topic and subscription
gcloud pubsub topics create orders
gcloud pubsub subscriptions create order-processor --topic=orders

# Test
gcloud pubsub topics publish orders --message='{"id":"123"}'
gcloud pubsub subscriptions pull order-processor --auto-ack

主要な概念

概念	説明
トピック	メッセージを公開するための名前付きリソース
サブスクリプション	メッセージを受信するための名前付きリソース
パブリッシャー	トピックにメッセージを送信します
サブスクライバー	サブスクリプションからメッセージを受信します
確認期限	再配信されるまでに確認応答する期限です
メッセージ保持期間	確認応答されていないメッセージを保持する期間です

配信タイプ

タイプ	説明	ユースケース
プル	サブスクライバーがメッセージを要求します	バッチ処理、負荷の変動がある場合
プッシュ	Pub/Sub がエンドポイントに送信します	サーバーレス、Webhook
BigQuery	BigQuery に直接エクスポートします	分析パイプライン
Cloud Storage	GCS に直接エクスポートします	データのアーカイブ

アーキテクチャ

Publisher ──▶ Topic ──▶ Subscription 1 (Pull) ──▶ Subscriber
                   ──▶ Subscription 2 (Push) ──▶ Cloud Run
                   ──▶ Subscription 3 ──▶ BigQuery

Node.js プロデューサー（@google-cloud/pubsub）

import { PubSub } from '@google-cloud/pubsub';

const pubsub = new PubSub({
  projectId: 'my-project',
});

const topic = pubsub.topic('orders');

// Publish single message
const messageId = await topic.publishMessage({
  data: Buffer.from(JSON.stringify(order)),
  attributes: {
    'correlation-id': correlationId,
    'order-type': order.type,
  },
  orderingKey: order.customerId, // For ordered delivery
});

// Batch publishing (automatic batching)
const publishOptions = {
  batching: {
    maxMessages: 100,
    maxMilliseconds: 10,
  },
};
const batchTopic = pubsub.topic('orders', publishOptions);

Node.js コンシューマー（プルサブスクリプション）

const subscription = pubsub.subscription('order-processor', {
  flowControl: {
    maxMessages: 100,
    maxExtensionMinutes: 10,
  },
  ackDeadline: 30,
});

const messageHandler = async (message) => {
  try {
    const order = JSON.parse(message.data.toString());
    const correlationId = message.attributes['correlation-id'];

    await processOrder(order);
    message.ack();
  } catch (error) {
    console.error('Processing failed:', error);
    message.nack(); // Will be redelivered
  }
};

subscription.on('message', messageHandler);
subscription.on('error', (error) => console.error('Subscription error:', error));

// Graceful shutdown
process.on('SIGTERM', async () => {
  await subscription.close();
});

デッドレタートピック

# Create DLT
gcloud pubsub topics create orders-dlq
gcloud pubsub subscriptions create orders-dlq-sub --topic=orders-dlq

# Create subscription with DLT
gcloud pubsub subscriptions create order-processor \
  --topic=orders \
  --dead-letter-topic=orders-dlq \
  --max-delivery-attempts=5

このスキルを使用しない場合

次の場合は、別のメッセージングソリューションを使用してください。

• AWS ネイティブのアーキテクチャ：SQS のほうが AWS との統合に優れています
• Azure ネイティブのアーキテクチャ：Azure Service Bus を使用してください
• リプレイを伴うイベントストリーミング：Dataflow または Kafka を使用してください
• オンプレミスへのデプロイ：RabbitMQ または ActiveMQ を使用してください
• マルチクラウドでの可搬性：Kafka または RabbitMQ を使用してください
• 複雑なルーティングパターン：RabbitMQ のほうが柔軟性に優れています
• JMS への準拠が必要：ActiveMQ を使用してください

アンチパターン

アンチパターン	問題点	解決策
デッドレタートピックがない	失敗したメッセージが失われます	すべてのサブスクリプションに DLT を設定します
確認期限が短い	メッセージが重複処理されます	最大処理時間より長い期限を設定します
再試行ポリシーがない	失敗時にすぐ再配信されます	指数バックオフを設定します
同期的な公開	スループットが低下します	バッチ処理と非同期公開を使用します
フロー制御なしのプル	コンシューマーが過負荷になります	max_messages の上限を設定します
必要な場合にメッセージ順序を指定しない	順不同で処理されます	順序指定キーを使用します
メッセージペイロードが大きい	コストが増加し、パフォーマンスが低下します	参照先として Cloud Storage を使用します
IAM の最小権限を適用しない	セキュリティリスクが生じます	最小限のロールを持つサービスアカウントを使用します

トラブルシューティングのクイックガイド

問題	考えられる原因	対処法
メッセージを受信できない	サブスクリプションがない、またはトピックが間違っています	サブスクリプションを作成し、トピックを確認します
メッセージが重複する	確認期限が切れています	確認期限を延長するか、処理を速くします
メッセージが DLT にある	最大配信試行回数を超えています	処理ロジックを確認し、DLT を確認します
権限が拒否される	IAM ロールがありません	Publisher／Subscriber ロールを付与します
順序が保証されない	順序指定キーがない、またはサブスクリプションが間違っています	順序指定キーを設定し、メッセージの順序指定を有効にします
レイテンシが高い	バッチ処理の遅延、またはネットワークの問題です	バッチ遅延を短縮し、ネットワークを確認します
プッシュサブスクリプションが失敗する	エンドポイントが停止している、または認証に失敗しています	エンドポイントの正常性を確認し、認証を検証します
バックログが増加している	コンシューマーの処理速度が遅い	コンシューマーを追加するか、処理を最適化します

本番環境への対応

監視メトリクス

メトリクス	アラートのしきい値
num_undelivered_messages	> 10000
oldest_unacked_message_age	> 3600s
num_outstanding_messages	> 10000
dead_letter_message_count	> 0
publish_latencies	p99 > 1s

チェックリスト

• 最小権限の IAM ロール
• コンポーネントごとのサービスアカウント
• デッドレタートピックの設定
• 再試行ポリシーの設定
• 適切な ACK 期限
• メッセージ保持期間の設定
• モニタリングアラートの設定
• スキーマ検証（必要な場合）
• メッセージ順序の設定（必要な場合）
• VPC Service Controls（必要な場合）

リファレンスドキュメント

詳細なナレッジ：包括的なドキュメントを参照するには、テクノロジーとして google-pubsub を指定して mcp__documentation__fetch_docs を使用してください。

利用可能なトピック：basics、producers、consumers、production