View the details of a schema

This document shows you how to view schema details for Pub/Sub topics.

Before you begin

• Understand how Pub/Sub schemas work.
• Create a schema.

Required roles and permissions

To get the permissions that you need to view schema details and manage them, ask your administrator to grant you the Pub/Sub Editor (roles/pubsub.editor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to view schema details and manage them. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to view schema details and manage them:

• Create schema: pubsub.schemas.create
• Attach schema to topic: pubsub.schemas.attach
• Commit a schema revision: pubsub.schemas.commit
• Delete a schema or a schema revision: pubsub.schemas.delete
• Get a schema or schema revisions: pubsub.schemas.get
• List schemas: pubsub.schemas.list
• List schema revisions: pubsub.schemas.listRevisions
• Rollback a schema: pubsub.schemas.rollback
• Validate a message: pubsub.schemas.validate
• Get the IAM policy for a schema: pubsub.schemas.getIamPolicy
• Configure the IAM policy for a schema: pubsub.schemas.setIamPolicy

You might also be able to get these permissions with custom roles or other predefined roles.

You can grant roles and permissions to principals such as users, groups, domains, or service accounts. You can create a schema in one project and attach it to a topic located in a different project. Ensure that you have the required permissions for each project.

View schema details

You can get the details of a schema using the Google Cloud console, the gcloud CLI, the Pub/Sub API, or the Cloud Client Libraries. The results return the details for the latest revision ID.

Console

1. In the Google Cloud console, go to the Pub/Sub schemas page.

   Go to Schemas

2. Click the name of the schema that you want to view.

   The Schema details page for the schema opens.

gcloud

To view the latest revision for a schema:

gcloud pubsub schemas describe SCHEMA_NAME

To view a specific revision for a schema:

gcloud pubsub schemas describe SCHEMA_ID@REVISION_ID

Where:

• REVISION_ID is the revision to which you want to roll back.

REST

To get the details of the latest revision of a schema, send a GET request like the following:

GET https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID

For example, for a schema with schema ID schema-inventory, send the following request: https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/schema-inventory

To get the details of a specific revision of a schema, send a GET request like the following:

GET https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID@REVISION_ID

For example, for a schema with schema ID schema-inventory and revision ID fa567a3e, send the following request: https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/schema-inventory@fa567a3e

Where:

• PROJECT_ID is your project ID.
• SCHEMA_ID is your schema ID.
• REVISION_ID is the ID of the revision of the specific schema.

If successful, the response body contains an instance of the Schema class.

C++

Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation.

namespace pubsub = ::google::cloud::pubsub;
[](pubsub::SchemaServiceClient client, std::string const& project_id,
   std::string const& schema_id, std::string const& revision_id) {
  std::string const schema_id_with_revision = schema_id + "@" + revision_id;

  google::pubsub::v1::GetSchemaRequest request;
  request.set_name(
      pubsub::Schema(project_id, schema_id_with_revision).FullName());
  request.set_view(google::pubsub::v1::FULL);
  auto schema = client.GetSchema(request);
  if (!schema) throw std::move(schema).status();

  std::cout << "The schema revision exists and its metadata is:"
            << "\n"
            << schema->DebugString() << "\n";
}

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.

using Google.Cloud.PubSub.V1;

public class GetSchemaSample
{
    public Schema GetSchema(string projectId, string schemaId)
    {
        SchemaServiceClient schemaService = SchemaServiceClient.Create();
        GetSchemaRequest request = new GetSchemaRequest
        {
            SchemaName = SchemaName.FromProjectSchema(projectId, schemaId),
            View = SchemaView.Full
        };

        return schemaService.GetSchema(request);
    }
}

Go

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func getSchemaRevision(w io.Writer, projectID, schemaID string) error {
	// projectID := "my-project-id"
	// schemaID := "my-schema[@my-schema-revision]"
	ctx := context.Background()
	client, err := pubsub.NewSchemaClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewSchemaClient: %w", err)
	}
	defer client.Close()

	s, err := client.Schema(ctx, schemaID, pubsub.SchemaViewFull)
	if err != nil {
		return fmt.Errorf("client.Schema revision: %w", err)
	}
	fmt.Fprintf(w, "Got schema revision: %#v\n", s)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.

import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.pubsub.v1.SchemaServiceClient;
import com.google.pubsub.v1.Schema;
import com.google.pubsub.v1.SchemaName;
import java.io.IOException;

public class GetSchemaRevisionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String schemaId = "your-schema-id[@your-schema-revision]";
    getSchemaRevisionExample(projectId, schemaId);
  }

  public static void getSchemaRevisionExample(String projectId, String schemaId)
      throws IOException {
    SchemaName schemaName = SchemaName.of(projectId, schemaId);

    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {

      Schema schema = schemaServiceClient.getSchema(schemaName);

      System.out.println("Got a schema:\n" + schema);

    } catch (NotFoundException e) {
      System.out.println(schemaName + "not found.");
    }
  }
}

Node.js

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const schemaNameOrId = 'YOUR_SCHEMA_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 getSchema(schemaNameOrId) {
  const schema = pubSubClient.schema(schemaNameOrId);
  const info = await schema.get();
  const fullName = await schema.getName();
  console.log(`Schema ${fullName} info: ${JSON.stringify(info, null, 4)}.`);
}

Node.js

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const schemaNameOrId = 'YOUR_SCHEMA_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function getSchema(schemaNameOrId: string) {
  const schema = pubSubClient.schema(schemaNameOrId);
  const info = await schema.get();
  const fullName = await schema.getName();
  console.log(`Schema ${fullName} info: ${JSON.stringify(info, null, 4)}.`);
}

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Get a schema.
 *
 * @param string $projectId
 * @param string $schemaId
 */
function get_schema($projectId, $schemaId)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);

    $schema = $pubsub->schema($schemaId);
    $schema->info();

    printf('Schema %s retrieved', $schema->name());
}

Python

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.

from google.api_core.exceptions import NotFound
from google.cloud.pubsub import SchemaServiceClient

# TODO(developer): Replace these variables before running the sample.
# project_id = "your-project-id"
# schema_id = "your-schema-id"
# schema_revision_id = "your-schema-revision-id"

schema_client = SchemaServiceClient()
schema_path = schema_client.schema_path(
    project_id, schema_id + "@" + schema_revision_id
)

try:
    result = schema_client.get_schema(request={"name": schema_path})
    print(f"Got a schema revision:\n{result}")
except NotFound:
    print(f"{schema_id} not found.")

Ruby

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.

# schema_id = "your-schema-id"

pubsub = Google::Cloud::Pubsub.new

schema = pubsub.schema schema_id

puts "Schema #{schema.name} retrieved."

What's next

• Delete a schema revision
• Delete a schema
• List schemas
• List revisions of a schema
• Subscribe to a topic with a schema