azure-sdk-for-js/sdk/eventgrid/eventgrid-namespaces

Azure Event Grid Namespaces client library for JavaScript

Azure Event Grid is a cloud-based service that provides reliable event delivery at massive scale.

Use the client library to Send events to Event Grid Namespaces

Key links:

• Source code
• Package (NPM)
• API reference documentation
• Product documentation
• Samples

Getting started

Currently supported environments

• LTS versions of Node.js
• Latest versions of Safari, Chrome, Edge, and Firefox.

See our support policy for more details.

Prerequisites

• An Azure subscription.
• An existing Event Grid Topic or Domain. If you need to create the resource, you can use the Azure Portal or Azure CLI.

If you use the Azure CLI, replace <your-resource-group-name> and <your-resource-name> with your own unique names:

Create an Event Grid Topic

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Create an Event Grid Domain

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Install the @azure/eventgrid-namespaces package

Install the Azure Event Grid Namespaces client library for JavaScript with npm:

npm install @azure/eventgrid-namespaces

Create and authenticate Namespace clients

To create a client object to access the Event Grid Namespaces API, you will need the endpoint of your Event Grid topic and a credential. The Event Grid Namespaces clients can use an Access Key.

You can find the endpoint for your Event Grid topic either in the Azure Portal or by using the Azure CLI snippet below:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Using an Access Key

Use the Azure Portal to browse to your Event Grid resource and retrieve an Access Key, or use the Azure CLI snippet below:

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

Once you have an API key and endpoint, you can use the AzureKeyCredential class to authenticate the client as follows:

const { EventGridSenderClient, EventGridReceiverClient, AzureKeyCredential } = require("@azure/eventgrid-namespaces");

const eventGridSenderClient = new EventGridSenderClient(
  "<endpoint>",
  new AzureKeyCredential("<Access Key>")
);

const eventGridReceiverClient = new EventGridReceiverClient(
  "<endpoint>",
  new AzureKeyCredential("<Access Key>")
);

Azure EventGrid provides integration with Azure Active Directory (Azure AD) for identity-based authentication of requests. With Azure AD, you can use role-based access control (RBAC) to grant access to your Azure Event Grid resources to users, groups, or applications.

To send events to a topic or domain with a TokenCredential, the authenticated identity should have the "EventGrid Data Sender" role assigned.

With the @azure/identity package, you can seamlessly authorize requests in both development and production environments. To learn more about Azure Active Directory, see the @azure/identity README.

For example, use can use DefaultAzureCredential to construct a client which will authenticate using Azure Active Directory:

const { EventGridSenderClient, EventGridReceiverClient } = require("@azure/eventgrid-namespaces");
const { DefaultAzureCredential } = require("@azure/identity");

const eventGridSenderClient = new EventGridSenderClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<topicName>"
);

const eventGridReceiverClient = new EventGridReceiverClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<topicName>",
  "<subscriptionName>"
);

Key concepts

Sending and Receiving Events

EventGridSenderClient can be used for sending events to an Event Grid. You can initialize it as:

const eventGridSenderClient = new EventGridSenderClient(
  "<endpoint>",
  new AzureKeyCredential("<API Key>"),
  "<topicName>"
);

EventGridReceiverClient can be used for receiving events from an Event Grid. You can initialize it as:

const eventGridReceiverClient = new EventGridReceiverClient(
  "<endpoint>",
  new AzureKeyCredential("<API Key>"),
  "<topicName>",
  "<subscriptionName>"
);

Distributed Tracing and Cloud Events

This library supports distributed tracing using @azure/core-tracing. When using distributed tracing, this library will create a span during a send operation. In addition, when sending events using the Cloud Events 1.0 schema, the SDK will add distributed tracing metadata to the events using the Distributed Tracing extension. The values for the traceparent and tracestate extension properties correspond to the traceparent and tracestate headers from the HTTP request which sends the events. If an event already has a traceparent extension property it is not updated.

Event Grid on Kubernetes

This library has been tested and validated on Kubernetes using Azure Arc.

Examples

Publish an Event to an Event Grid Topic

const { EventGridSenderClient, AzureKeyCredential } = require("@azure/eventgrid-namespaces");

const client = new EventGridSenderClient(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  "<topicName>"
);

const cloudEvent: CloudEvent = {
  type: "example",
  source: "https://example.com",
  id: `singleEventIdV210001`,
  time: new Date(),
  data: {
    resourceUri: "https://dummyurl.com",
  },
  specversion: "1.0",
};
// Publish the Cloud Event
await client.sendEvents(cloudEvent);

Troubleshooting

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

For more detailed instructions on how to enable the logs, you can look at the @azure/logger package docs.

Next steps

Please take a look at the samples directory for detailed examples on how to use this library.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

Related projects

• Microsoft Azure SDK for Javascript