Skip to content

Commit 05533d3

Browse files
PMEds28PMEds28
authored
Merge pull request #103060 from johndowns/patch-10
Add documentation for Event Grid output binding
2 parents b747f49 + 724fbf6 commit 05533d3

File tree

2 files changed

+258
-17
lines changed

2 files changed

+258
-17
lines changed

‎articles/azure-functions/functions-bindings-event-grid.md

Lines changed: 256 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,29 @@
11
---
2-
title: Event Grid trigger for Azure Functions
2+
title: Azure Event Grid bindings for Azure Functions
33
description: Understand how to handle Event Grid events in Azure Functions.
44
author: craigshoemaker
55

66
ms.topic: reference
7-
ms.date: 09/04/2018
7+
ms.date: 02/03/2020
88
ms.author: cshoe
9+
ms.custom: fasttrack-edit
910
---
1011

11-
# Event Grid trigger for Azure Functions
12+
# Azure Event Grid bindings for Azure Functions
1213

1314
This article explains how to handle [Event Grid](../event-grid/overview.md) events in Azure Functions. For details on how to handle Event Grid messages in an HTTP end point, read [Receive events to an HTTP endpoint](../event-grid/receive-events.md).
1415

1516
Event Grid is an Azure service that sends HTTP requests to notify you about events that happen in *publishers*. A publisher is the service or resource that originates the event. For example, an Azure blob storage account is a publisher, and [a blob upload or deletion is an event](../storage/blobs/storage-blob-event-overview.md). Some [Azure services have built-in support for publishing events to Event Grid](../event-grid/overview.md#event-sources).
1617

17-
Event *handlers* receive and process events. Azure Functions is one of several [Azure services that have built-in support for handling Event Grid events](../event-grid/overview.md#event-handlers). In this article, you learn how to use an Event Grid trigger to invoke a function when an event is received from Event Grid.
18+
Event *handlers* receive and process events. Azure Functions is one of several [Azure services that have built-in support for handling Event Grid events](../event-grid/overview.md#event-handlers). In this article, you learn how to use an Event Grid trigger to invoke a function when an event is received from Event Grid, and to use the output binding to send events to an [Event Grid custom topic](../event-grid/post-to-custom-topic.md).
1819

1920
If you prefer, you can use an HTTP trigger to handle Event Grid Events; see [Receive events to an HTTP endpoint](../event-grid/receive-events.md). Currently, you can't use an Event Grid trigger for an Azure Functions app when the event is delivered in the [CloudEvents schema](../event-grid/cloudevents-schema.md#azure-functions). Instead, use an HTTP trigger.
2021

2122
[!INCLUDE [intro](../../includes/functions-bindings-intro.md)]
2223

2324
## Packages - Functions 2.x and higher
2425

25-
The Event Grid trigger is provided in the [Microsoft.Azure.WebJobs.Extensions.EventGrid](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid) NuGet package, version 2.x. Source code for the package is in the [azure-functions-eventgrid-extension](https://github.com/Azure/azure-functions-eventgrid-extension/tree/v2.x) GitHub repository.
26+
The Event Grid bindings are provided in the [Microsoft.Azure.WebJobs.Extensions.EventGrid](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid) NuGet package, version 2.x. Source code for the package is in the [azure-functions-eventgrid-extension](https://github.com/Azure/azure-functions-eventgrid-extension/tree/v2.x) GitHub repository.
2627

2728
[!INCLUDE [functions-package-v2](../../includes/functions-package-v2.md)]
2829

@@ -32,7 +33,11 @@ The Event Grid trigger is provided in the [Microsoft.Azure.WebJobs.Extensions.Ev
3233

3334
[!INCLUDE [functions-package](../../includes/functions-package.md)]
3435

35-
## Example
36+
## Trigger
37+
38+
Use the function trigger to respond to an event sent to an Event Grid topic.
39+
40+
## Trigger - example
3641

3742
# [C#](#tab/csharp)
3843

@@ -62,7 +67,7 @@ namespace Company.Function
6267
}
6368
```
6469

65-
For more information, see Packages, [Attributes](#attributes), [Configuration](#configuration), and [Usage](#usage).
70+
For more information, see Packages, [Attributes](#trigger---attributes), [Configuration](#trigger---configuration), and [Usage](#trigger---usage).
6671

6772
### Version 1.x
6873

@@ -123,7 +128,7 @@ public static void Run(EventGridEvent eventGridEvent, ILogger log)
123128
}
124129
```
125130

126-
For more information, see Packages, [Attributes](#attributes), [Configuration](#configuration), and [Usage](#usage).
131+
For more information, see Packages, [Attributes](#trigger---attributes), [Configuration](#trigger---configuration), and [Usage](#trigger---usage).
127132

128133
### Version 1.x
129134

@@ -280,7 +285,7 @@ In the [Java functions runtime library](/java/api/overview/azure/functions/runti
280285

281286
---
282287

283-
## Attributes
288+
## Trigger - attributes
284289

285290
# [C#](#tab/csharp)
286291

@@ -312,11 +317,11 @@ Attributes are not supported by Python.
312317

313318
# [Java](#tab/java)
314319

315-
The [EventGridTrigger](https://github.com/Azure/azure-functions-java-library/blob/master/src/main/java/com/microsoft/azure/functions/annotation/EventGridTrigger.java) annotation allows you to declaratively configure an Event Grid binding by providing configuration values. See the [example](#example) and [configuration](#configuration) sections for more detail.
320+
The [EventGridTrigger](https://github.com/Azure/azure-functions-java-library/blob/master/src/main/java/com/microsoft/azure/functions/annotation/EventGridTrigger.java) annotation allows you to declaratively configure an Event Grid binding by providing configuration values. See the [example](#trigger---example) and [configuration](#trigger---configuration) sections for more detail.
316321

317322
---
318323

319-
## Configuration
324+
## Trigger - configuration
320325

321326
The following table explains the binding configuration properties that you set in the *function.json* file. There are no constructor parameters or properties to set in the `EventGridTrigger` attribute.
322327

@@ -326,7 +331,7 @@ The following table explains the binding configuration properties that you set i
326331
| **direction** | Required - must be set to `in`. |
327332
| **name** | Required - the variable name used in function code for the parameter that receives the event data. |
328333

329-
## Usage
334+
## Trigger - usage
330335

331336
# [C#](#tab/csharp)
332337

@@ -366,11 +371,11 @@ The Event Grid instance is available via the parameter configured in the *functi
366371

367372
# [Java](#tab/java)
368373

369-
The Event Grid event instance is available via the parameter associated to the `EventGridTrigger` attribute, typed as an `EventSchema`. See the [example](#example) for more detail.
374+
The Event Grid event instance is available via the parameter associated to the `EventGridTrigger` attribute, typed as an `EventSchema`. See the [example](#trigger---example) for more detail.
370375

371376
---
372377

373-
## Event schema
378+
## Trigger - event schema
374379

375380
Data for an Event Grid event is received as a JSON object in the body of an HTTP request. The JSON looks similar to the following example:
376381

@@ -408,7 +413,7 @@ For explanations of the common and event-specific properties, see [Event propert
408413

409414
The `EventGridEvent` type defines only the top-level properties; the `Data` property is a `JObject`.
410415

411-
## Create a subscription
416+
## Trigger - create a subscription
412417

413418
To start receiving Event Grid HTTP requests, create an Event Grid subscription that specifies the endpoint URL that invokes the function.
414419

@@ -508,7 +513,7 @@ For more information, see [Authorization keys](functions-bindings-http-webhook-t
508513

509514
Alternatively, you can send an HTTP PUT to specify the key value yourself.
510515

511-
## Local testing with viewer web app
516+
## Trigger - local testing with viewer web app
512517

513518
To test an Event Grid trigger locally, you have to get Event Grid HTTP requests delivered from their origin in the cloud to your local machine. One way to do that is by capturing requests online and manually resending them on your local machine:
514519

@@ -582,6 +587,241 @@ The Event Grid trigger function executes and shows logs similar to the following
582587
583588
![Sample Event Grid trigger function logs](media/functions-bindings-event-grid/eg-output.png)
584589
590+
## Output
591+
592+
Use the Event Grid output binding to write events to a custom topic. You must have a valid [access key for the custom topic](../event-grid/security-authentication.md#custom-topic-publishing).
593+
594+
> [!NOTE]
595+
> The Event Grid output binding does not support shared access signatures (SAS tokens). You must use the topic's access key.
596+
597+
Make sure the required package references are in place before you try to implement an output binding.
598+
599+
> [!IMPORTANT]
600+
> The Event Grid output binding is only available for Functions 2.x and higher.
601+
602+
# [C#](#tab/csharp)
603+
604+
The following example shows a [C# function](functions-dotnet-class-library.md) that writes a message to an Event Grid custom topic, using the method return value as the output:
605+
606+
```csharp
607+
[FunctionName("EventGridOutput")]
608+
[return: EventGrid(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
609+
public static EventGridEvent Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
610+
{
611+
return new EventGridEvent("message-id", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0");
612+
}
613+
```
614+
615+
The following example shows how to use the `IAsyncCollector` interface to send a batch of messages.
616+
617+
```csharp
618+
[FunctionName("EventGridAsyncOutput")]
619+
public static async Task Run(
620+
[TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
621+
[EventGrid(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]IAsyncCollector<EventGridEvent> outputEvents,
622+
ILogger log)
623+
{
624+
for (var i = 0; i < 3; i++)
625+
{
626+
var myEvent = new EventGridEvent("message-id-" + i, "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0");
627+
await outputEvents.AddAsync(myEvent);
628+
}
629+
}
630+
```
631+
632+
# [C# Script](#tab/csharp-script)
633+
634+
The following example shows the Event Grid output binding data in the *function.json* file.
635+
636+
```json
637+
{
638+
"type": "eventGrid",
639+
"name": "outputEvent",
640+
"topicEndpointUri": "MyEventGridTopicUriSetting",
641+
"topicKeySetting": "MyEventGridTopicKeySetting",
642+
"direction": "out"
643+
}
644+
```
645+
646+
Here's C# script code that creates one event:
647+
648+
```cs
649+
#r "Microsoft.Azure.EventGrid"
650+
using System;
651+
using Microsoft.Azure.EventGrid.Models;
652+
using Microsoft.Extensions.Logging;
653+
654+
public static void Run(TimerInfo myTimer, out EventGridEvent outputEvent, ILogger log)
655+
{
656+
outputEvent = new EventGridEvent("message-id", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0");
657+
}
658+
```
659+
660+
Here's C# script code that creates multiple events:
661+
662+
```cs
663+
#r "Microsoft.Azure.EventGrid"
664+
using System;
665+
using Microsoft.Azure.EventGrid.Models;
666+
using Microsoft.Extensions.Logging;
667+
668+
public static void Run(TimerInfo myTimer, ICollector<EventGridEvent> outputEvent, ILogger log)
669+
{
670+
outputEvent.Add(new EventGridEvent("message-id-1", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0"));
671+
outputEvent.Add(new EventGridEvent("message-id-2", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0"));
672+
}
673+
```
674+
675+
# [JavaScript](#tab/javascript)
676+
677+
The following example shows the Event Grid output binding data in the *function.json* file.
678+
679+
```json
680+
{
681+
"type": "eventGrid",
682+
"name": "outputEvent",
683+
"topicEndpointUri": "MyEventGridTopicUriSetting",
684+
"topicKeySetting": "MyEventGridTopicKeySetting",
685+
"direction": "out"
686+
}
687+
```
688+
689+
Here's JavaScript code that creates a single event:
690+
691+
```javascript
692+
module.exports = async function (context, myTimer) {
693+
var timeStamp = new Date().toISOString();
694+
695+
context.bindings.outputEvent = {
696+
id: 'message-id',
697+
subject: 'subject-name',
698+
dataVersion: '1.0',
699+
eventType: 'event-type',
700+
data: "event-data",
701+
eventTime: timeStamp
702+
};
703+
context.done();
704+
};
705+
```
706+
707+
Here's JavaScript code that creates multiple events:
708+
709+
```javascript
710+
module.exports = function(context) {
711+
var timeStamp = new Date().toISOString();
712+
713+
context.bindings.outputEvent = [];
714+
715+
context.bindings.outputEvent.push({
716+
id: 'message-id-1',
717+
subject: 'subject-name',
718+
dataVersion: '1.0',
719+
eventType: 'event-type',
720+
data: "event-data",
721+
eventTime: timeStamp
722+
});
723+
context.bindings.outputEvent.push({
724+
id: 'message-id-2',
725+
subject: 'subject-name',
726+
dataVersion: '1.0',
727+
eventType: 'event-type',
728+
data: "event-data",
729+
eventTime: timeStamp
730+
});
731+
context.done();
732+
};
733+
```
734+
735+
# [Python](#tab/python)
736+
737+
The Event Grid output binding is not available for Python.
738+
739+
# [Java](#tab/java)
740+
741+
The Event Grid output binding is not available for Java.
742+
743+
---
744+
745+
## Output - attributes and annotations
746+
747+
# [C#](#tab/csharp)
748+
749+
For [C# class libraries](functions-dotnet-class-library.md), use the [EventGridAttribute](https://github.com/Azure/azure-functions-eventgrid-extension/blob/dev/src/EventGridExtension/OutputBinding/EventGridAttribute.cs) attribute.
750+
751+
The attribute's constructor takes the name of an app setting that contains the name of the custom topic, and the name of an app setting that contains the topic key. For more information about these settings, see [Output - configuration](#output---configuration). Here's an `EventGrid` attribute example:
752+
753+
```csharp
754+
[FunctionName("EventGridOutput")]
755+
[return: EventGrid(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
756+
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
757+
{
758+
...
759+
}
760+
```
761+
762+
For a complete example, see [Output - C# example](#output).
763+
764+
# [C# Script](#tab/csharp-script)
765+
766+
Attributes are not supported by C# Script.
767+
768+
# [JavaScript](#tab/javascript)
769+
770+
Attributes are not supported by JavaScript.
771+
772+
# [Python](#tab/python)
773+
774+
The Event Grid output binding is not available for Python.
775+
776+
# [Java](#tab/java)
777+
778+
The Event Grid output binding is not available for Java.
779+
780+
---
781+
782+
## Output - configuration
783+
784+
The following table explains the binding configuration properties that you set in the *function.json* file and the `EventGrid` attribute.
785+
786+
|function.json property | Attribute property |Description|
787+
|---------|---------|----------------------|
788+
|**type** | n/a | Must be set to "eventGrid". |
789+
|**direction** | n/a | Must be set to "out". This parameter is set automatically when you create the binding in the Azure portal. |
790+
|**name** | n/a | The variable name used in function code that represents the event. |
791+
|**topicEndpointUri** |**TopicEndpointUri** | The name of an app setting that contains the URI for the custom topic, such as `MyTopicEndpointUri`. |
792+
|**topicKeySetting** |**TopicKeySetting** | The name of an app setting that contains an access key for the custom topic. |
793+
794+
[!INCLUDE [app settings to local.settings.json](../../includes/functions-app-settings-local.md)]
795+
796+
> [!IMPORTANT]
797+
> Ensure that you set the value of the `TopicEndpointUri` configuration property to the name of an app setting that contains the URI of the custom topic. Do not specify the URI of the custom topic directly in this property.
798+
799+
## Output - usage
800+
801+
# [C#](#tab/csharp)
802+
803+
Send messages by using a method parameter such as `out EventGridEvent paramName`. To write multiple messages, you can use `ICollector<EventGridEvent>` or
804+
`IAsyncCollector<EventGridEvent>` in place of `out EventGridEvent`.
805+
806+
# [C# Script](#tab/csharp-script)
807+
808+
Send messages by using a method parameter such as `out EventGridEvent paramName`. In C# script, `paramName` is the value specified in the `name` property of *function.json*. To write multiple messages, you can use `ICollector<EventGridEvent>` or
809+
`IAsyncCollector<EventGridEvent>` in place of `out EventGridEvent`.
810+
811+
# [JavaScript](#tab/javascript)
812+
813+
Access the output event by using `context.bindings.<name>` where `<name>` is the value specified in the `name` property of *function.json*.
814+
815+
# [Python](#tab/python)
816+
817+
The Event Grid output binding is not available for Python.
818+
819+
# [Java](#tab/java)
820+
821+
The Event Grid output binding is not available for Java.
822+
823+
---
824+
585825
## Next steps
586826

587827
> [!div class="nextstepaction"]

‎includes/functions-bindings.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ ms.service: azure-functions
44
ms.topic: include
55
ms.date: 09/04/2018
66
ms.author: glenga
7+
ms.custom: fasttrack-edit
78
---
89
This table shows the bindings that are supported in the major versions of the Azure Functions runtime:
910

@@ -12,7 +13,7 @@ This table shows the bindings that are supported in the major versions of the Az
1213
| ---- | :-: | :-: | :------: | :---: | :----: |
1314
| [Blob storage](../articles/azure-functions/functions-bindings-storage-blob.md) |✔|✔|✔|✔|✔|
1415
| [Cosmos DB](../articles/azure-functions/functions-bindings-documentdb.md) |✔|✔|✔|✔|✔|
15-
| [Event Grid](../articles/azure-functions/functions-bindings-event-grid.md) |✔|✔|✔| | |
16+
| [Event Grid](../articles/azure-functions/functions-bindings-event-grid.md) |✔|✔|✔| |✔|
1617
| [Event Hubs](../articles/azure-functions/functions-bindings-event-hubs.md) |✔|✔|✔| |✔|
1718
| [HTTP & webhooks](../articles/azure-functions/functions-bindings-http-webhook.md) |✔|✔|✔| |✔|
1819
| [IoT Hub](../articles/azure-functions/functions-bindings-event-iot.md) |✔|✔|✔| |✔|

0 commit comments

Comments
 (0)