List subject versions

You can list the versions of a subject within a specific schema registry in your project.

This document shows you how to list subject versions using the Google Cloud console or the Managed Kafka API.

Required roles and permissions

To get the permissions that you need to list subject versions, ask your administrator to grant you the Managed Kafka Schema Registry Viewer (roles/managedkafka.schemaRegistryViewer) IAM role on your schema registry. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to list subject versions. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to list subject versions:

  • Grant the following permission on the parent subject: managedkafka.versions.list

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

For more information about predefined roles, see the Managed Service for Apache Kafka predefined roles.

List your subject versions

To list all versions of a subject in a specific schema registry within your project, follow these steps.

Console

  1. In the Google Cloud console, go to the Schema registries page.

    Go to schema registry

    A list of schema registries in your project is displayed.

  2. Click the name of the schema registry where your subject is located.

    The Schema registry details page opens. The information displayed on this page is explained in the Schema registry page details section.

  3. From the list of schema subjects in Subjects in this schema registry, click the subject for which you want to list the versions.

    The Subject details page opens, which lists all the versions of the subject.

REST

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

To list subject versions, make a GET request to the projects.locations.schemaRegistries.subjects.versions.list method.

GET https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • LOCATION: the Google Cloud region where the schema registry is located.
  • REGISTRY_ID: the ID of your schema registry.
  • SUBJECT_ID: the ID of the subject.

Example:

GET https://managedkafka.googleapis.com/v1main/projects/test-project/locations/us-central1/schemaRegistries/test_registry/subjects/test_subject/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)

Or with a context:

GET https://managedkafka.googleapis.com/v1main/projects/test-project/locations/us-central1/schemaRegistries/test_registry/contexts/test_context/subjects/test_subject/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)

Where:

  • test-project is your Google Cloud project ID.
  • us-central1 is the Google Cloud region where the schema registry is located.
  • test_registry is the ID of your schema registry.
  • test_context is the ID of the context.
  • test_subject is the ID of the subject.

If the request is successful, the API returns a 200 OK status code. The response body contains a JSON array of subject versions.

The following is a sample successful response:

{
  "versions": [
    {
      "name": "projects/test-project/locations/us-central1/schemaRegistries/test_registry/subjects/test_subject/versions/1",
      "revisionId": "1a2b3c4d",
      "schemaId": "S12345",
      "createTime": "2024-07-15T12:00:00Z",
      "revisionCreateTime": "2024-07-15T12:00:00Z"
    },
    {
      "name": "projects/test-project/locations/us-central1/schemaRegistries/test_registry/subjects/test_subject/versions/2",
      "revisionId": "5e6f7g8h",
      "schemaId": "S67890",
      "createTime": "2024-07-16T14:30:00Z",
      "revisionCreateTime": "2024-07-16T14:30:00Z"
    }
  ]
}

For more information, see the projects.locations.schemaRegistries.subjects.versions.list method documentation.

What's next

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.