Contact UsGet started

Getting started with EventRouter

Written by
Updated at March 28, 2025

Note

EventRouter is at the Preview stage. To gain access, submit a request in the management console.

In this tutorial, you will use an EventRouter bus to forward a message from a Message Queue to a workflow in Workflows.

If it matches the filter defined in the rule inside the bus, a message entering the queue will be forwarded to the workflow. The workflow will start automatically. Before being forwarded, the message will be converted according to the template defined in the same rule as the filter.

Getting started

To get started in Yandex Cloud:

  1. Log in to the management console. If not signed up yet, navigate to the management console and follow the on-screen instructions.
  2. On the Billing page, make sure you have a billing account linked and its status is ACTIVE or TRIAL_ACTIVE. If you do not have a billing account yet, create one.
  3. If you do not have a folder yet, create one.

Create a service account

  1. In the management console, select the appropriate folder.
  2. From the list of services, select Identity and Access Management.
  3. Click Create service account.
  4. Enter a name for the service account: sa-for-eventrouter.
  5. Click Add role and select the serverless.workflows.executor, ymq.reader, and ymq.writer roles.
  6. Click Create.

Create a queue

  1. In the management console, select Message Queue.
  2. Click Create queue.
  3. Enter a name for the queue: sample-queue.
  4. Select the Standard type. Do not change other settings.
  5. Click Create.
  6. Open the queue you created.
  7. In the Overview tab, under General information, copy the queue URL as you will need it later.

Create a workflow

Note

Workflows is at the Preview stage. To gain access, submit a request in the management console.

  1. In the management console, select Serverless Integrations from the list of services.
  2. In the left-hand panel, select Workflows.
  3. In the top-right corner, click Create workflow.
  4. In the YaML specification field, add the specification as follows: 
    yawl: "0.1"
start: noopstep
steps:
  noopstep:
    noOp:
      output: |-
        \(.)
  5. Expand the Additional parameters section.
  6. In the Name field, enter the workflow name: sample-workflow.
  7. In the Service account field, select the sa-for-eventrouter service account.
  8. Click Create.

Create a bus

  1. In the management console, select Serverless Integrations from the list of services.
  2. In the left-hand panel, select EventRouter.
  3. In the top-right corner, click Create bus.
  4. Enter the bus name: sample-bus.
  5. Click Create.

Create a connector

  1. Select the sample-bus bus.
  2. Navigate to the Connectors tab.
  3. In the top-right corner, click Create connector.
  4. In the Source field, select Yandex Message Queue.
  5. Specify sample-queue in the Message queue field.
  6. In the Service account field, specify sa-for-eventrouter.
  7. Click Create.

Create a rule

  1. Select the sample-bus bus.
  2. Navigate to the Rules tab.
  3. In the top-right corner, click Create rule.
  4. Expand the Filter section and specify the following jq expression to filter messages: 
    .httpMethod == "GET" and (.headers.Host | test("^d5dm"))
  5. Under Targets, click Add.
  6. In the Type field, select Yandex Workflows.
  7. In the Workflow field, specify sample-workflow.
  8. In the Service account field, specify sa-for-eventrouter.
  9. Expand the Transformer section and specify the jq expression to convert messages: 
    {
   "message": "API gateway host is \(.headers.Host)."
}
  10. Click Create.

Send a message to the queue

Make sure the messages matching the created rule are converted and forwarded to the workflow.

  1. Install the AWS CLI.

  2. Create static access keys for the sa-for-eventrouter service account. Save the ID and secret key to a secure location. You will not be able to view the secret key parameters again after you close the window.

  3. Configure the AWS CLI:

    1. Launch the interactive profile setup:

      aws configure

    2. Specify the service account key ID you obtained earlier:

      AWS Access Key ID [****************ver_]: <service_account_key_ID>

    3. Specify the service account secret key you obtained earlier:

      AWS Secret Access Key [****************w5lb]: <service_account_secret_key>

    4. Specify the ru-central1 default region name:

      Default region name [ru-central1]: ru-central1

    5. Specify json as the default format for output data:

      Default output format [None]: json

    6. To view the current profile settings, run this command:

      aws configure list

      Result:

            Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                <not set>             None    None
access_key     ****************aBc1 shared-credentials-file
secret_key     ****************DeF2 shared-credentials-file
    region              ru-central1      config-file    ~/.aws/config

  4. Send the first message to sample-queue using the previously saved queue URL:

    aws sqs send-message \
  --message-body '{"httpMethod":"GET","headers":{"Host":"h6ds1lb3s0df********.k7******.apigw.yandexcloud.net"}}' \
  --endpoint https://message-queue.api.cloud.yandex.net/ \
  --queue-url <queue_URL>

    Result:

    {
    "MD5OfMessageBody": "c37859ba35a9958be041467c********",
    "MessageId": "f845****-9260****-7527****-f4b0****",
    "SequenceNumber": "0"
}

  5. Make sure the filter you specified in the rule stopped the message from going through the bus:

    1. In the management console, select Serverless Integrations from the list of services.
    2. In the left-hand panel, select Workflows.
    3. Navigate to the Executions tab. You should not see any completed runs on the page.

  6. Send the second message to sample-queue using the previously saved queue URL:

    aws sqs send-message \
  --message-body '{"httpMethod":"GET","headers":{"Host":"d5dm1lba80md********.i9******.apigw.yandexcloud.net"}}' \
  --endpoint https://message-queue.api.cloud.yandex.net/ \
  --queue-url <queue_URL>

    Result:

    {
    "MD5OfMessageBody": "c37859ba35a9958be041467c********",
    "MessageId": "f845****-9260****-7527****-f4b0****",
    "SequenceNumber": "0"
}

  7. Make sure the filter you specified in the rule allowed the message to go through the bus and then the message was converted according to the template and forwarded to the workflow:

    1. In the management console, select Serverless Integrations from the list of services.
    2. In the left-hand panel, select Workflows.
    3. Navigate to the Executions tab. You should now see a completed run on the page.
    4. Select the completed run.
    5. Make sure the Input data section displays the converted message: 
      {
   "message": "API gateway host is d5dm1lba80md********.i9******.apigw.yandexcloud.net."
}

What's next

Previous
Workflows
Next
All guides