En este documento, se describe cómo crear una suscripción de envío. Puedes usar la consola de Google Cloud, Google Cloud CLI, la biblioteca cliente o la API de Pub/Sub para crear una suscripción de envío.
Antes de comenzar
- Obtén más información sobre las suscripciones
- Comprende cómo funcionan las suscripciones de envío.
Roles y permisos requeridos
Para crear una suscripción, debes configurar el control de acceso a nivel de proyecto. También necesitas permisos a nivel de recursos si tus suscripciones y temas se encuentran en proyectos diferentes, como se explica más adelante en esta sección.
Si quieres obtener los permisos que necesitas para crear suscripciones de envío, pídele a tu administrador que te otorgue el rol de IAM Editor de Pub/Sub (roles/pubsub.editor
) en el proyecto.
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.
Este rol predefinido contiene los permisos necesarios para crear suscripciones de envío. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios
Se requieren los siguientes permisos para crear suscripciones de envío:
-
Crea una suscripción:
pubsub.subscriptions.create
-
Borrar una suscripción:
pubsub.subscriptions.delete
-
Obtener una suscripción:
pubsub.subscriptions.get
-
Muestra una suscripción:
pubsub.subscriptions.list
-
Actualiza una suscripción:
pubsub.subscriptions.update
-
Adjuntar una suscripción a un tema:
pubsub.topics.attachSubscription
-
Obtén la política de IAM de una suscripción:
pubsub.subscriptions.getIamPolicy
-
Configura la política de IAM para una suscripción:
pubsub.subscriptions.setIamPolicy
Es posible que también puedas obtener estos permisos con funciones personalizadas o con otras funciones predefinidas.
Si necesitas crear suscripciones de envío en un proyecto que estén asociados con un tema de otro proyecto, pídele al administrador de temas que también te otorgue el rol de IAM (roles/pubsub.editor)
del editor de Pub/Sub en el tema.
Propiedades de la suscripción de envío
Cuando configuras una suscripción de envío, puedes especificar las siguientes propiedades.
Propiedades comunes
Obtén información sobre las propiedades de suscripción comunes que puedes configurar en todas las suscripciones.
Extremos
URL del extremo (obligatoria). Una dirección HTTPS de acceso público El servidor para el extremo de envío debe tener un certificado SSL válido firmado por una autoridad certificadora. El servicio Pub/Sub entrega mensajes a los extremos de envío desde la misma región de Google Cloud en la que el servicio de Pub/Sub almacena los mensajes. El servicio Pub/Sub entrega mensajes de la misma región de Google Cloud según el criterio del mejor esfuerzo.
Pub/Sub ya no requiere un comprobante de propiedad para los dominios de URL de suscripción de envío. Si tu dominio recibe solicitudes POST inesperadas de Pub/Sub, puedes denunciar sospechas de abuso.
Proporción de eficiencia energética (EER)
Habilita la autenticación. Cuando está habilitado, los mensajes que entrega Pub/Sub al extremo de envío incluyen un encabezado de autorización para permitir que el extremo autentique la solicitud. Los mecanismos de autenticación y autorización automáticas están disponibles para los extremos del entorno estándar y de Cloud Functions de App Engine alojados en el mismo proyecto que la suscripción.
La configuración de autenticación para una suscripción de envío autenticada consiste en una cuenta de servicio administrada por el usuario y los parámetros de público que se especifican en una llamada create, patch o ModifyPushConfig. También debes otorgar una función específica a una cuenta de servicio especial administrada por Google, como se explica en la siguiente sección.
Cuenta de servicio administrada por el usuario (obligatoria). La cuenta de servicio asociada con la suscripción de envío. Esta cuenta se utiliza como la reclamación
email
del token web JSON (JWT) generado. La siguiente es una lista de requisitos para la cuenta de servicio:Esta cuenta de servicio debe estar en el mismo proyecto que la suscripción de envío.
La principal que crea o modifica la suscripción de envío debe tener el permiso
iam.serviceAccounts.actAs
en la cuenta de servicio. Puedes otorgar una función con este permiso en el proyecto, la carpeta o la organización para permitir que el llamador actúe en nombre de varias cuentas de servicio, o bien otorgar una función con este permiso en la cuenta de servicio para permitir que el emisor suplante solo la identidad de esta cuenta de servicio.
Público. Es una string única que no distingue entre mayúsculas y minúsculas y que el webhook usa para validar el público objetivo de este token en particular.
Cuenta de servicio administrada por Google (obligatoria).
Pub/Sub crea de forma automática una cuenta de servicio con el formato
service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
.A esta cuenta de servicio se le debe otorgar el permiso
iam.serviceAccounts.getOpenIdToken
(incluido en la funciónroles/iam.serviceAccountTokenCreator
) a fin de permitir que Pub/Sub cree tokens JWT para las solicitudes de envío autenticadas.
Desenvolvimiento de la carga útil
La opción Habilitar la separación de la carga útil quita los mensajes de Pub/Sub de todos los metadatos del mensaje, excepto los datos del mensaje. Con la separación de la carga útil, los datos del mensaje se entregan directamente como el cuerpo HTTP.
- Escribe metadatos. Vuelve a agregar los metadatos del mensaje que se quitaron anteriormente al encabezado de la solicitud.
Controles del servicio de VPC
Para un proyecto protegido por los Controles del servicio de VPC, ten en cuenta las siguientes limitaciones para las suscripciones de envío:
Solo puedes crear suscripciones de envío nuevas para las que el extremo de envío esté configurado en un servicio de Cloud Run con una URL
run.app
predeterminada o una ejecución de Workflows. Los dominios personalizados no funcionan.Cuando enrutas eventos a través de Eventarc a destinos de Workflows para los que el extremo de envío está configurado como una ejecución de Workflows, solo puedes crear nuevas suscripciones de envío a través de Eventarc.
No puedes actualizar las suscripciones de envío existentes. Estas suscripciones de envío continúan funcionando, aunque no están protegidas por los Controles del servicio de VPC.
Crea una suscripción de envío
En los siguientes ejemplos, se muestra cómo crear una suscripción con entrega push mediante la configuración predeterminada que se proporciona.
De forma predeterminada, las suscripciones usan la entrega de extracción, a menos que establezcas una configuración de envío explícitamente, como se muestra en los siguientes ejemplos.
Console
Para crear una suscripción de envío, completa los siguientes pasos:
- En la consola de Google Cloud, ve a la página Suscripciones.
- Haz clic en Crear suscripción.
- En el campo ID de la suscripción, ingresa un nombre.
Si quieres obtener información para asignarle un nombre a una suscripción, consulta Lineamientos para asignar el nombre de un tema o una suscripción.
- Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.
- Selecciona el Tipo de entrega como Envío.
- Especifica una URL de extremo.
- Conserva todos los demás valores predeterminados.
- Haz clic en Crear.
Desde la sección Temas también puedes crear una suscripción. Este acceso directo es útil para asociar temas a suscripciones.
- En la consola de Google Cloud, ve a la página Temas.
- Haz clic en more_vert junto al tema en el que se creará una suscripción.
- En el menú contextual, selecciona Crear suscripción (Create subscription).
- Ingresa el ID de suscripción.
Si quieres obtener información para asignarle un nombre a una suscripción, consulta Lineamientos para asignar el nombre de un tema o una suscripción.
- Selecciona el Tipo de entrega como Envío.
- Especifica una URL de extremo.
- Conserva todos los demás valores predeterminados.
- Haz clic en Crear.
gcloud
-
En la consola de Google Cloud, activa Cloud Shell.
En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.
-
Para crear una suscripción de envío, ejecuta el comando
gcloud pubsub subscriptions create
.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT
Reemplaza lo siguiente:
SUBSCRIPTION_ID
: El nombre o el ID de tu nueva suscripción de envío.TOPIC_ID
: Es el nombre o el ID de tu tema.- PUSH_ENDPOINT: Es la URL que se usará como extremo de esta suscripción.
Por ejemplo,
https://myproject.appspot.com/myhandler
REST
Para crear una suscripción de envío, usa el método projects.subscriptions.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 gcloud auth application-default print-access-token.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer ACCESS_TOKEN
Cuerpo de la solicitud:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", // Only needed if you are using push delivery "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" } }
Aquí:
https://myproject.appspot.com/myhandler
Respuesta:
{ "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler", "attributes": { "x-goog-version": "v1" } }, "ackDeadlineSeconds": 10, "messageRetentionDuration": "604800s", "expirationPolicy": { "ttl": "2678400s" } }
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# que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub C#.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Go
Antes de probar esta muestra, sigue las instrucciones de configuración de Go que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Go.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Java
Antes de probar esta muestra, sigue las instrucciones de configuración de Java que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Java.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Node.js
Node.js
PHP
Antes de probar esta muestra, sigue las instrucciones de configuración de PHP que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub PHP.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración de Python que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Python.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Ruby
Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Ruby.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
¿Qué sigue?
- Crea o modifica una suscripción con los comandos
gcloud
. - Crea o modifica una suscripción con las APIs de REST.