En este documento, se muestra cómo asociar esquemas para temas de Pub/Sub.
Antes de comenzar
- Obtén información sobre cómo funcionan los esquemas de Pub/Sub.
- Crea un esquema.
Funciones y permisos requeridos
A fin de obtener los permisos que necesitas para asociar y administrar esquemas,
solicita 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.
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 un esquema al tema:
pubsub.schemas.attach
-
Confirma una revisión del esquema:
pubsub.schemas.commit
-
Borra un esquema o una revisión de esquema:
pubsub.schemas.delete
-
Obtén un esquema o revisiones de esquema:
pubsub.schemas.get
-
Enumera los esquemas:
pubsub.schemas.list
-
Enumera las revisiones de esquema:
pubsub.schemas.listRevisions
-
Revierte 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 adjuntarlo a un tema ubicado en un proyecto diferente. Asegúrate de tener los permisos necesarios para cada proyecto.
Lineamientos para asociar un esquema con un tema
Puedes asociar un esquema a un tema cuando creas o editas un tema. Estos son los lineamientos para asociar un esquema con un tema:
Puedes asociar un esquema con uno o más temas.
Después de que se asocia un esquema con un tema, todos los mensajes a los que recibe de los publicadores debe 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
oJSON
. Si usas JSON con un En el esquema de Avro, presta mucha atención a las reglas de codificación para uniones.Si un esquema asociado a un tema tiene revisiones, los mensajes deben coincidir con y validarlos con una revisión dentro del rango disponible. Si no se validan, el mensaje no se publica.
Las revisiones se prueban en orden cronológico inverso según el hora de creación. Para crear una revisión de esquema, consulta Confirma una revisión del esquema.
Lógica de validación para un esquema de mensaje
Cuando asocias un esquema a un tema y si el esquema tiene revisiones, puedes especificar un subconjunto de revisiones para usar. Si no especificas un rango completo, se usa todo el rango para la validación.
Si no especificas una revisión como Primera revisión permitida, se usa para la validación la revisión existente más antigua del esquema. Si no especificas una revisión como Última revisión permitida, Luego, se usa la revisión existente más reciente del esquema.
Tomemos el ejemplo del esquema S
adjunto al tema T
.
El esquema S
tiene los IDs de revisión A
, B
, C
y D
creados en orden.
En el ejemplo anterior, A
es la primera revisión o la más antigua. Ninguno de los esquemas es idéntico
entre sí o reversiones de un esquema existente.
Si solo configuras el campo First revision allowed como
B
, los mensajes que solo se ajustan al esquemaA
se rechazan y se aceptan mensajes que cumplen con los esquemasB
,C
yD
.Si solo configuras el campo Última revisión permitida como
C
, que cumplen con los esquemasA
,B
yC
. y se rechazan los que solo se ajustan al esquemaD
.Si estableces ambos campos en First revision allowed, como
B
y Última revisión permitida comoC
, mensajes que cumplen con Se aceptan los esquemasB
yC
.También puedes establecer la primera y la última revisión con el mismo ID de revisión. En este caso, solo se aceptan los mensajes que cumplen con esa revisión.
Crea y asocia un esquema cuando creas 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
En la consola de Google Cloud, ve a la página Temas de Pub/Sub.
Haga clic en Crear tema.
En el campo ID de tema, ingresa un ID para tu tema.
Para asignar un nombre a un tema, consulta los lineamientos.
Marca la casilla Usar un esquema.
Mantén la configuración predeterminada para los campos restantes.
Puedes crear un esquema o usar uno existente.
Si creas un esquema, sigue estos pasos:
- En Selecciona un esquema de Pub/Sub, elige Crear un esquema nuevo.
Se mostrará la página Crear esquema en una pestaña secundaria.
Sigue los pasos que se indican en Crea un esquema.
Vuelve a la pestaña Crear tema y haz clic en Actualizar.
Busca tu esquema en el campo Selecciona un esquema de Pub/Sub.
Selecciona la codificación de mensajes como JSON o Binario.
El esquema que acabas de crear tiene un ID de revisión. Puedes crear más revisiones de esquema, como se describe en Confirma una revisión de esquema.
Si asocias un esquema ya creado, sigue estos pasos:
En Selecciona un esquema de Pub/Sub, elige un esquema existente.
Selecciona la codificación del mensaje como JSON o Binario.
Opcional: Si el esquema seleccionado tiene revisiones, para Rango de revisión, usa los menús desplegables de Se permite la primera revisión y Última revisión permitida:
Puedes especificar ambos campos, especificar solo uno o mantener el valor predeterminado según tus requisitos.
Mantén la configuración predeterminada para los campos restantes.
Haz clic en Crear para guardar el tema y asignarlo al esquema seleccionado.
gcloud
Para crear un tema asignado con un esquema creado previamente, ejecuta el siguiente 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 estás creando.
- ENCODING_TYPE es la codificación de los mensajes validados en función del
. Este valor se debe establecer en
JSON
oBINARY
. - SCHEMA_ID es el ID de un esquema existente.
- FIRST_REVISION_ID es el ID de la revisión más antigua que se validará.
- LAST_REVISION_ID es el ID de la revisión más reciente que se validará.
--first-revision-id
y --last-revision-id
son opcionales.
También puedes asignar un esquema desde otro proyecto de Google Cloud:
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 de Google Cloud del tema.
REST
Para crear un tema, usa la projects.topics.create
.
método:
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. Se debe configurar como
JSON
oBINARY
. - FIRST_REVISION_ID es el ID de la revisión más antigua que se validará.
- LAST_REVISION_ID es el ID de la revisión más reciente que se validará.
firstRevisionId
y 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" } }
Si no se proporcionan, se omiten firstRevisionId
y lastRevisionId
.
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++.
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#.
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.
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.
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.
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.
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.
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.
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.
Editar un esquema asociado a un tema
Puedes editar un tema para adjuntar un esquema, quitar un esquema o actualizar el rango de revisión que se usa para validar mensajes En general, si tiene cambios planificados para el esquema en uso puedes confirmar una nueva revisión y y actualizarás el rango de revisiones que se usan en el tema.
Puedes editar un esquema asociado a un tema usando el La consola de Google Cloud, gcloud CLI, la API de Pub/Sub, o las bibliotecas cliente de Cloud.
Console
En la consola de Google Cloud, ve a la página Temas de Pub/Sub.
Haz clic en el ID del tema de un tema.
En la página de detalles del tema, haz clic en Editar.
Puedes realizar los siguientes cambios en el esquema.
Es posible que los cambios tarden unos minutos en aplicarse.
Si deseas 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 demás campos según sea necesario.
- Si quieres actualizar el rango de revisión para Revision Range, haz lo siguiente: usa los menús desplegables de Se permite la primera revisión y Última revisión permitida:
Puedes especificar ambos campos, especificar solo uno o mantener el valor predeterminado según tus requisitos.
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 estás creando.
- ENCODING_TYPE es la codificación de los mensajes validados en función del
. Este valor se debe establecer en
JSON
oBINARY
. - SCHEMA_NAME es el nombre de un esquema existente.
- FIRST_REVISION_ID es el ID de la revisión más antigua que se validará.
- LAST_REVISION_ID es el ID de la revisión más reciente que se validará.
--first-revision-id
y --last-revision-id
son opcionales.
REST
Para actualizar un tema, usa projects.topics.patch
.
método:
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. Se debe configurar como
JSON
oBINARY
. - FIRST_REVISION_ID es el ID de la revisión más antigua que se validará.
- LAST_REVISION_ID es el ID de la revisión más reciente que se validará.
firstRevisionId
y 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" } }
Tanto firstRevisionId
como lastRevisionId
no se establecen después de
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++.
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.
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.
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.
0¿Qué sigue?
- Confirma una revisión del esquema
- Publica mensajes en un tema con un esquema
- Cómo validar una definición de esquema
- Valida un mensaje para un esquema