このドキュメントでは、Pub/Sub トピックのスキーマ リビジョンをコミットする方法について説明します。
始める前に
- Pub/Sub スキーマの仕組みを理解する。
- スキーマの作成
必要なロールと権限
スキーマのリビジョンを commit してスキーマを管理するために必要な権限を取得するには、Pub/Sub 編集者 (roles/pubsub.editor
)プロジェクトに対する IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。
この事前定義ロールには、スキーマのリビジョンを commit してスキーマを管理するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
スキーマ リビジョンを commit してスキーマを管理するには、次の権限が必要です。
-
スキーマを作成します:
pubsub.schemas.create
-
スキーマをトピックに添付します:
pubsub.schemas.attach
-
スキーマのリビジョンを commit します:
pubsub.schemas.commit
-
スキーマまたはスキーマ リビジョンを削除します:
pubsub.schemas.delete
-
スキーマまたはスキーマのリビジョンを取得します:
pubsub.schemas.get
-
スキーマを一覧表示します:
pubsub.schemas.list
-
スキーマのリビジョンを一覧表示します:
pubsub.schemas.listRevisions
-
スキーマをロールバックします:
pubsub.schemas.rollback
-
メッセージを検証します:
pubsub.schemas.validate
-
スキーマの IAM ポリシーを取得します:
pubsub.schemas.getIamPolicy
-
スキーマの IAM ポリシーを構成します:
pubsub.schemas.setIamPolicy
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
ユーザー、グループ、ドメイン、サービス アカウントなどのプリンシパルにロールと権限を付与できます。あるプロジェクトにスキーマを作成し、別のプロジェクトにあるトピックにアタッチできます。プロジェクトごとに必要な権限があることを確認します。
スキーマを修正する
スキーマのリビジョンをコミットするには、Google Cloud コンソール、gcloud CLI、Pub/Sub API、Cloud クライアント ライブラリを使用します。
スキーマ リビジョンを commit するガイドラインは次のとおりです。
特定の制約内でスキーマを変更できます。
プロトコル バッファ スキーマの場合は、オプション フィールドを追加または削除できます。他のフィールドを追加または削除することはできません。また、既存のフィールドを編集することもできません。
Avro スキーマについては、スキーマの解決に関するルールについては Avro のドキュメントをご覧ください。新しいリビジョンは、リーダー スキーマとライター スキーマの両方であるかのように、ルールに従う必要があります。
スキーマには、一度に最大 20 個のリビジョンを設定できます。上限を超えた場合は、スキーマ リビジョンを削除してから別のリビジョンを作成してください。
各リビジョンには一意のリビジョン ID が関連付けられています。リビジョン ID は自動生成された 8 文字の UUID です。
トピックの検証に使用されるリビジョン範囲またはスキーマのリビジョンを更新する場合、変更が有効になるまで数分かかることがあります。
Console
スキーマ リビジョンを作成するには、次の操作を行います。
Google Cloud コンソールで、[Pub/Sub スキーマ] ページに移動します。
既存のスキーマの [スキーマ ID] をクリックします。
スキーマの [スキーマの詳細] ページが開きます。
[Create revision] をクリックします。
[スキーマ リビジョンの作成] ページが開きます。
必要に応じて変更を行います。
たとえば、スキーマを作成するで作成した Avro のサンプル スキーマでは、次のように
Price
というオプション フィールドを追加できます。{ "type": "record", "name": "Avro", "fields": [ { "name": "ProductName", "type": "string", "default": "" }, { "name": "SKU", "type": "int", "default": 0 }, { "name": "InStock", "type": "boolean", "default": false }, { "name": "Price", "type": "double", "default": "0.0" } ] }
[Validate definition] をクリックして、スキーマ定義が正しいかどうかを確認します。
スキーマのメッセージを検証することもできます。
[テスト メッセージ] をクリックしてサンプル メッセージをテストします。
[メッセージのテスト] ウィンドウで、[メッセージ エンコード] のタイプを選択します。
[メッセージ本文] にテスト メッセージを入力します。
たとえば、テストスキーマ用のサンプル メッセージを次に示します。この例では、[メッセージ エンコード] を
JSON
として選択します。{"ProductName":"GreenOnions", "SKU":34543, "Price":12, "InStock":true}
[テスト] をクリックします。
[Commit] をクリックしてスキーマを保存します。
gcloud
gcloud pubsub schemas commit SCHEMA_ID \ --type=SCHEMA_TYPE \ --definition=SCHEMA_DEFINITION
ここで
- SCHEMA_TYPE は
avro
かprotocol-buffer
のどちらかです。 - SCHEMA_DEFINITION は、選択したスキーマタイプに従って形式指定されたスキーマの定義を含む
string
です。
ファイルでスキーマ定義を指定することもできます。
gcloud pubsub schemas commit SCHEMA_ID \ --type=SCHEMA_TYPE \ --definition-file=SCHEMA_DEFINITION_FILE
ここで
- SCHEMA_TYPE は
avro
かprotocol-buffer
のどちらかです。 - SCHEMA_DEFINITION_FILE は、選択したスキーマタイプに従って書式設定されたスキーマの定義が含まれるファイルへのパスを含む
string
です。
REST
スキーマ リビジョンをコミットするには、次のような POST リクエストを送信します。
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID:commit Authorization: Bearer $(gcloud auth application-default print-access-token) Content-Type: application/json --data @response-body.json
リクエスト本文に次のフィールドを指定します。
{ "definition": SCHEMA_DEFINITION "type": SCHEMA_TYPE "name": SCHEMA_NAME }
ここで
- SCHEMA_TYPE は
AVRO
かPROTOCOL_BUFFER
のどちらかです。 - SCHEMA_DEFINITION は、選択したスキーマタイプに従って形式指定されたスキーマの定義を含む文字列です。
- SCHEMA_NAME は、既存のサブネットの名前です。
レスポンスの本文には、スキーマ リソースの JSON 表現を含める必要があります。例:
{ "name": SCHEMA_NAME, "type": SCHEMA_TYPE, "definition": SCHEMA_DEFINITION "revisionId": REVISION_ID "revisionCreateTime": REVISION_CREATE_TIME }
ここで
- REVISION_ID は、リビジョンのサーバー生成 ID です。
- REVISION_CREATE_TIME は、リビジョンが作成された ISO 8601 タイムスタンプです。
Go
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Go の設定手順を実施してください。詳細については、Pub/Sub Go API リファレンス ドキュメントをご覧ください。
Avro
.proto
C++
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の C++ の設定手順を実施してください。詳細については、Pub/Sub C++ API リファレンス ドキュメントをご覧ください。
Avro
.proto
Java
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、Pub/Sub Java API リファレンス ドキュメントをご覧ください。
Avro
.proto
Python
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Python の設定手順を実施してください。詳細については、Pub/Sub Python API リファレンス ドキュメントをご覧ください。
Avro
.proto
Node.js
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、Pub/Sub Node.js API リファレンス ドキュメントをご覧ください。
Avro
.proto
Node.js
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、Pub/Sub Node.js API リファレンス ドキュメントをご覧ください。
Avro
.proto
スキーマのリビジョンを commit すると、[スキーマ] ページで新しいリビジョンの詳細を確認できます。