Compartir a través de


Envío y recepción de mensajes de colas de Azure Service Bus (TypeScript)

En este tutorial, va a completar los siguientes pasos:

  1. Creación de un espacio de nombres de Service Bus mediante Azure Portal
  2. Creación de una cola de Service Bus mediante Azure Portal.
  3. Escriba una aplicación ESM de TypeScript para usar el paquete de @azure/service-bus en:
    1. Enviar un conjunto de mensajes a la cola.
    2. Recibir esos mensajes de la cola.

Nota

En este inicio rápido se proporcionan instrucciones paso a paso para un escenario sencillo de envío de mensajes a una cola de Service Bus y la recepción de estos. Puede encontrar ejemplos pregenerados de JavaScript y TypeScript para Azure Service Bus en el repositorio del SDK de Azure para JavaScript en GitHub.

Requisitos previos

Si no está familiarizado con el servicio, consulte la información general sobre Service Bus antes de seguir este artículo de inicio rápido.

Para usar este inicio rápido con su propia cuenta de Azure, debe hacer lo siguiente:

  • Instale la CLI de Azure, que proporciona la autenticación sin contraseña en la máquina del desarrollador.
  • Iniciar sesión con su cuenta de Azure en el terminal o en el símbolo del sistema con az login.
  • Usar la misma cuenta al agregar el rol de datos adecuado al recurso.
  • Ejecutar el código en el mismo terminal o símbolo del sistema.
  • Anote el nombre de la cola del espacio de nombres de Service Bus. Lo necesitará en el código.

Nota

Este tutorial funciona con ejemplos que puede copiar y ejecutar mediante Node.js. Para obtener instrucciones acerca de cómo crear una aplicación de Node.js, consulte Creación e implementación de una aplicación Node.js en un sitio web de Azure o Servicio en la nube Node.js (con Windows PowerShell).

Creación de un espacio de nombres en Azure Portal

Para empezar a usar entidades de mensajería de Service Bus en Azure, cree un espacio de nombres con un nombre único en Azure. Un espacio de nombres proporciona un contenedor de ámbito para los recursos de Service Bus, como colas y temas, en la aplicación.

Para crear un espacio de nombres:

  1. Inicie sesión en Azure Portal.

  2. Seleccione el menú flotante de la parte superior izquierda y vaya a la página Todos los servicios.

  3. En la barra de navegación izquierda, seleccione Integración.

  4. Desplácese hacia abajo hasta Servicios de mensajería>Service Bus y seleccione Crear.

    Captura de pantalla que muestra la selección de Crear un recurso, Integración y Service Bus en el menú.

  5. En la pestaña Aspectos básicos de la página Crear espacio de nombres , siga estos pasos:

    1. En Suscripción, elija la suscripción de Azure en la que se va a crear el espacio de nombres.

    2. Para Grupo de recursos, elija un grupo de recursos existente o cree uno nuevo.

    3. Escriba un nombre de espacio de nombres que cumpla las siguientes convenciones de nomenclatura:

      • El nombre debe ser único en Azure. El sistema realiza la comprobación automáticamente para ver si el nombre está disponible.
      • La longitud del nombre es de 6 caracteres como mínimo y 50 como máximo.
      • El nombre solo puede contener letras, números y guiones -.
      • El nombre debe comenzar con una letra y terminar con una letra o un número.
      • El nombre no termina con -sb ni -mgmt.
    4. En Ubicación, elija la región para hospedar el espacio de nombres.

    5. En Plan de tarifa, seleccione el plan de tarifa (Básico, Estándar o Prémium) del espacio de nombres. Para este inicio rápido, seleccione Estándar.

      Si selecciona Nivel Premium , puede habilitar la replicación geográfica para el espacio de nombres. La característica de replicación geográfica garantiza que los metadatos y los datos de un espacio de nombres se repliquen continuamente desde una región primaria a una o varias regiones secundarias.

      Importante

      Si desea usar temas y suscripciones, elija Estándar o Premium. Los temas y las suscripciones no se admiten en el plan de tarifa Básico.

      Si ha seleccionado el plan de tarifa Prémium, especifique el número de unidades de mensajería. El plan Premium proporciona aislamiento de recursos en el nivel de CPU y memoria para que cada carga de trabajo se ejecute de forma aislada. Este contenedor de recursos se llama unidad de mensajería. A cada espacio de nombres prémium se le asigna al menos una unidad de mensajería. Puede seleccionar 1, 2, 4, 8 o 16 unidades de mensajería para cada espacio de nombres prémium de Service Bus. Para más información, consulte Nivel de mensajería Premium de Service Bus.

    6. En la parte inferior de la página, seleccione Revisar y crear.

      Captura de pantalla que muestra la página Crear un espacio de nombres

    7. En la página Revisar y crear, examine la configuración y seleccione Crear.

  6. Una vez que la implementación del recurso se haya realizado correctamente, seleccione Ir al recurso en la página de implementación.

    Captura de pantalla que muestra la página de implementación exitosa con el enlace Ir al recurso.

  7. Verá la página principal del espacio de nombres de Service Bus.

    Captura de pantalla que muestra la página principal del espacio de nombres de Service Bus creado.

Creación de colas en Azure Portal

  1. En la página Espacio de nombres de Service Bus, expanda Entidades en el menú de navegación a la izquierda y seleccione Colas.

  2. En la página Colas, en la barra de herramientas, seleccione + Cola.

  3. Escriba un nombre para la cola. Deje los demás valores con sus valores predeterminados.

  4. Selecciona Crear.

    Captura de pantalla que muestra la página Crear cola.

Autenticación de la aplicación en Azure

En este artículo se muestran dos maneras de conectarse a Azure Service Bus: sin contraseña y cadena de conexión.

La primera opción muestra cómo usar la entidad de seguridad en Microsoft Entra ID y el control de acceso basado en rol (RBAC) para conectarse a un espacio de nombres de Service Bus. No es necesario preocuparse por tener una cadena de conexión codificada de forma rígida en el código, en un archivo de configuración o en un almacenamiento seguro como Azure Key Vault.

La segunda opción muestra cómo usar una cadena de conexión para conectarse a un espacio de nombres de Service Bus. Si no está familiarizado con Azure, es posible que encuentre la opción de cadena de conexión más fácil de seguir. Se recomienda usar la opción sin contraseña en aplicaciones reales y entornos de producción. Para más información, consulte Autenticación y autorización de Service Bus. Para más información sobre la autenticación sin contraseña, consulte Autenticación de aplicaciones .NET.

Asignación de roles al usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que se conecta a Azure Service Bus tiene los permisos correctos. Necesita el rol Propietario de datos de Azure Service Bus para enviar y recibir mensajes. Para asignarse este rol, necesita el rol Administrador de acceso de usuario u otro rol que incluya la Microsoft.Authorization/roleAssignments/write acción.

Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Para más información sobre los ámbitos disponibles para las asignaciones de roles, consulte Descripción del ámbito de RBAC de Azure.

En el ejemplo siguiente se asigna el rol Azure Service Bus Data Owner a la cuenta de usuario, que proporciona un acceso completo a los recursos de Azure Service Bus. En un escenario real, siga el principio de privilegios mínimos para conceder a los usuarios solo los permisos mínimos necesarios para un entorno de producción más seguro.

Roles integrados de Azure para Azure Service Bus

En el caso de Azure Service Bus, la administración de los espacios de nombres y de todos los recursos relacionados mediante Azure Portal y la API de administración de recursos de Azure, ya se ha protegido mediante el modelo de Azure RBAC. Azure proporciona los siguientes roles integrados de Azure para autorizar el acceso a un espacio de nombres de Service Bus:

Si desea crear un rol personalizado, consulte Derechos necesarios para las operaciones de Service Bus.

Incorporación de un usuario de Microsoft Entra al rol Propietario de Azure Service Bus

Asigne el rol Propietario de datos de Azure Service Bus al nombre de usuario de Microsoft Entra en el nivel de espacio de nombres de Service Bus. Esta configuración permite que una aplicación que se ejecute en el contexto de la cuenta de usuario envíe mensajes a una cola o a un tema. Puede recibir mensajes de una cola o de la suscripción de un tema.

Importante

En la mayoría de los casos, la asignación de roles tardará uno o dos minutos en propagarse en Azure. En raras ocasiones, puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. Si no tiene abierta la página Espacio de nombres de Service Bus en Azure-Portal, busque el espacio de nombres de Service Bus mediante la barra de búsqueda principal o el panel de navegación izquierdo.

  2. En la página Información general , seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles.

    Una captura de pantalla que muestra cómo asignar un rol.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Azure Service Bus Data Owner y seleccione el resultado coincidente. Después, haga clic en Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Configurar proyecto

  1. Cree una carpeta de proyecto para contener los archivos de inicio rápido.

  2. En un terminal de la carpeta del proyecto, inicialice el proyecto Node.js.

    npm init -y
    
  3. Abra el archivo package.json en la carpeta del proyecto y agregue la propiedad para configurar ESM. Agregue esta propiedad después de la propiedad version:

    "type":"module",
    
  4. En el archivo package.json, edite la propiedad scripts para compilar los archivos TypeScript. Agregue el script build.

    "scripts": {
        "build": "tsc"
    }
    
  5. Cree un tsconfig.json en el archivo de proyecto para configurar la compilación de ESM de TypeScript y copie lo siguiente en el archivo:

    {
      "compilerOptions": {
        "module": "NodeNext",
        "target": "ESNext",
        "moduleResolution": "NodeNext",
    
        "outDir": "dist",
        "rootDir": "./src",
    
        "esModuleInterop": true,
        "skipLibCheck": true
      },
      "include": ["src/**/*"],
      "exclude": ["node_modules", "dist"]
    }
    
  6. Cree una carpeta src en el proyecto. Aquí es donde colocará los archivos TypeScript creados en este inicio rápido.

Uso del Administrador de paquetes de Node (npm) para instalar el paquete

  1. Para instalar los paquetes de npm necesarios para Service Bus, abra un símbolo del sistema que tenga npm en la ruta de acceso, cambie el directorio a la carpeta en la que quiere colocar los ejemplos y ejecute este comando.

  2. Instale los siguientes paquetes:

    npm install @azure/service-bus @azure/identity
    

mensajes a una cola

El código de ejemplo siguiente muestra cómo enviar un mensaje a una cola.

Debe haber iniciado sesión con el comando az login de la CLI de Azure para que la máquina local proporcione la autenticación sin contraseña necesaria en este código.

  1. Abra el editor que prefiera, como Visual Studio Code.

  2. En la carpeta src, cree un archivo denominado send.ts y pegue el código siguiente en él. Este código envía los nombres de los científicos como mensajes a la cola.

    Importante

    La credencial sin contraseña se proporciona con DefaultAzureCredential.

    import {
        ServiceBusClient,
        ServiceBusSender,
        ServiceBusMessageBatch,
      } from "@azure/service-bus";
    import { DefaultAzureCredential } from "@azure/identity";
    
    // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
    const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
    
    // Passwordless credential
    const credential = new DefaultAzureCredential();
    
    // name of the queue
    const queueName = "<QUEUE NAME>"
    
    const messages = [
        { body: "Albert Einstein" },
        { body: "Werner Heisenberg" },
        { body: "Marie Curie" },
        { body: "Steven Hawking" },
        { body: "Isaac Newton" },
        { body: "Niels Bohr" },
        { body: "Michael Faraday" },
        { body: "Galileo Galilei" },
        { body: "Johannes Kepler" },
        { body: "Nikolaus Kopernikus" }
        ];
    
    async function main() {
        // create a Service Bus client using the passwordless authentication to the Service Bus namespace
        const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
    
        // createSender() can also be used to create a sender for a topic.
        const serviceBusSender: ServiceBusSender = serviceBusClient.createSender(queueName);
    
        try {
            // Tries to send all messages in a single batch.
            // Will fail if the messages cannot fit in a batch.
            // await sender.sendMessages(messages);
    
            // create a batch object
            let serviceBusMessageBatch: ServiceBusMessageBatch = await serviceBusSender.createMessageBatch();
            for (let i = 0; i < messages.length; i++) {
                // for each message in the array
    
                // try to add the message to the batch
                if (!serviceBusMessageBatch.tryAddMessage(messages[i])) {
                    // if it fails to add the message to the current batch
                    // send the current batch as it is full
                    await serviceBusSender.sendMessages(serviceBusMessageBatch);
    
                    // then, create a new batch
                    serviceBusMessageBatch = await serviceBusSender.createMessageBatch();
    
                    // now, add the message failed to be added to the previous batch to this batch
                    if (!serviceBusMessageBatch.tryAddMessage(messages[i])) {
                        // if it still can't be added to the batch, the message is probably too big to fit in a batch
                        throw new Error("Message too big to fit in a batch");
                    }
                }
            }
    
            // Send the last created batch of messages to the queue
            await serviceBusSender.sendMessages(serviceBusMessageBatch);
    
            console.log(`Sent a batch of messages to the queue: ${queueName}`);
    
            // Close the sender
            await serviceBusSender.close();
        } finally {
            await serviceBusSender.close();
        }
    }
    
    // call the main function
    main().catch((err) => {
        console.log("Error occurred: ", err);
        process.exit(1);
        });
    
  3. Reemplace <SERVICE-BUS-NAMESPACE> por el espacio de nombres de Service Bus.

  4. Reemplace <QUEUE NAME> por el nombre de la cola.

  5. Después, ejecute el comando en un símbolo del sistema para ejecutar este archivo.

    npm run build
    node dist/send.js
    
  6. Debería ver la siguiente salida.

    Sent a batch of messages to the queue: myqueue
    

mensajes de una cola

Debe haber iniciado sesión con el comando az login de la CLI de Azure para que la máquina local proporcione la autenticación sin contraseña necesaria en este código.

  1. Abra el editor que prefiera, como Visual Studio Code

  2. En la carpeta src, cree un archivo denominado receive.ts y pegue el código siguiente en él.

    import { delay, ServiceBusClient, ServiceBusMessage, ProcessErrorArgs, ServiceBusReceiver } from "@azure/service-bus";
    import { DefaultAzureCredential } from "@azure/identity";
    
    // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
    const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
    
    // Passwordless credential
    const credential = new DefaultAzureCredential();
    
    // name of the queue
    const queueName = "<QUEUE NAME>"
    
     async function main() {
        // create a Service Bus client using the passwordless authentication to the Service Bus namespace
        const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
    
        // createReceiver() can also be used to create a receiver for a subscription.
        const serviceBusReceiver: ServiceBusReceiver = serviceBusClient.createReceiver(queueName);
    
        // function to handle messages
        const myMessageHandler = async (
            messageReceived: ServiceBusMessage,
        ): Promise<void> => {
            console.log(`Received message: ${messageReceived.body}`);
        };
    
        // function to handle any errors
        const myErrorHandler = async (error: ProcessErrorArgs): Promise<void> => {
            console.log(error);
        };
    
        // subscribe and specify the message and error handlers
        serviceBusReceiver.subscribe({
            processMessage: myMessageHandler,
            processError: myErrorHandler,
        });
    
        // Waiting long enough before closing the sender to send messages
        await delay(20000);
    
        await serviceBusReceiver.close();
        await serviceBusReceiver.close();
    }
    // call the main function
    main().catch((err) => {
        console.log("Error occurred: ", err);
        process.exit(1);
     });
    
  3. Reemplace <SERVICE-BUS-NAMESPACE> por el espacio de nombres de Service Bus.

  4. Reemplace <QUEUE NAME> por el nombre de la cola.

  5. Después, ejecute el comando en un símbolo del sistema para ejecutar este archivo.

    npm run build
    node dist/receive.js
    

Debería ver la siguiente salida.

Received message: Albert Einstein
Received message: Werner Heisenberg
Received message: Marie Curie
Received message: Stephen Hawking
Received message: Isaac Newton
Received message: Niels Bohr
Received message: Michael Faraday
Received message: Galileo Galilei
Received message: Johannes Kepler
Received message: Nikolaus Kopernikus

En la página Información general del espacio de nombres de Service Bus en Azure Portal, verá el recuento de mensajes entrantes y salientes. Es posible que tenga que esperar alrededor de un minuto y luego actualizar la página para ver los valores más recientes.

Captura de pantalla de Azure Portal que muestra el recuento de mensajes entrantes y salientes.

Seleccione la cola en esta página Información general para ir a la página Cola de Service Bus. En esta página también verá el recuento de mensajes entrantes y salientes. También verá otra información, como el tamaño actual de la cola, el tamaño máximo o el recuento de mensajes activos.

Captura de pantalla de Azure Portal en la que se muestran los detalles de la cola.

Solución de problemas

Si recibe uno de los siguientes errores al ejecutar la versión sin contraseña del código TypeScript, asegúrese de que ha iniciado sesión mediante el comando de la CLI de Azure, az login y el rol adecuado se aplica a la cuenta de usuario de Azure:

  • Se requieren notificaciones de envío para realizar esta operación.
  • Se requieren notificaciones de recepción para realizar esta operación.

Limpieza de recursos

Vaya al espacio de nombres de Service Bus en Azure Portal y seleccione Eliminar para eliminar el espacio de nombres y la cola que hay en él.

Pasos siguientes

Consulte la documentación y los ejemplos siguientes: