Asocia un esquema a un tema

En este documento, se muestra cómo asociar esquemas para temas de Pub/Sub.

Antes de comenzar

Roles y permisos requeridos

Para obtener los permisos que necesitas para asociar y administrar esquemas, pídele a tu administrador que te otorgue el rol de IAM de Editor de Pub/Sub (roles/pubsub.editor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para asociar y administrar esquemas. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para asociar y administrar esquemas:

  • Crea un esquema: pubsub.schemas.create
  • Adjunta el esquema al tema: pubsub.schemas.attach
  • Confirma una revisión del esquema: pubsub.schemas.commit
  • Borra un esquema o una revisión del esquema: pubsub.schemas.delete
  • Obtén un esquema o revisiones de esquemas: pubsub.schemas.get
  • Esquemas de lista: pubsub.schemas.list
  • Enumera las revisiones del esquema: pubsub.schemas.listRevisions
  • Cómo revertir un esquema: pubsub.schemas.rollback
  • Valida un mensaje: pubsub.schemas.validate
  • Obtén la política de IAM para un esquema: pubsub.schemas.getIamPolicy
  • Configura la política de IAM para un esquema: pubsub.schemas.setIamPolicy

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Puedes otorgar roles y permisos a principales, como usuarios, grupos, dominios o cuentas de servicio. Puedes crear un esquema en un proyecto y adjuntarlo a un tema ubicado en otro proyecto. Asegúrate de tener los permisos necesarios para cada proyecto.

Lineamientos para asociar un esquema a un tema

Puedes asociar un esquema con un tema cuando creas o editas un tema. A continuación, se indican los lineamientos para asociar un esquema a un tema:

  • Puedes asociar un esquema con uno o más temas.

    Después de que se asocia un esquema a un tema, todos los mensajes que el tema recibe de los publicadores deben seguir ese esquema.

  • Cuando asocias un esquema a un tema, también debes especificar la codificación de los mensajes que se publicarán como BINARY o JSON. Si usas JSON con un esquema de Avro, presta mucha atención a las reglas de codificación para las uniones.

  • Si un esquema asociado a un tema tiene revisiones, los mensajes deben coincidir con la codificación y validarse en función de una revisión dentro del rango disponible. Si no se validan, no se publicará el mensaje.

    Las revisiones se prueban en orden cronológico inverso según la hora de creación. Para crear una revisión del esquema, consulta Confirma una revisión del esquema.

Lógica de validación para un esquema de mensaje

Cuando asocias un esquema con un tema y el esquema tiene revisiones, puedes especificar un rango de subconjunto de revisiones para usar. Si no especificas un rango, se usará el rango completo para la validación.

Si no especificas una revisión como Primera revisión permitida, se usará la revisión existente más antigua del esquema para la validación. Si no especificas una revisión como Última revisión permitida, se usará la revisión existente más reciente para el esquema.

Tomemos el ejemplo del esquema S que se adjunta al tema T.

El esquema S tiene los IDs de revisión A, B, C y D creados en orden, donde A es la primera o la revisión más antigua. Ninguno de los esquemas es idéntico entre sí ni son reversiones de un esquema existente.

  • Si solo configuras el campo Primera revisión permitida como B, se rechazarán los mensajes que solo cumplan con el esquema A, mientras que se aceptarán los mensajes que cumplan con los esquemas B, C y D.

  • Si solo configuras el campo Última revisión permitida como C, se aceptarán los mensajes que cumplan con los esquemas A, B y C, y se rechazarán los mensajes que solo cumplan con el esquema D.

  • Si configuras ambos campos Primera revisión permitida como B y Última revisión permitida como C, se aceptarán los mensajes que cumplan con los esquemas B y C.

  • También puedes establecer la primera y la última revisión en el mismo ID de revisión. En este caso, solo se aceptarán los mensajes que cumplan con esa revisión.

Crea y asocia un esquema cuando crees un tema

Puedes crear un tema con un esquema usando la consola de Google Cloud , gcloud CLI, la API de Pub/Sub o las bibliotecas cliente de Cloud.

Console

  1. En la consola de Google Cloud , ve a la página Temas de Pub/Sub.

    Ir a temas

  2. Haga clic en Crear tema.

  3. En el campo ID de tema, ingresa un ID para tu tema.

    Para asignar un nombre a un tema, consulta los lineamientos.

  4. Marca la casilla Usar un esquema.

    Conserva la configuración predeterminada para los campos restantes.

    Puedes crear un esquema o usar uno existente.

  5. Si creas un esquema, sigue estos pasos: `

    1. En Seleccionar un esquema de Pub/Sub, selecciona Crear un esquema nuevo.

    La página Crear esquema se muestra en una pestaña secundaria.

    Sigue los pasos que se indican en Crea un esquema.

    1. Vuelve a la pestaña Crear tema y haz clic en Actualizar.

    2. Busca tu esquema en el campo Seleccionar un esquema de Pub/Sub.

    3. Selecciona la codificación del mensaje como JSON o Binario.

    El esquema que acabas de crear tiene un ID de revisión. Puedes crear revisiones de esquema adicionales como se explica en Confirma una revisión del esquema.

  6. Si asocias un esquema ya creado, sigue estos pasos:

    1. En Selecciona un esquema de Pub/Sub, elige un esquema existente.

    2. Selecciona la codificación del mensaje como JSON o Binario.

  7. Opcional: Si el esquema seleccionado tiene revisiones, en Rango de revisión, usa los menús desplegables para Primera revisión permitida y Última revisión permitida.

Puedes especificar ambos campos, solo uno o conservar la configuración predeterminada según tus requisitos.

  1. Conserva la configuración predeterminada para los campos restantes.

  2. Haz clic en Crear para guardar el tema y asignarlo al esquema seleccionado.

gcloud

Para crear un tema asignado con un esquema creado anteriormente, ejecuta el comando gcloud pubsub topics create:

gcloud pubsub topics create TOPIC_ID \
        --message-encoding=ENCODING_TYPE \
        --schema=SCHEMA_ID \
        --first-revision-id=FIRST_REVISION_ID \
        --last-revision-id=LAST_REVISION_ID \

Aquí:

  • TOPIC_ID es el ID del tema que creas.
  • ENCODING_TYPE es la codificación de los mensajes validados según el esquema. Este valor se debe establecer en JSON o BINARY.
  • SCHEMA_ID es el ID de un esquema existente.
  • FIRST_REVISION_ID es el ID de la revisión más antigua con la que se validará.
  • LAST_REVISION_ID es el ID de la revisión más reciente con la que se realizará la validación.

Tanto --first-revision-id como --last-revision-id son opcionales.

También puedes asignar un esquema de un proyecto Google Cloud diferente:

gcloud pubsub topics create TOPIC_ID \
        --message-encoding=ENCODING_TYPE \
        --schema=SCHEMA_ID \
        --schema-project=SCHEMA_PROJECT \
        --project=TOPIC_PROJECT

Aquí:

  • SCHEMA_PROJECT es el ID del proyecto de Google Cloud para el esquema.
  • TOPIC_PROJECT es el ID del proyecto Google Cloud del tema.

REST

Para crear un tema, usa el método projects.topics.create:

Solicitud:

La solicitud debe autenticarse con un token de acceso en el encabezado Authorization. A fin de obtener un token de acceso para las credenciales predeterminadas actuales de la aplicación, usa el siguiente comando: gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN

Cuerpo de la solicitud:

{
  "schemaSettings": {
    "schema": "SCHEMA_NAME",
    "encoding": "ENCODING_TYPE"
    "firstRevisionId": "FIRST_REVISION_ID"
    "lastRevisionId": "LAST_REVISION_ID"
  }
}

Aquí:

  • PROJECT_ID es el ID del proyecto.
  • TOPIC_ID es el ID del tema.
  • SCHEMA_NAME es el nombre del esquema con el que se deben validar los mensajes publicados. El formato es el siguiente: projects/PROJECT_ID/schemas/SCHEMA_ID.
  • ENCODING_TYPE es la codificación de los mensajes validados según el esquema. Debe establecerse en JSON o BINARY.
  • FIRST_REVISION_ID es el ID de la revisión más antigua con la que se validará.
  • LAST_REVISION_ID es el ID de la revisión más reciente con la que se realizará la validación.

Tanto firstRevisionId como lastRevisionId son opcionales.

Respuesta:

{
  "name": "projects/PROJECT_ID/topics/TOPIC_ID",
  "schemaSettings": {
    "schema": "SCHEMA_NAME",
    "encoding": "ENCODING_TYPE"
    "firstRevisionId": "FIRST_REVISION_ID"
    "lastRevisionId": "LAST_REVISION_ID"
  }
}

Se omiten firstRevisionId y lastRevisionId si no se proporcionan en la solicitud.

C++

Antes de probar esta muestra, sigue las instrucciones de configuración de C++ en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C++.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::TopicAdminClient client, std::string project_id,
   std::string topic_id, std::string schema_id, std::string const& encoding) {
  google::pubsub::v1::Topic request;
  request.set_name(pubsub::Topic(project_id, std::move(topic_id)).FullName());
  request.mutable_schema_settings()->set_schema(
      pubsub::Schema(std::move(project_id), std::move(schema_id)).FullName());
  request.mutable_schema_settings()->set_encoding(
      encoding == "JSON" ? google::pubsub::v1::JSON
                         : google::pubsub::v1::BINARY);
  auto topic = client.CreateTopic(request);

  // Note that kAlreadyExists is a possible error when the library retries.
  if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The topic already exists\n";
    return;
  }
  if (!topic) throw std::move(topic).status();

  std::cout << "The topic was successfully created: " << topic->DebugString()
            << "\n";
}

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C#.


using Google.Cloud.PubSub.V1;
using Grpc.Core;
using System;

public class CreateTopicWithSchemaSample
{
    public Topic CreateTopicWithSchema(string projectId, string topicId, string schemaId, Encoding encoding)
    {
        PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
        var topicName = TopicName.FromProjectTopic(projectId, topicId);
        Topic topic = new Topic
        {
            TopicName = topicName,
            SchemaSettings = new SchemaSettings
            {
                SchemaAsSchemaName = SchemaName.FromProjectSchema(projectId, schemaId),
                Encoding = encoding
            }
        };

        Topic receivedTopic = null;
        try
        {
            receivedTopic = publisher.CreateTopic(topic);
            Console.WriteLine($"Topic {topic.Name} created.");
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            Console.WriteLine($"Topic {topicName} already exists.");
        }
        return receivedTopic;
    }
}

Go

Antes de probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createTopicWithSchemaRevisions(w io.Writer, projectID, topicID, schemaID, firstRevisionID, lastRevisionID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	// schemaID := "my-schema-id"
	// firstRevisionID := "my-revision-id"
	// lastRevisionID := "my-revision-id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}

	topic := &pubsubpb.Topic{
		Name: fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
		SchemaSettings: &pubsubpb.SchemaSettings{
			Schema:          fmt.Sprintf("projects/%s/schemas/%s", projectID, schemaID),
			FirstRevisionId: firstRevisionID,
			LastRevisionId:  lastRevisionID,
			// Alternative encoding is pubsubpb.Encoding_JSON
			Encoding: pubsubpb.Encoding_BINARY,
		},
	}
	t, err := client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopicWithConfig: %w", err)
	}
	fmt.Fprintf(w, "Created topic with schema revision: %#v\n", t)
	return nil
}

Java

Antes de probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java.


import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.pubsub.v1.Encoding;
import com.google.pubsub.v1.SchemaName;
import com.google.pubsub.v1.SchemaSettings;
import com.google.pubsub.v1.Topic;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreateTopicWithSchemaRevisionsExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    // Use an existing schema.
    String schemaId = "your-schema-id";
    // Choose either BINARY or JSON message serialization in this topic.
    Encoding encoding = Encoding.BINARY;
    // Set the minimum and maximum revsion ID
    String firstRevisionId = "your-revision-id";
    String lastRevisionId = "your-revision-id";

    createTopicWithSchemaRevisionsExample(
        projectId, topicId, schemaId, firstRevisionId, lastRevisionId, encoding);
  }

  public static void createTopicWithSchemaRevisionsExample(
      String projectId,
      String topicId,
      String schemaId,
      String firstRevisionid,
      String lastRevisionId,
      Encoding encoding)
      throws IOException {
    TopicName topicName = TopicName.of(projectId, topicId);
    SchemaName schemaName = SchemaName.of(projectId, schemaId);

    SchemaSettings schemaSettings =
        SchemaSettings.newBuilder()
            .setSchema(schemaName.toString())
            .setFirstRevisionId(firstRevisionid)
            .setLastRevisionId(lastRevisionId)
            .setEncoding(encoding)
            .build();

    try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {

      Topic topic =
          topicAdminClient.createTopic(
              Topic.newBuilder()
                  .setName(topicName.toString())
                  .setSchemaSettings(schemaSettings)
                  .build());

      System.out.println("Created topic with schema: " + topic.getName());
    } catch (AlreadyExistsException e) {
      System.out.println(schemaName + "already exists.");
    }
  }
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const schemaName = 'YOUR_SCHEMA_NAME_OR_ID';
// const encodingType = 'BINARY';

// 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 createTopicWithSchema(
  topicNameOrId,
  schemaNameOrId,
  encodingType,
) {
  // Get the fully qualified schema name.
  const schema = pubSubClient.schema(schemaNameOrId);
  const fullName = await schema.getName();

  // Creates a new topic with a schema. Note that you might also
  // pass Encodings.Json or Encodings.Binary here.
  await pubSubClient.createTopic({
    name: topicNameOrId,
    schemaSettings: {
      schema: fullName,
      encoding: encodingType,
    },
  });
  console.log(`Topic ${topicNameOrId} created with schema ${fullName}.`);
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const schemaName = 'YOUR_SCHEMA_NAME_OR_ID';
// const encodingType = 'BINARY';

// 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 createTopicWithSchema(
  topicNameOrId: string,
  schemaNameOrId: string,
  encodingType: 'BINARY' | 'JSON',
) {
  // Get the fully qualified schema name.
  const schema = pubSubClient.schema(schemaNameOrId);
  const fullName = await schema.getName();

  // Creates a new topic with a schema. Note that you might also
  // pass Encodings.Json or Encodings.Binary here.
  await pubSubClient.createTopic({
    name: topicNameOrId,
    schemaSettings: {
      schema: fullName,
      encoding: encodingType,
    },
  });
  console.log(`Topic ${topicNameOrId} created with schema ${fullName}.`);
}

PHP

Antes de probar esta muestra, sigue las instrucciones de configuración de PHP en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para PHP.

use Google\Cloud\PubSub\PubSubClient;
use Google\Cloud\PubSub\Schema;

/**
 * Create a topic with a schema.
 *
 * @param string $projectId
 * @param string $topicId
 * @param string $schemaId
 * @param string $encoding
 */
function create_topic_with_schema($projectId, $topicId, $schemaId, $encoding)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);

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

    $topic = $pubsub->createTopic($topicId, [
        'schemaSettings' => [
            // The schema may be provided as an instance of the schema type,
            // or by using the schema ID directly.
            'schema' => $schema,
            // Encoding may be either `BINARY` or `JSON`.
            // Provide a string or a constant from Google\Cloud\PubSub\V1\Encoding.
            'encoding' => $encoding,
        ]
    ]);

    printf('Topic %s created', $topic->name());
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.

from google.api_core.exceptions import AlreadyExists, InvalidArgument
from google.cloud.pubsub import PublisherClient, SchemaServiceClient
from google.pubsub_v1.types import Encoding

# TODO(developer): Replace these variables before running the sample.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# schema_id = "your-schema-id"
# first_revision_id = "your-revision-id"
# last_revision_id = "your-revision-id"
# Choose either BINARY or JSON as valid message encoding in this topic.
# message_encoding = "BINARY"

publisher_client = PublisherClient()
topic_path = publisher_client.topic_path(project_id, topic_id)

schema_client = SchemaServiceClient()
schema_path = schema_client.schema_path(project_id, schema_id)

if message_encoding == "BINARY":
    encoding = Encoding.BINARY
elif message_encoding == "JSON":
    encoding = Encoding.JSON
else:
    encoding = Encoding.ENCODING_UNSPECIFIED

try:
    response = publisher_client.create_topic(
        request={
            "name": topic_path,
            "schema_settings": {
                "schema": schema_path,
                "encoding": encoding,
                "first_revision_id": first_revision_id,
                "last_revision_id": last_revision_id,
            },
        }
    )
    print(f"Created a topic:\n{response}")

except AlreadyExists:
    print(f"{topic_id} already exists.")
except InvalidArgument:
    print("Please choose either BINARY or JSON as a valid message encoding type.")

Ruby

Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Ruby.

# topic_id = "your-topic-id"
# schema_id = "your-schema-id"
# Choose either BINARY or JSON as valid message encoding in this topic.
# message_encoding = :binary

pubsub = Google::Cloud::Pubsub.new

topic = pubsub.create_topic topic_id, schema_name: schema_id, message_encoding: message_encoding

puts "Topic #{topic.name} created."

Cómo editar un esquema asociado a un tema

Puedes editar un tema para adjuntar o quitar un esquema, o bien actualizar el rango de revisión que se usa para validar mensajes. En general, si tienes cambios planificados para el esquema en uso, puedes confirmar una revisión nueva y actualizar el rango de revisiones que se usan para el tema.

Puedes editar un esquema asociado a un tema con la consola deGoogle Cloud , gcloud CLI, la API de Pub/Sub o las bibliotecas cliente de Cloud.

Console

  1. En la consola de Google Cloud , ve a la página Temas de Pub/Sub.

    Ir a temas

  2. Haz clic en el ID del tema de un tema.

  3. En la página de detalles del tema, haz clic en Editar.

  4. Puedes realizar los siguientes cambios en el esquema.

    Es posible que los cambios tarden unos minutos en aplicarse.

    • Si quieres quitar el esquema del tema, en la página Editar tema, desmarca la casilla de verificación Usar un esquema.

    • Si quieres cambiar el esquema, en la sección Esquema, selecciona el nombre de un esquema.

    Actualiza los otros campos según sea necesario.

    • Si deseas actualizar el rango de revisión, en Rango de revisión, usa los menús desplegables de Primera revisión permitida y Última revisión permitida.

    Puedes especificar ambos campos, solo uno o conservar la configuración predeterminada según tus requisitos.

  5. Haz clic en Actualizar para guardar los cambios.

gcloud

gcloud pubsub topics update TOPIC_ID \
        --message-encoding=ENCODING_TYPE \
        --schema=SCHEMA_NAME \
        --first-revision-id=FIRST_REVISION_ID \
        --last-revision-id=LAST_REVISION_ID \

Aquí:

  • TOPIC_ID es el ID del tema que creas.
  • ENCODING_TYPE es la codificación de los mensajes validados según el esquema. Este valor se debe establecer en JSON o BINARY.
  • SCHEMA_NAME es el nombre de un esquema existente.
  • FIRST_REVISION_ID es el ID de la revisión más antigua con la que se validará.
  • LAST_REVISION_ID es el ID de la revisión más reciente con la que se realizará la validación.

Tanto --first-revision-id como --last-revision-id son opcionales.

REST

Para actualizar un tema, usa el método projects.topics.patch:

Solicitud:

La solicitud debe autenticarse con un token de acceso en el encabezado Authorization. A fin de obtener un token de acceso para las credenciales predeterminadas actuales de la aplicación, usa el siguiente comando: gcloud auth application-default print-access-token.

PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN

Cuerpo de la solicitud:

{
  "schemaSettings": {
    "schema": "SCHEMA_NAME",
    "encoding": "ENCODING_TYPE"
    "firstRevisionId": "FIRST_REVISION_ID"
    "lastRevisionId": "LAST_REVISION_ID"
    "update_mask":
  }
}

Aquí:

  • PROJECT_ID es el ID del proyecto.
  • TOPIC_ID es el ID del tema.
  • SCHEMA_NAME es el nombre del esquema con el que se deben validar los mensajes publicados. El formato es el siguiente: projects/PROJECT_ID/schemas/SCHEMA_ID.
  • ENCODING_TYPE es la codificación de los mensajes validados según el esquema. Debe establecerse en JSON o BINARY.
  • FIRST_REVISION_ID es el ID de la revisión más antigua con la que se validará.
  • LAST_REVISION_ID es el ID de la revisión más reciente con la que se realizará la validación.

Tanto firstRevisionId como lastRevisionId son opcionales.

Respuesta:

{
  "name": "projects/PROJECT_ID/topics/TOPIC_ID",
  "schemaSettings": {
    "schema": "SCHEMA_NAME",
    "encoding": "ENCODING_TYPE"
    "firstRevisionId": "FIRST_REVISION_ID"
    "lastRevisionId": "LAST_REVISION_ID"
  }
}

Ni firstRevisionId ni lastRevisionId se configuran después de la actualización.

C++

Antes de probar esta muestra, sigue las instrucciones de configuración de C++ en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C++.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::TopicAdminClient client, std::string project_id,
   std::string topic_id, std::string const& first_revision_id,
   std::string const& last_revision_id) {
  google::pubsub::v1::UpdateTopicRequest request;
  auto* request_topic = request.mutable_topic();
  request_topic->set_name(
      pubsub::Topic(std::move(project_id), std::move(topic_id)).FullName());
  request_topic->mutable_schema_settings()->set_first_revision_id(
      first_revision_id);
  request_topic->mutable_schema_settings()->set_last_revision_id(
      last_revision_id);
  *request.mutable_update_mask()->add_paths() =
      "schema_settings.first_revision_id";
  *request.mutable_update_mask()->add_paths() =
      "schema_settings.last_revision_id";
  auto topic = client.UpdateTopic(request);

  if (!topic) throw std::move(topic).status();

  std::cout << "The topic was successfully updated: " << topic->DebugString()
            << "\n";
}

Go

Antes de probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

func updateTopicSchema(w io.Writer, projectID, topicID, firstRevisionID, lastRevisionID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic" // an existing topic that has schema settings attached to it.
	// firstRevisionID := "my-revision-id"
	// lastRevisionID := "my-revision-id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}

	// This updates the first / last revision ID for the topic's schema.
	// To clear the schema entirely, use a zero valued (empty) SchemaSettings
	// with the same field mask.
	req := &pubsubpb.UpdateTopicRequest{
		Topic: &pubsubpb.Topic{
			Name: fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
			SchemaSettings: &pubsubpb.SchemaSettings{
				FirstRevisionId: firstRevisionID,
				LastRevisionId:  lastRevisionID,
			},
		},
		// Construct a field mask to indicate which field to update in the topic.
		// Fields are specified relative to the topic
		UpdateMask: &fieldmaskpb.FieldMask{
			Paths: []string{"schema_settings.first_revision_id", "schema_settings.last_revision_id"},
		},
	}
	gotTopicCfg, err := client.TopicAdminClient.UpdateTopic(ctx, req)
	if err != nil {
		fmt.Fprintf(w, "topic.Update err: %v\n", gotTopicCfg)
		return err
	}
	fmt.Fprintf(w, "Updated topic with schema: %#v\n", gotTopicCfg)
	return nil
}

Java

Antes de probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java.


import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.protobuf.FieldMask;
import com.google.pubsub.v1.SchemaSettings;
import com.google.pubsub.v1.Topic;
import com.google.pubsub.v1.TopicName;
import com.google.pubsub.v1.UpdateTopicRequest;
import java.io.IOException;

public class UpdateTopicSchemaExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    // This is an existing topic that has schema settings attached to it.
    String topicId = "your-topic-id";
    // Set the minimum and maximum revsion ID
    String firstRevisionId = "your-revision-id";
    String lastRevisionId = "your-revision-id";

    UpdateTopicSchemaExample.updateTopicSchemaExample(
        projectId, topicId, firstRevisionId, lastRevisionId);
  }

  public static void updateTopicSchemaExample(
      String projectId, String topicId, String firstRevisionid, String lastRevisionId)
      throws IOException {
    try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {

      TopicName topicName = TopicName.of(projectId, topicId);

      // Construct the schema settings with the changes you want to make.
      SchemaSettings schemaSettings =
          SchemaSettings.newBuilder()
              .setFirstRevisionId(firstRevisionid)
              .setLastRevisionId(lastRevisionId)
              .build();

      // Construct the topic with the schema settings you want to change.
      Topic topic =
          Topic.newBuilder()
              .setName(topicName.toString())
              .setSchemaSettings(schemaSettings)
              .build();

      // Construct a field mask to indicate which field to update in the topic.
      FieldMask updateMask =
          FieldMask.newBuilder()
              .addPaths("schema_settings.first_revision_id")
              .addPaths("schema_settings.last_revision_id")
              .build();

      UpdateTopicRequest request =
          UpdateTopicRequest.newBuilder().setTopic(topic).setUpdateMask(updateMask).build();

      Topic response = topicAdminClient.updateTopic(request);

      System.out.println("Updated topic with schema: " + topic.getName());
    }
  }
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.

from google.api_core.exceptions import InvalidArgument, NotFound
from google.cloud.pubsub import PublisherClient

# TODO(developer): Replace these variables before running the sample.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# first_revision_id = "your-revision-id"
# last_revision_id = "your-revision-id"

publisher_client = PublisherClient()
topic_path = publisher_client.topic_path(project_id, topic_id)

try:
    response = publisher_client.update_topic(
        request={
            "topic": {
                "name": topic_path,
                "schema_settings": {
                    "first_revision_id": first_revision_id,
                    "last_revision_id": last_revision_id,
                },
            },
            "update_mask": "schemaSettings.firstRevisionId,schemaSettings.lastRevisionId",
        }
    )
    print(f"Updated a topic schema:\n{response}")

except NotFound:
    print(f"{topic_id} not found.")
except InvalidArgument:
    print("Schema settings are not valid.")

¿Qué sigue?