diff --git a/articles/azure-functions/durable/durable-functions-event-publishing.md b/articles/azure-functions/durable/durable-functions-event-publishing.md index 861c6aa0e4bb6..0a335b5e1493c 100644 --- a/articles/azure-functions/durable/durable-functions-event-publishing.md +++ b/articles/azure-functions/durable/durable-functions-event-publishing.md @@ -249,7 +249,7 @@ The following list explains the lifecycle events schema: ## How to test locally -To test locally, read [Local testing with viewer web app](../event-grid-how-tos.md#local-testing-with-viewer-web-app). You can also use the *ngrok* utility as shown in [this tutorial](../functions-event-grid-blob-trigger.md#start-local-debugging). +To test locally, read [Local testing with viewer web app](../event-grid-how-tos.md#local-testing-with-viewer-web-app). You can also use the a tunneling utility as shown in [this tutorial](../functions-event-grid-blob-trigger.md#start-local-debugging). ## Next steps diff --git a/articles/azure-functions/event-grid-how-tos.md b/articles/azure-functions/event-grid-how-tos.md index 674a8352b388a..5b8ccd82a6bc3 100644 --- a/articles/azure-functions/event-grid-how-tos.md +++ b/articles/azure-functions/event-grid-how-tos.md @@ -129,7 +129,7 @@ To test an Event Grid trigger locally, you have to get Event Grid HTTP requests When you're done testing, you can use the same subscription for production by updating the endpoint. Use the [`az eventgrid event-subscription update`](/cli/azure/eventgrid/event-subscription#az-eventgrid-event-subscription-update) Azure CLI command. -You can also use the *ngrok* utility to forward remote requests to your locally running functions. For more information, see [this tutorial](./functions-event-grid-blob-trigger.md#start-local-debugging). +You can also use the *ngrok* or *tunnelmole* utilities to forward remote requests to your locally running functions. For more information, see [this tutorial](./functions-event-grid-blob-trigger.md#start-local-debugging). ### Create a viewer web app diff --git a/articles/azure-functions/functions-event-grid-blob-trigger.md b/articles/azure-functions/functions-event-grid-blob-trigger.md index b2bffe9ce2b13..3e2b02337e362 100644 --- a/articles/azure-functions/functions-event-grid-blob-trigger.md +++ b/articles/azure-functions/functions-event-grid-blob-trigger.md @@ -19,7 +19,7 @@ This article shows how to create a function that runs based on events raised whe > * Create a container in blob storage. > * Create an event-driven Blob Storage triggered function. > * Create an event subscription to a blob container. -> * Debug locally using ngrok by uploading files. +> * Debug locally using tunnelmole or ngrok by uploading files. > * Deploy to Azure and create a filtered event subscription. ::: zone pivot="programming-language-javascript,programming-language-typescript" @@ -43,7 +43,7 @@ This article shows how to create a function that runs based on events raised whe ::: zone pivot="programming-language-java" [!INCLUDE [functions-requirements-visual-studio-code-java](../../includes/functions-requirements-visual-studio-code-java.md)] ::: zone-end -+ The [ngrok](https://ngrok.com/) utility, which provides a way for Azure to call into your locally running function. ++ The [tunnelmole](https://tunnelmole.com/docs) or [ngrok](https://ngrok.com/) utilities, which provides a way for Azure to call into your locally running function. + [Azure Storage extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestorage) for Visual Studio Code, minimally version 5.x. @@ -351,7 +351,7 @@ After you create the function, in the function.json configuration file, add `"so ## Start local debugging -Event Grid validates the endpoint URL when you create an event subscription in the Azure portal. This validation means that before you can create an event subscription for local debugging, your function must be running locally with remote access enabled by the ngrok utility. If your local function code isn't running and accessible to Azure, you won't be able to create the event subscription. +Event Grid validates the endpoint URL when you create an event subscription in the Azure portal. This validation means that before you can create an event subscription for local debugging, your function must be running locally with remote access enabled by the tunnelmole or ngrok utility. If your local function code isn't running and accessible to Azure, you won't be able to create the event subscription. ### Determine the blob trigger endpoint @@ -380,56 +380,65 @@ Save this path, which you'll use later to create endpoint URLs for event subscri > [!NOTE] > Because the endpoint is handling events for a Blob Storage trigger, the endpoint path includes `blobs`. The endpoint URL for an Event Grid trigger would instead have `eventgrid` in the path. -### Run ngrok +### Run Tunnelmole or ngrok -To break into a function being debugged on your machine, you must provide a way for Azure Event Grid to communicate with functions running on your local computer. +To break into a function being debugged on your machine, you must provide a way for Azure Event Grid to communicate with functions running on your local computer. The [Tunnelmole](https://tunnelmole.com) and [ngrok](https://ngrok.com/) utilities can accomplish this by forwarding external requests to a specific address and port on your local computer. -The [ngrok](https://ngrok.com/) utility forwards external requests to a randomly generated proxy server address to a specific address and port on your local computer. through to call the webhook endpoint of the function running on your machine. +Tunnelmole is a free and open source tool while ngrok is a popular closed source tool. You can select either based on your preference. -1. Start *ngrok* using the following command: +1. Start *Tunnelmole* using the following command: + + ```bash + > tmole 7071 + http://wm4a9r-ip-49-183-170-98.tunnelmole.net is forwarding to localhost:7071 + https://wm4a9r-ip-49-183-170-98.tunnelmole.net is forwarding to localhost:7071 + ``` + + In the output, you'll see two URLs, one HTTP and a HTTPS URL. It's best to use the HTTPS URL for privacy and security. Note this down as you will use it to build your endpoint URL in the next step. + + Alternatively, you can use *ngrok* to accomplish the same. ```bash - ngrok.exe http http://localhost:7071 + ngrok http http://localhost:7071 ``` As the utility starts, the command window should look similar to the following screenshot: ![Screenshot that shows the Command Prompt after starting the "ngrok" utility.](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-ngrok.png) -1. Copy the **HTTPS** URL generated when *ngrok* is run. This value is used to determine the webhook endpoint on your computer exposed using ngrok. +2. Copy the **HTTPS** URL generated when *Tunnelmole* or *ngrok* is run. This value is used to determine the webhook endpoint on your computer exposed using either of the tools. > [!IMPORTANT] -> At this point, don't stop `ngrok`. Every time you start `ngrok`, the HTTPS URL is regenerated with a different value. Because the endpoint of an event subscription can't be modified, you have to create a new event subscription every time you run `ngrok`. -> -> Unless you create an ngrok account, the maximum ngrok session time is limited to two hours. +> Do not stop `tmole` or `ngrok` at this point. Each time you start these utilities, the HTTPS URL is regenerated with a different value. As the endpoint of an event subscription cannot be modified, you have to create a new event subscription every time you run `tmole` or `ngrok`. +> For ngrok, note that unless you create an account, the maximum session time is limited to two hours. -### Build the endpoint URL +### Build the Endpoint URL -The endpoint used in the event subscription is made up of three different parts, a prefixed server name, a path, and a query string. The following table describes these parts: +The endpoint used in the event subscription is made up of three different parts: a prefixed server name, a path, and a query string. The following table describes these parts: -| URL part | Description | +| URL Part | Description | | --- | --- | -| Prefix and server name | When your function runs locally, the server name with an `https://` prefix comes from the **Forwarding** URL generated by *ngrok*. In the localhost URL, the *ngrok* URL replaces `http://localhost:7071`. When running in Azure, you'll instead use the published function app server, which is usually in the form `https://.azurewebsites.net`. | -| Path | The path portion of the endpoint URL comes from the localhost URL copied earlier, and looks like `/runtime/webhooks/blobs` for a Blob Storage trigger. The path for an Event Grid trigger would be `/runtime/webhooks/EventGrid` | -| Query string | For all languages including .NET Isolated the `functionName=Host.Functions.BlobTriggerEventGrid` parameter, except for .NET In-process which should be `functionName=BlobTriggerEventGrid` in the query string sets the name of the function that handles the event. If you used a different name for your function, you'll need to change this value. An access key isn't required when running locally. When running in Azure, you'll also need to include a `code=` parameter in the URL, which contains a key that you can get from the portal. | +| Prefix and Server Name | When your function runs locally, the server name with an `https://` prefix comes from the **Forwarding** URL generated by *Tunnelmole* or *ngrok*. In the localhost URL, the *Tunnelmole* or *ngrok* URL replaces `http://localhost:7071`. When running in Azure, you'll instead use the published function app server, which is usually in the form `https://.azurewebsites.net`. | +| Path | The path part of the endpoint URL comes from the `localhost` URL copied earlier, and looks like `/runtime/webhooks/blobs` for a Blob Storage trigger. The path for an Event Grid trigger would be `/runtime/webhooks/EventGrid`. | +| Query String | All languages including .NET Isolated should set `functionName=Host.Functions.BlobTriggerEventGrid` in the query string, except for .NET In-process which should be `functionName=BlobTriggerEventGrid`. If you used a different name for your function, you'll need to change this value. An access key isn't required when running locally. When in Azure, you'll also need to include a `code=` parameter in the URL, which contains a key which you can get from the portal. | -The following screenshot shows an example of how the final endpoint URL should look when using a Blob Storage trigger named `BlobTriggerEventGrid`: +The following screenshot shows an example of how the final endpoint URL should look like when using a Blob Storage trigger named `BlobTriggerEventGrid`: ::: zone pivot="programming-language-csharp" # [Isolated process](#tab/isolated-process) - ![Endpoint selection](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-event-subscription-endpoint-selection-qualified.png) +![Endpoint selection](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-event-subscription-endpoint-selection-qualified.png) # [In-process](#tab/in-process) - ![Endpoint selection](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-event-subscription-endpoint-selection.png) +![Endpoint selection](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-event-subscription-endpoint-selection.png) --- ::: zone-end ::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-powershell,programming-language-python,programming-language-java" - ![Endpoint selection](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-event-subscription-endpoint-selection-qualified.png) +![Endpoint selection](./media/functions-event-grid-blob-trigger/functions-event-grid-local-dev-event-subscription-endpoint-selection-qualified.png) ::: zone-end -### Start debugging +### Start Debugging -With ngrok already running, start your local project as follows: +With tunnelmole or ngrok already running, start your local project as follows: 1. Set a breakpoint in your function on the line that handles logging. @@ -446,11 +455,11 @@ With ngrok already running, start your local project as follows: Press **F5** to start a debugging session. ::: zone-end -With your code running and ngrok forwarding requests, it's time to create an event subscription to the blob container. +With your code running and tunnelmole or ngrok forwarding requests, it's time to create an event subscription to the blob container. ## Create the event subscription -An event subscription, powered by Azure Event Grid, raises events based on changes in the linked blob container. This event is then sent to the webhook endpoint on your function's trigger. After an event subscription is created, the endpoint URL can't be changed. This means that after you're done with local debugging (or if you restart ngrok), you'll need to delete and recreate the event subscription. +An event subscription, powered by Azure Event Grid, raises events based on changes in the linked blob container. This event is then sent to the webhook endpoint on your function's trigger. After an event subscription is created, the endpoint URL can't be changed. This means that after you're done with local debugging (or if you restart tunnelmole or ngrok), you'll need to delete and recreate the event subscription. 1. In Visual Studio Code, choose the Azure icon in the Activity bar. In **Resources**, expand your subscription, expand **Storage accounts**, right-click the storage account you created earlier, and select **Open in portal**. @@ -469,7 +478,7 @@ An event subscription, powered by Azure Event Grid, raises events based on chang | **System Topic Name** | *samples-workitems-blobs* | Name for the topic, which represents the container. The topic is created with the first subscription, and you'll use it for future event subscriptions. | | **Filter to Event Types** | *Blob Created*| | **Endpoint Type** | **Web Hook** | The blob storage trigger uses a web hook endpoint. You would use Azure Functions for an Event Grid trigger. | - | **Endpoint** | Your ngrok-based URL endpoint | Use the ngrok-based URL endpoint that you determined earlier. | + | **Endpoint** | Your tunnelmole or ngrok-based URL endpoint | Use the tunnelmole or ngrok-based URL endpoint that you determined earlier. | 1. Select **Confirm selection** to validate the endpoint URL. @@ -477,7 +486,7 @@ An event subscription, powered by Azure Event Grid, raises events based on chang ## Upload a file to the container -With the event subscription in place and your code project and ngrok still running, you can now upload a file to your storage container to trigger your function. You can upload a file from your computer to your blob storage container using Visual Studio Code. +With the event subscription in place and your code project and tunnelmole or ngrok still running, you can now upload a file to your storage container to trigger your function. You can upload a file from your computer to your blob storage container using Visual Studio Code. 1. In Visual Studio Code, open the command palette (press F1) and type `Azure Storage: Upload Files...`. @@ -492,7 +501,7 @@ With the event subscription in place and your code project and ngrok still runni | **Select Blob Container** | **samples-workitems** | This value is the name of the container you created in a previous step. | | **Enter the destination directory of this upload** | default | Just accept the default value of `/`, which is the container root. | -This command uploads a file from your computer to the storage container in Azure. At this point, your running ngrok instance should report that a request was forwarded. You'll also see in the func.exe output for your debugging session that your function has been started. Hopefully, at this point, your debug session is waiting for you where you set the breakpoint. +This command uploads a file from your computer to the storage container in Azure. If you are running ngrok, it should report that a request was forwarded. You'll also see in the func.exe output for your debugging session that your function has been started. Hopefully, at this point, your debug session is waiting for you where you set the breakpoint. ## Publish the project to Azure @@ -577,7 +586,7 @@ This time, you'll include the filter on the event subscription so that only JPEG 1. In the [Azure portal](https://portal.azure.com), select the **Events** option from the left menu. -1. In the **Events** window, select your old ngrok-based event subscription, select **Delete** > **Save**. This action removes the old event subscription. +1. In the **Events** window, select your old tunnelmole or ngrok-based event subscription, select **Delete** > **Save**. This action removes the old event subscription. 1. Select the **+ Event Subscription** button, and provide values from the following table into the **Basic** tab: diff --git a/articles/communication-services/how-tos/call-automation/record-every-call.md b/articles/communication-services/how-tos/call-automation/record-every-call.md index 25b976847f4a1..544c30f1d0b65 100644 --- a/articles/communication-services/how-tos/call-automation/record-every-call.md +++ b/articles/communication-services/how-tos/call-automation/record-every-call.md @@ -149,7 +149,7 @@ The Call Started event when a call start is formatted in the following way: ## Start recording -1. Create a method to handle the `CallStarted` events. This method trigger recording to start when the call started. +1. Create a method to handle the `CallStarted` events. This method triggers the start of the recording when the call starts. ```csharp @@ -178,21 +178,31 @@ The Call Started event when a call start is formatted in the following way: ### Running locally -To run the function locally, you can press `F5` in Visual Studio Code. We use [ngrok](https://ngrok.com/) to hook our locally running Azure Function with Azure Event Grid. +1. To run the function locally, please press `F5` in Visual Studio Code. You can use [Tunnelmole](https://tunnelmole.com), a free and open source tunneling tool or [ngrok](https://ngrok.com), a popular closed source tunneling tool, to connect your locally running Azure Function with Azure Event Grid. -1. Once the function is running, we configure ngrok. (You need to [download ngrok](https://ngrok.com/download) for your environment.) +#### Tunnelmole +After running the function, you can configure Tunnelmole. Follow the [Installation Guide](https://tunnelmole.com/docs/#installation) to get Tunnelmole installed. + ```bash + tmole 7071 + ``` + + Copy the Tunnelmole link provided where your function is running. + +#### ngrok +If you prefer to use ngrok, follow the below step. Remember to [download ngrok](https://ngrok.com/download) for your environment. + ```bash ngrok http 7071 ``` Copy the ngrok link provided where your function is running. -2. Configure C`allStarted` events through Event Grid within your Azure Communication Services resource. We do this using the [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli). You need the resource ID for your Azure Communication Services resource found in the Azure portal. (The resource ID looks something like:  `/subscriptions/<>/resourceGroups/<>/providers/Microsoft.Communication/CommunicationServices/<>`) +2. Configure `CallStarted` events through Event Grid within your Azure Communication Services resource. We do this using the [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli). You need the resource ID for your Azure Communication Services resource found in the Azure portal. (The resource ID looks something like: `/subscriptions/<>/resourceGroups/<>/providers/Microsoft.Communication/CommunicationServices/<>`) ```bash - az eventgrid event-subscription create --name "<>" --endpoint-type webhook --endpoint "<>/runtime/webhooks/EventGrid?functionName=<> " --source-resource-id "<>" --included-event-types Microsoft.Communication.CallStarted + az eventgrid event-subscription create --name "<>" --endpoint-type webhook --endpoint "<>/runtime/webhooks/EventGrid?functionName=<> " --source-resource-id "<>" --included-event-types Microsoft.Communication.CallStarted ``` diff --git a/articles/communication-services/how-tos/event-grid/local-testing-event-grid.md b/articles/communication-services/how-tos/event-grid/local-testing-event-grid.md index 5b4b312340aad..fd5c3eecd40e1 100644 --- a/articles/communication-services/how-tos/event-grid/local-testing-event-grid.md +++ b/articles/communication-services/how-tos/event-grid/local-testing-event-grid.md @@ -1,4 +1,5 @@ --- + title: Test your Event Grid handler locally titleSuffix: An Azure Communication Services how-to document description: In this how-to document, you can learn how to locally test your Event Grid handler for Azure Communication Services events with Postman. @@ -20,15 +21,30 @@ Testing Event Grid triggered Azure Functions locally can be complicated. You don - Install [Postman](https://www.postman.com/downloads/). - Have a running Azure Function that can be triggered by Event Grid. If you don't have one, you can follow the [quickstart](../../../azure-functions/functions-bindings-event-grid-trigger.md?tabs=in-process%2Cextensionv3&pivots=programming-language-javascript) to create one. -The Azure Function can be running either in Azure if you want to test it with some test events or if you want to test the entire flow locally (press `F5` in Visual Studio Code to run it locally). If you want to test the entire flow with an externally triggered webhook, you need to use [ngrok](https://ngrok.com/) to expose your locally running Azure Function -to the public, allowing it to be triggered by internet sources (as an example from Azure Event WebHooks). Configure ngrok by running the command: +The Azure Function can be running either in Azure if you want to test it with some test events or if you want to test the entire flow locally (press `F5` in Visual Studio Code to run it locally). If you want to test the entire flow with an externally triggered webhook, you need to use a tunneling tool to expose your locally running Azure Function to the public, allowing it to be triggered by internet sources (as an example from Azure Event WebHooks). + +We recommend using [Tunnelmole](https://tunnelmole.com), a free and open source tunneling tool, or [ngrok](https://ngrok.com/), a popular closed source tunneling tool. + +### Tunnelmole Configuration +1. First, install Tunnelmole by following the [Installation Guide](https://tunnelmole.com/docs/#installation). For most use cases, this will be done with a single copied/pasted terminal command, but there are advanced options available including building from source, or using Tunnelmole as a dependency in JavaScript/TypeScript code. +2. Run `tmole 7071` (replace `7071` with your listening port number if different). In the output, you'll get the URLs (one http and another https) of your tunnel. Be sure to use the https URL. + + ```bash + +tmole 7071 + + ``` + +### ngrok Configuration +To configure ngrok, run the following command: ```bash -ngrok http 7071 +ngrok http 7071 ``` -It is worth remembering that exposing development resources publicly might not be considered as secure. That is why you can also run the entire workflow locally without ngrok by invoking requests to: + +It's worth remembering that exposing development resources publicly might not be considered secure. That's why you can also run the entire workflow locally without a tunneling tool by invoking requests to: ``` http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname} ``` @@ -40,13 +56,11 @@ http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname} ![Screenshot of Postman body configuration.](media/postman-body.png) 2. Select the `POST` method. - -3. Enter the URL of your Azure Function. Can either be the URL of the Azure Function running in Azure or the ngrok URL if you're running it locally. Ensure that you add the function name at the end of the URL: `/runtime/webhooks/EventGrid?functionName=<>`. - -4. Select the `Body` tab and select `raw` and `JSON` from the dropdown. In the body, you add a test schema for the event you want to trigger. For example, if you're testing an Azure Function that is triggered by receiving SMS events, you add the following: +3. Enter the URL of your Azure Function. This can either be the URL of the Azure Function running in Azure, the Tunnelmole URL, or the ngrok URL if you're running it locally. Ensure that you add the function name at the end of the URL: `/runtime/webhooks/EventGrid?functionName=<>`. +4. Select the `Body` tab and select `raw` and `JSON` from the dropdown. In the body, add a test schema for the event you want to trigger. For example, if you're testing an Azure Function that's triggered by receiving SMS events, you add the following: ```json - + { "id": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e", "topic": "/subscriptions/50ad1522-5c2c-4d9a-a6c8-67c11ecb75b8/resourcegroups/acse2e/providers/microsoft.communication/communicationservices/{communication-services-resource-name}", @@ -63,7 +77,7 @@ http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname} "metadataVersion": "1", "eventTime": "2020-09-18T00:27:47Z" } - + ``` You can find more information for the different event types used for Azure Communication Services in the [documentation](../../../event-grid/event-schema-communication-services.md). @@ -79,4 +93,4 @@ http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname} ![Screenshot of Postman send button.](media/postman-send.png) - At this point, an event should trigger in your Azure Function. You can verify the event by looking at the execution of your Azure Function. You can then validate that the function is doing its job correctly. + At this point, an event should trigger in your Azure Function. You can verify the event by observing the execution of your Azure Function. You can then validate that the function is performing its task correctly. diff --git a/articles/communication-services/quickstarts/sms/includes/receive-sms-js.md b/articles/communication-services/quickstarts/sms/includes/receive-sms-js.md index c4fc39c150a01..f26e4728fbdef 100644 --- a/articles/communication-services/quickstarts/sms/includes/receive-sms-js.md +++ b/articles/communication-services/quickstarts/sms/includes/receive-sms-js.md @@ -12,7 +12,6 @@ ms.topic: include ms.custom: include file --- - Event Grid provides out of the box support for Azure Functions, making it easy to set up an event listener without the need to deal with the complexity of parsing headers or debugging webhooks. Using the out of the box trigger, we can set up an Azure Function that runs each time an event is detected that matches the trigger. In this document, we focus on SMS received triggers. ## Setting up our local environment @@ -109,9 +108,19 @@ From here, the possibilities are endless. From responding to a message with a pr ## Running locally -To run the function locally, press `F5` in Visual Studio Code. We use [ngrok](https://ngrok.com/) to hook our locally running Azure Function with Azure Event Grid. +To run the function locally, press `F5` in Visual Studio Code. To hook our locally running Azure Function with Azure Event Grid, we can use the free and open source tunneling tool, Tunnelmole, or the popular closed source tunneling tool, ngrok. -1. Once the function is running, we configure ngrok. (You need to [download ngrok](https://ngrok.com/download) for your environment.) +### Running with Tunnelmole +1. Once the function is running, we configure Tunnelmole. (To use Tunnelmole, first install it following the [Installation Guide](https://tunnelmole.com/docs/#installation)) + + ```bash + tmole 7071 + ``` + + Copy the HTTPS Tunnelmole link provided where your function is running. + +### Running with ngrok +1. Alternatively, you can use ngrok. (To use ngrok, you need to [download ngrok](https://ngrok.com/download) for your environment.) ```bash ngrok http 7071 @@ -142,3 +151,4 @@ az eventgrid event-subscription update --name "<>" --en Since we are updating the event subscription we created for local testing, make sure to use the same event subscription name you used above. You can test by sending an SMS to the phone number you have procured through Azure Communication Services resource. +