Asociar un esquema a un tema

En este documento se explica cómo asociar esquemas a temas de Pub/Sub.

Antes de empezar

• Consulta cómo funcionan los esquemas de Pub/Sub.
• Crea un esquema.

Roles y permisos necesarios

Para obtener los permisos que necesitas para asociar y gestionar esquemas, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Pub/Sub (roles/pubsub.editor) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para asociar y gestionar esquemas. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

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

Puedes conceder roles y permisos a entidades 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 que tienes los permisos necesarios para cada proyecto.

Directrices para asociar un esquema a un tema

Puedes asociar un esquema a un tema cuando crees o edites un tema. Estas son las directrices para asociar un esquema a un tema:

• Puede asociar un esquema a uno o varios temas.

  Una vez que se asocia un esquema a un tema, todos los mensajes que reciba el tema de los editores deben seguir ese esquema.

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

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

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

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

Cuando asocias un esquema a un tema y el esquema tiene revisiones, puedes especificar un intervalo de revisiones para usarlo. Si no especificas un intervalo, se usará todo el intervalo para la validación.

Si no especificas una revisión como Primera revisión permitida, se usará la revisión 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 más reciente del esquema.

Tomemos como ejemplo el esquema S, que está asociado 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 a otro ni es una reversión de un esquema ya creado.

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

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

• Si asignas el valor B al campo First revision allowed y el valor C al campo Last revision allowed, se aceptarán los mensajes que se ajusten a los esquemas B y C.

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

Crear y asociar un esquema al crear un tema

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

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 \

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

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

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

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

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";
}

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

public class CreateTopicWithSchemaSample